# Configure the Media Player data model
> Configure the Media Player dbt package for tracking video and audio playback metrics with customizable variables.
> Source: https://docs.snowplow.io/docs/modeling-your-data/modeling-your-data-with-dbt/dbt-configuration/media-player/
> Documentation index: https://docs.snowplow.io/llms.txt

This page helps you configure the Snowplow Media Player dbt package. You can customize variables, generate configuration code, and set output schemas.

## Package configuration variables (v1.0.2)

This package utilizes a set of variables that are configured to recommended values for optimal performance of the models. Depending on your use case, you might want to override these values by adding to your `dbt_project.yml` file.

> **Note: Variable name prefix**
>
> All variables in Snowplow packages start with `snowplow__` but we have removed these in the below tables for brevity.

### Warehouse and tracker

| Variable | Description | Default |
| --- | --- | --- |
| `database` | The database that contains your atomic events table. | `target.database` |
| `atomic_schema` | The schema (dataset for BigQuery) that contains your atomic events table. | `atomic` |
| `events_table` | The name of the table that contains your atomic events. | `events` |
| `percent_progress_boundaries` | The list of percent progress values. It needs to be aligned with the values being tracked by the tracker. It is worth noting that the more these percent progress boundaries are being tracked the more accurate the play time calculations become. Please note that tracking 100% is unnecessary as there is a separate `ended` event which the model equates to achieving 100% and it also gets included automatically to this list, in case it is not added (you can refer to the helper macro `get_percentage_boundaries` ([source](https://snowplow.github.io/dbt-snowplow-media-player/#!/macro/macro.snowplow_media_player.get_percentage_boundaries)) for details). | `[10, 25, 50, 75]` |
| `dev_target_name` | The [target name](https://docs.getdbt.com/docs/core/connect-data-platform/profiles.yml) of your development environment as defined in your `profiles.yml` file. See the [Manifest Tables](/docs/modeling-your-data/modeling-your-data-with-dbt/package-mechanics/manifest-tables/) section for more details. | `dev` |
| `grant_schema_usage` | Enables granting usage on schemas interacted with on a dbt run | `true` |
| `grant_select_to` | A list of users to grant select to all tables created by this package to. | `[]` |

### Operation and logic

| Variable | Description | Default |
| --- | --- | --- |
| `start_date` | The date to start processing events from in the package on first run or a full refresh, based on `collector_tstamp` | `2020-01-01` |
| `valid_play_sec` | The minimum number of seconds that a media play needs to last to consider that interaction a valid play. The default is 30 seconds (based on the YouTube standard) but it can be modified here, if needed. | `30` |
| `allow_refresh` | Used as the default value to return from the `allow_refresh()` macro. This macro determines whether the manifest tables can be refreshed or not, depending on your environment. See the [Manifest Tables](/docs/modeling-your-data/modeling-your-data-with-dbt/package-mechanics/manifest-tables/) section for more details. | `false` |
| `backfill_limit_days` | The maximum numbers of days of new data to be processed since the latest event processed. Please refer to the [incremental logic](/docs/modeling-your-data/modeling-your-data-with-dbt/package-mechanics/incremental-processing/#package-state) section for more details. | `30` |
| `days_late_allowed` | The maximum allowed number of days between the event creation and it being sent to the collector. Exists to reduce lengthy table scans that can occur as a result of late arriving data. | `3` |
| `session_identifiers` | A list of key:value dictionaries which contain all of the contexts and fields where your session identifiers are located. For each entry in the list, if your map contains the `schema` value `atomic`, then this refers to a field found directly in the atomic `events` table. If you are trying to introduce a context/entity with an identifier in it, the package will look for the context in your events table with the name specified in the `schema` field. It will use the specified value in the `field` key as the field name to access. For Redshift/Postgres, using the `schema` key the package will try to find a table in your `snowplow__events_schema` schema with the same name as the `schema` value provided, and join that. If multiple fields are specified, the package will try to coalesce all fields in the order specified in the list. For a better understanding of the advanced usage of this variable, please see the [Custom Identifiers](/docs/modeling-your-data/modeling-your-data-with-dbt/package-features/custom-identifiers/) section for more details. | `[{"schema": "contexts_com_snowplowanalytics_snowplow_medi...` |
| `session_sql` | This allows you to override the `session_identifiers` SQL, to define completely custom SQL in order to build out a session identifier for your events. If you are interested in using this instead of providing identifiers through the `session_identifiers` variable, please see the [Custom Identifiers](/docs/modeling-your-data/modeling-your-data-with-dbt/package-features/custom-identifiers/) section for more details on how to do that. | `""` |
| `user_identifiers` | A list of key:value dictionaries which contain all of the contexts and fields where your user identifiers are located. For each entry in the list, if your map contains the `schema` value `atomic`, then this refers to a field found directly in the atomic `events` table. If you are trying to introduce a context/entity with an identifier in it, the package will look for the context in your events table with the name specified in the `schema` field. It will use the specified value in the `field` key as the field name to access. For Redshift/Postgres, using the `schema` key the package will try to find a table in your `snowplow__events_schema` schema with the same name as the `schema` value provided, and join that. If multiple fields are specified, the package will try to coalesce all fields in the order specified in the list. For a better understanding of the advanced usage of this variable, please see the [Custom Identifiers](/docs/modeling-your-data/modeling-your-data-with-dbt/package-features/custom-identifiers/) section for more details. | `[{"schema" : "atomic", "field" : "domain_userid", "prefix...` |
| `user_sql` | This allows you to override the `user_identifiers` SQL, to define completely custom SQL in order to build out a user identifier for your events. If you are interested in using this instead of providing identifiers through the `user_identifiers` variable, please see the [Custom Identifiers](/docs/modeling-your-data/modeling-your-data-with-dbt/package-features/custom-identifiers/) section for more details on how to do that. | `""` |
| `license_accepted` | Use this field to accept the Snowplow Personal and Academic License or specify that you have a commercial agreement with Snowplow. | `false` |
| `session_timestamp` | Determines which timestamp to use for optimizing the queries in our sessionization logic. This should be set to the same timestamp as the field you partition your events table on. This does not affect how sessions are processed and all events will be processed as described in our [sessionization](/docs/modeling-your-data/modeling-your-data-with-dbt/package-mechanics/incremental-processing) logic. | `collector_tstamp` |
| `complete_play_rate` | The rate to set what percentage of a media needs to be played in order to consider that complete. 0.99 (=99%) is set as a default value here but it may be increased to 1 (or decreased) depending on the use case. | `0.99` |
| `max_media_pv_window` | The number of hours that needs to pass before new page_view level media player metrics from the `snowplow_media_player_base` table are safe to be processed by the model downstream in the `snowplow_media_player_media_stats` table. Please note that even if new events are added later on ( e.g. new `percentprogress` events are fired indicating potential replay) and the `snowplow_media_player_base` table is changed, the model will not update them in the media_stats table, therefore it is safer to set as big of a number as still convenient for analysis and reporting. | `10` |
| `max_session_days` | The maximum allowed session length in days. For a session exceeding this length, all events after this limit will stop being processed. Exists to reduce lengthy table scans that can occur due to long sessions which are usually a result of bots. | `3` |
| `session_lookback_days` | Number of days to limit scan on `snowplow_media_player_base_sessions_lifecycle_manifest` manifest. Exists to improve performance of model when we have a lot of sessions. Should be set to as large a number as practical. | `730` |
| `upsert_lookback_days` | Number of days to look back over the incremental derived tables during the upsert. Where performance is not a concern, should be set to as long a value as possible. Having too short a period can result in duplicates. Please see the [Snowplow Optimized Materialization](/docs/modeling-your-data/modeling-your-data-with-dbt/package-mechanics/optimized-upserts/) section for more details. | `30` |
| `surrogate_key_treat_nulls_as_empty_strings` | Passed through to `dbt_utils` to match legacy surrogate key behavior. | `true` |

### Entities (contexts), filters, and logs

| Variable | Description | Default |
| --- | --- | --- |
| `app_id` | A list of `app_id`s to filter the events table on for processing within the package. | `[ ] (no filter applied)` |
| `enable_web_events` | Whether to use the web contexts for web media events in the processing (based on the web page context). | `true` |
| `enable_mobile_events` | Whether to use the mobile contexts for mobile media events in the processing (based on the client session and screen view context). | `false` |
| `enable_ad_quartile_event` | Set to `true` if [ad quartile events](https://github.com/snowplow/iglu-central/blob/master/schemas/com.snowplowanalytics.snowplow.media/ad_quartile_event/jsonschema/1-0-0) are tracked during media ad playback. | `false` |
| `enable_media_ad` | Set to `true` if the [media ad context schema](https://github.com/snowplow/iglu-central/blob/master/schemas/com.snowplowanalytics.snowplow.media/ad/jsonschema/1-0-0) is enabled. This is tracked by our latest JavaScript and mobile trackers along with ad events. | `false` |
| `enable_media_ad_break` | Set to `true` if the [media ad-break context schema](https://github.com/snowplow/iglu-central/blob/master/schemas/com.snowplowanalytics.snowplow.media/ad_break/jsonschema/1-0-0) is enabled. This is tracked by our latest JavaScript and mobile trackers when ad breaks are tracked along with ad events. | `false` |
| `enable_media_player_v1` | Set to `true` if the [version 1 of the media player context schema](https://github.com/snowplow/iglu-central/blob/master/schemas/com.snowplowanalytics.snowplow/media_player/jsonschema/1-0-0) is enabled. This schema was used in our older media plugins on the JavaScript tracker. It is not tracked in the latest versions. | `false` |
| `enable_media_player_v2` | Set to `true` if the [version 2 of the media player context schema](https://github.com/snowplow/iglu-central/blob/master/schemas/com.snowplowanalytics.snowplow/media_player/jsonschema/2-0-0) is enabled. This is tracked by our latest JavaScript and mobile trackers. | `true` |
| `enable_media_session` | Set to `true` if the [media session context schema](https://github.com/snowplow/iglu-central/blob/master/schemas/com.snowplowanalytics.snowplow.media/session/jsonschema/1-0-0) is enabled. This is tracked by our latest JavaScript and mobile trackers (optional but enabled by default). | `false` |
| `enable_whatwg_media` | Set to `true` if the [HTML5 media element context schema](https://github.com/snowplow/iglu-central/blob/master/schemas/org.whatwg/media_element/jsonschema/1-0-0) is enabled. This variable is used to handle syntax depending on whether the context fields are available in the database or not. | `false` |
| `enable_whatwg_video` | Set to `true` if the [HTML5 video element context schema](https://github.com/snowplow/iglu-central/blob/master/schemas/org.whatwg/video_element/jsonschema/1-0-0) is enabled. This variable is used to handle syntax depending on whether the context fields are available in the database or not. | `false` |
| `enable_youtube` | Set to `true` if the [YouTube context schema](https://github.com/snowplow/iglu-central/blob/master/schemas/com.youtube/youtube/jsonschema/1-0-0) is enabled. This variable is used to handle syntax depending on whether the context fields are available in the database or not. | `false` |
| `ad_views_passthroughs` | Field(s) to carry through from the events table to the `snowplow_media_player_media_ad_views` derived table. The field is from the ad view event record. Aggregation is not supported. A list of either flat column names from the events table or a dictionary with the keys `sql` for the SQL code to select the column and `alias` for the alias of the column in the output. | `[ ] (no passthroughs)` |
| `base_passthroughs` | Field(s) to carry through from the events table to the `snowplow_media_player_base` and `snowplow_media_player_plays_by_page_view` derived tables. The field is from the media base event record. Aggregation is not supported. A list of either flat column names from the events table or a dictionary with the keys `sql` for the SQL code to select the column and `alias` for the alias of the column in the output. | `[ ] (no passthroughs)` |
| `media_event_names` | A list of names for media events to include for processing. | `['media_player_event']` |

### Warehouse-specific

| Variable | Description | Default | Warehouse |
| --- | --- | --- | --- |
| `derived_tstamp_partitioned` | Boolean to enable filtering the events table on `derived_tstamp` in addition to `collector_tstamp`. | `true` | Bigquery |
| `enable_load_tstamp` | Flag to include the `load_tstamp` column in the base events this run model. This should be set to true (the default) unless you are using the Postgres loader or an RDB loader version less than 4.0.0. It must be true to use consent models on Postgres and Redshift. | `true` | Redshift |
| `entities_or_sdes` | A list of dictionaries defining the `entity` or `self-describing` event tables to join onto your base events table. Please use the tool below or see the section on [Utilizing custom contexts or SDEs](/docs/modeling-your-data/modeling-your-data-with-dbt/package-features/modeling-entities/) for details of the structure. | `[]` | Redshift |