Configure metadata with your SDK in order to populate dimensions to search, filter and segment your video performance metrics.
One of Mux Data's core concepts are dimensions, which are the attributes of a video view that you can use to search, filter, and segment your video performance metrics.
While some of these dimensions are tracked automatically, Mux Data allows you to provide details about the video and environment that either can't be detected automatically, can't be accessed if the video fails to load, or should be overridden.
Each dimension corresponds with a metadata key which can be used to set these values. While all metadata details except for env_key are optional, some may be necessary to calculate certain metrics and you'll see more helpful results as you include more.
Each dimension is either considered basic or advanced. All dimensions are available for the standard retention period of 100 days. Long Term Metrics only support basic dimensions. If you are interested in Long Term Metrics, please reach out to Mux Support.
Long Term Metrics are available on the Custom Media Plan. Learn more about Mux Data Plans.
Many of Mux Data's dimensions are scoped to specific categories. Based on the category, they may have different behavior in terms of how these details are updated.
video_) describe the current video that's playing and are all reset automatically when changing the video. This metadata might come from your internal CMS or video management system.player_) describe the player configuration that's being used and should be set whenever monitoring is started on a new player. They do not reset when the video is changed.There are three types of dimensions based on their availability.
Tracking: Enables tracking of additional metrics but are unavailble as dimensions.
Limited: Appear as attributes of a view on the individual view page as well as in the API.
Full: Can be used as filters and breakdowns in aggregate reports, in the video view page and in the API.
The following dimensions are the most important fields whose metadata keys you should populate in order to get the basic functionality from Mux Data.
Note about viewer_user_id
For viewer_user_id you should not use any value that is personally identifiable on its own (such as email address, username, etc.). Instead, you should supply an anonymized viewer ID which you have stored within your own system.
| Dimension Name | Key Name | Unit | Type | Level | Description |
|---|---|---|---|---|---|
| Environment | env_key | Unique ID | Required | N/A | Your env key from the Mux dashboard. This field ensures that your data goes into the correct environment. Note this was previously named property_key |
| Video ID | video_id | Text | Full | basic | Your internal ID for the video. Defaults to the Mux External ID if enabled for Assets and Livestreams hosted by Mux. |
| Video Title | video_title | Text | Full | basic | Title of the video being played (e.g.: Awesome Show: Pilot). Defaults to the Mux Video Title if enabled for Assets and Livestreams hosted by Mux. |
| Viewer ID | viewer_user_id | Unique ID | Full | adv | An ID representing the viewer who is watching the stream. Use this to look up video views for an individual viewer. If no value is specified, a unique ID will be generated by the SDK. Note: You should not use any value that is personally identifiable on its own (such as email address, username, etc.). Instead, you should supply an anonymized viewer ID which you have stored within your own system. |
The following dimensions can be set manually using the metadata key name and will be reported by Mux Data.
| Dimension Name | Key Name | Unit | Type | Level | Description |
|---|---|---|---|---|---|
| Audio Codec | audio_codec | Text | Full | adv | The codec of the audio that played during the view. |
| CDN | video_cdn | Text | Full | basic | The Content Delivery Network used to deliver the video. If using an SDK that supports CDN header extraction, this value will be auto-populated. |
| CDN Edge PoP | view_cdn_edge_pop | Text | Full | adv | Region where the CDN edge point of presence server is located or other origin server identification. |
| Content Type | video_content_type | Text | Full | basic | The type of content: short, movie, episode, clip, trailer, or event |
| Client Application Name | client_application_name | Text | Full | adv | Name of the customer application that the viewer is using to watch the content. e.g 'OurBrand iOS App' |
| Client Application Version | client_application_version | Text | Full | adv | Version of the customer application that the viewer is using to view the content. |
| DRM Type | view_drm_type | Text | Full | adv | The DRM SDK or service that is used for the video playback, such as widevine or playready |
| DRM Level | view_drm_level | Text | Full | adv | Security level of the specific DRM type. Some DRM types do not have levels. |
| Duration | video_duration | Milliseconds | Limited | adv | The length of the video in milliseconds |
| Dynamic Range Type | video_dynamic_range_type | Text | Full | adv | The format or type of dynamic range available on the video during the view. |
| Encoding Variant | video_encoding_variant | Text | Full | adv | Allows you to compare different encoders or encoding settings. This could designate the encoder used (e.g. x264, hevc, or av1), the preset used (e.g. av1-0, av1-4, or av1-8), or other properties of the encoding you want to track. |
| Experiment Name | experiment_name | Text | Full | adv | You can use this field to separate views into different experiments, if you would like to filter by this dimension later. This should be a string value, but your account is limited to a total of 10 unique experiment names, so be sure that this value is not generated dynamically or randomly. |
| Origin | view_cdn_origin | Text | Full | adv | Identifying name of the Content Origin or Region where the Origin server is located. |
| Page Type | page_type | Text | Full | adv | Provide the context of the page for more specific analysis. Values include watchpage, iframe, or leave empty. watchpage — A web page that is dedicated to playing a specific video (for example youtube.com/watch/ID or hulu.com/watch/ID) iframe — An iframe specifically used to embed a player on different sites/pages |
| Player Initialization Time | player_init_time | Milliseconds since Epoch | Tracking | N/A | If you are explicitly loading your player in page (perhaps as a response to a user interaction), include the timestamp (milliseconds since Jan 1 1970) when you initialize the player (or for HTML5 video, when right before you add the element to the DOM) in order to accurately track page load time and player startup time. |
| Player Name | player_name | Text | Full | basic | You can provide a name for the player (e.g. My Player) if you want to compare different configurations or types of players around your site or application. This is different from the player software (e.g. Video.js), which is tracked automatically by the SDK. |
| Player Version | player_version | Text | Full | adv | As you make changes to your player you can compare how new versions of your player perform (e.g. 1.2.0). This is not the player software version (e.g. Video.js 5.0.0), which is tracked automatically by the SDK. |
| Sub Property ID | sub_property_id | Text | Full | basic | A sub property is an optional way to group data within a property. For example, sub properties may be used by a video platform to group data by its own customers, or a media company might use them to distinguish between its many websites. |
| Time Shift Enabled | view_time_shift_enabled | Text | Full | adv | Boolean indicating if this view had time_shift enabled. |
| Used Captions | player_captions_enabled | Text | Full | adv | Boolean indicating if the player used captions at any time during the view. |
| Used PiP | player_pip_enabled | Text | Full | adv | Boolean indicating if the player used Picture in Picture at any time during the view. |
| Video Affiliate | video_affiliate | Text | Full | adv | Affiliate station that the viewer is watching or associated with the viewer. |
| Video Brand | video_brand | Text | Full | adv | Brand associated with the video or the brand of the streaming platform the viewer is using to watch the video. |
| Video Codec | video_codec | Text | Full | adv | The codec of the video that played during the view. |
| Video Language | video_language_code | Text | Limited | adv | The audio language of the video, assuming it's unchangeable after playing. |
| Video Producer | video_producer | Text | Limited | adv | The producer of the video title |
| Video Series | video_series | Text | Full | basic | The series of the video (e.g.: Season 1) |
| Video Stream Type | video_stream_type | Text | Full | basic | The type of video stream (e.g: live or on-demand) |
| View Session ID | view_session_id | Unique ID | Full | adv | An ID that can be used to correlate the view with platform services upstream such as CDN or origin logs. |
| Video Variant Name | video_variant_name | Text | Limited | adv | Allows you to monitor issues with the files of specific versions of the content, for example different audio translations or versions with hard-coded/burned-in subtitles. |
| Video Variant ID | video_variant_id | Text | Limited | adv | Your internal ID for a video variant |
| View Dropped | view_dropped | Boolean | Full | adv | Boolean indicating whether the view was finalized without an explicit viewend event. |
| Viewer Plan | viewer_plan | Text | Full | adv | Name of the viewer's customer-specific plan, product, or subscription. |
| Viewer Plan Status | viewer_plan_status | Text | Full | adv | Status pertaining to that viewer's subscription plan (e.g. subscriber, non-subscriber, SVOD, AVOD, free, standard, premium). |
| Viewer Plan Category | viewer_plan_category | Text | Full | adv | Category of the viewer's customer-specific subscription plan (e.g. bundle-type, subscription-campaign-id). |
| Custom Dimensions | custom_1 - 10 | Text | Full | adv | Customer-defined metadata |
The following dimensions are populated automatically where the data is supported by the SDK. This data can be overridden by the SDK client implementation using the metadata key name, if needed.
| Dimension Name | Key Name | Unit | Type | Level | Description |
|---|---|---|---|---|---|
| Autoplay | player_autoplay | Boolean | Full | adv | Indicates whether the player was set to autoplay the video or not. This tracks whether the video has autoplay=true set; it is not always able to tell if the browser disregarded the setting, otherwise prevented the video from playing, or if the video play was triggered via a script. |
| Browser | browser | Text | Full | basic | Browser used for the video view (Safari, Chrome, etc.). On Android and iOS applications this defaults to the bundle identifier. NB: (viewer_application_name) |
| Browser Version | browser_version | Version | Full | adv | Browser version (e.g. 66.0.3359.158). On Android and iOS applications this defaults to the bundle version. NB: (viewer_application_version) |
| CDN | cdn | Text | Full | adv | CDN delivering the video, either detected by Mux (via response X-CDN header) or specified in the view as video_cdn. Specifying a video_cdn value on the view does not override the detected value, if the X-CDN value is set on the segment response headers. |
| Connection Type | viewer_connection_type | Text | Full | adv | The type of connection used by the player, as reported by the client when available: cellular, other, wifi, wired |
| Device Brand | viewer_device_manufacturer | Text | Full | basic | Device Manufacturer (e.g. Apple, Microsoft, etc.) |
| Device Category | viewer_device_category | Text | Full | basic | The form factor of the device: camera, car browser, console, desktop, feature phone, peripheral, phone, portable media player, smart display, smart speaker, tablet, tv, wearable |
| Device Model | viewer_device_model | Text | Full | adv | Device Model (e.g. iPhone11,2) |
| Device Name | viewer_device_name | Text | Full | basic | Device Name (e.g. iPhone 12) |
| Error Code | player_error_code | Text | Full | basic | Error code encountered by the player during playback. |
| Operating System | operating_system | Text | Full | basic | Operating System (iOS, Windows, etc.) NB: (viewer_os_family) |
| Operating System Version | operating_system_version | Version | Full | adv | Operating System version (e.g. 10.6) NB: (viewer_os_version) |
| Page URL | page_url | URL | Limited | adv | Page URL |
| Player Height | player_height | Integer | Limited | adv | Height of the player as displayed, in logical pixels |
| Player Instance ID | player_instance_id | Unique ID | Limited | adv | Identifies the instance of the Player class that is created when a video is initialized |
| Player Language | player_language | Text | Limited | adv | Player's text language |
| Player Poster | player_poster | URL | Limited | adv | The image shown as the pre-visualization before play |
| Player Software | player_software_name | Text | Full | basic | Player Software being used to play the Video (e.g. Video.js, JW Player, etc.). Note this was previously named player_software |
| Player Software Version | player_software_version | Text | Full | adv | Player Software Version (e.g. 2.45.5) |
| Player Width | player_width | Integer | Limited | adv | Width of the player as displayed, in logical pixels |
| Preload | player_preload | Boolean | Limited | adv | Specifies if the player was configured to load the video when the page loads. |
| Remote Played | player_remote_played | Boolean | Full | adv | If the video is remote played to AirPlay as specified by the SDK. |
| Source Height | player_source_height | Integer | Limited | adv | Height of the source video being sent to the player, in pixels |
| Source Width | player_source_width | Integer | Limited | adv | Width of the source video being as seen by the player |
| Source Type | source_type | Text | Limited | basic | Format of the source, as determined by the player. E.g. application/dash+xml, x-application/mpegUrl, mp4, etc. |
| Used Full Screen | used_fullscreen | Boolean | Limited | adv | Indicates whether the viewer used full screen to watch the video. |
| Video Creator ID | video_creator_id | Text | Full | adv | A unique identifier for the creator of the video. Defaults to the Mux Creator ID if enabled for Assets and Livestreams hosted by Mux. |
The following dimensions are populated automatically by the SDK, and cannot be overriden by the SDK client implementation.
| Dimension Name | Unit | Type | Level | Description |
|---|---|---|---|---|
| ASN | Boolean | Full | adv | The Autonomous System Number (ASN) representing the network provider of the viewer. |
| Continent Code | Text | Full | basic | The continent from which the video was accessed, represented as a code. |
| Country | Text | Full | adv | The country from which the video was accessed, represented as a country code. |
| Exited Before Video Start | Boolean | Full | basic | Indicates whether the viewer exited before the video started playing. |
| Mux Asset ID | Unique ID | Full | basic | A unique identifier for the video asset being played. |
| Mux Live Stream ID | Unique ID | Full | basic | The unique identifier of the live stream being played. |
| Mux Playback ID | Text | Full | basic | A unique identifier for the video view. |
| Mux Plugin | Text | Full | adv | The name of the Mux plugin used by the video player. |
| Mux Plugin Version | Text | Full | adv | The version of the Mux plugin used by the video player. |
| Playback Business Exception | Boolean | Full | adv | Indicates whether a business rule-related issue caused playback failure. |
| Playback Failure | Boolean | Full | adv | Indicates whether the playback failed for any reason. |
| Region | Text | Full | adv | The specific region or state where the video was accessed. |
| Source Hostname | Text | Full | adv | The hostname of the video source, such as the CDN or media server. |
| Video Startup Failure | Boolean | Full | basic | Indicates whether the video failed to start due to an error. |
| Video Startup Business Exception | Boolean | Full | adv | Indicates whether a business rule-related issue caused a video startup failure. |
| View Has Ad | Boolean | Full | basic | Indicates whether the video view included an ad. |
Metadata is normally set using code in the SDK configuration. However, some video metadata can also be set using Session Data key/value pairs in the HLS manifest. This method makes it easier to communicate values to the Mux player SDK without having to side-channel information to the client or change client-side code in order to configure metadata for a view.
Some common use cases where this is helpful are, for example, setting a view session id that comes from a backend system which can be used to associate a playback view with the requests that were made to a CDN or being able to easily capture which experiments a viewer is participating in without having to communicate that to the player.
HLS Session Data, which is represented in an HLS master playlist using the EXT-X-SESSION-DATA tag, is a key/value pair that can be read by the player. When the master playlist is loaded into a video player integrated with a Mux Data SDK that supports extracting Session Data, the Session Data keys that use the io.litix.data prefix will be included in the Mux Data view as dimension metadata the same as if you had configured the value from the SDK configuration code.
Note about HLS Session Data for developers using Mux Video:
This feature is intended for developers using their own custom video delivery pipeline. HLS Session Data is set by Mux Video when videos are viewed; injecting your own HLS Session Data into Mux Video content is not currently supported.
The Session Data tags are interpreted as follows from the master playlist:
Tag: #EXT-X-SESSION-DATA
Key: DATA-ID="io.litix.data.[dimension_name]"
Value: VALUE="dimension value"The dimension names available to be set from the master playlist:
video_*custom_*experiment_nameview_session_idviewer_user_idThe following is an example of Session Data tags in a master playlist:
#EXTM3U
#EXT-X-VERSION:7
#EXT-X-INDEPENDENT-SEGMENTS
#EXT-X-SESSION-DATA:DATA-ID="io.litix.data.experiment_name",VALUE="abr_test:true"
#EXT-X-SESSION-DATA:DATA-ID="io.litix.data.view_session_id",VALUE="12345ABCD"
#EXT-X-STREAM-INF:BANDWIDTH=2516370,AVERAGE-BANDWIDTH=2516370,CODECS="mp4a.40.2,avc1.640020",RESOLUTION=1280x720
...The Session Data tags contained in a master playlist would result in the Experiment Name dimension set to abr_test:true and View Session ID dimension set to 12345ABCD.
We're aware of a crash that may occur in AVPlayer Data SDK versions 2.12.0 - 3.5.0 when processing HLS Session Data that is prefixed with io.litix.data. AVPlayer Data SDK integrations that process HLS Session Data not prefixed with io.litix.data are not affected. Custom integrations that use the Objective-C MuxCore SDK and do not depend on the AVPlayer Data SDK are not affected.
In iOS and Android SDKs, names are converted to lowerCamelCase setters and getters. For example, to set the Video Stream Type field in iOS or Android, use videoStreamType instead of video_stream_type.
In the Objective-C SDKs, options are provided via the MUXSDKCustomerPlayerData, MUXSDKCustomerVideoData, MUXSDKCustomerViewData, and MUXSDKCustomData objects. See the header directories for a complete list of names:
In the Java SDK, options are provided via the CustomerPlayerData, CustomerVideoData, and CustomData objects. Use your IDE to inspect these objects' API.