Configure metadata with your SDK in order to search, filter and segment your video performance metrics.
Mux Data allows you to provide details about the video and environment that can't be detected automatically or if the video fails to load.
All metadata details except for env_key are optional, however you'll see more helpful results as you include more.
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.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.
Metadata is used in five different ways.
Required: env_key is a required field, and ensures that your data goes into the correct environment.
Filter: some fields are available as filters and breakdowns in aggregate reports (as well as in the API and video view page).
View: some fields appear as attributes of a view on the individual video view page (as well as in the API).
API: some fields are only available via API or data export.
Metrics: some fields enable Mux to track additional metrics.
The following metadata fields are the most important fields that you should populate in order to get the basic functionality of 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.
| Name | Key Name | Unit | Type | Description |
|---|---|---|---|---|
| Environment | env_key | Unique ID | Required | Your env key from the Mux dashboard. Note this was previously named property_key |
| Video ID | video_id | Text | Filter | Your internal ID for the video |
| Video Title | video_title | Text | Filter | Title of the video player (e.g.: Awesome Show: Pilot) |
| Viewer ID | viewer_user_id | Unique ID | Filter | 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 metadata fields can be set manually and will be reported by Mux Data.
| Name | Key Name | Unit | Type | Description |
|---|---|---|---|---|
| Experiment Name | experiment_name | Text | Filter | 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. |
| Page Type | page_type | Text | Filter | 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 | Metrics | 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 | Filter | 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 | Filter | 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 | Filter | 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. |
| CDN | video_cdn | Text | Filter | The Content Delivery Network used to deliver the video. If using an SDK that supports CDN header extraction, this value will be auto-populated. |
| Content Type | video_content_type | Text | Filter | The type of content: short, movie, episode, clip, trailer, or event |
| DRM Type | view_drm_type | Text | Filter | The DRM SDK or service that is used for the video playback, such as widevine or playready |
| Duration | video_duration | Milliseconds | View | The length of the video in milliseconds |
| Encoding Variant | video_encoding_variant | Text | Filter | 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. |
| Video Language | video_language_code | Text | API | The audio language of the video, assuming it's unchangeable after playing. |
| Producer | video_producer | Text | API | The producer of the video title |
| Series | video_series | Text | Filter | The series of the video (e.g.: Season 1) |
| Video Stream Type | video_stream_type | Text | Filter | The type of video stream (e.g: live or on-demand) |
| Variant Name | video_variant_name | Text | API | 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. |
| Variant ID | video_variant_id | Text | API | Your internal ID for a video variant |
| View Session ID | view_session_id | Unique ID | Filter | An ID that can be used to correlate the view with platform services upstream such as CDN or origin logs. |
| Custom Dimensions | custom_1 - 10 | Text | Filter | Customer-defined metadata |
The following metadata is populated automatically where the data is supported by the SDK. This data can be overridden by the SDK client implementation, if needed.
| Name | Key Name | Unit | Type | Description |
|---|---|---|---|---|
| Browser | browser | Text | Filter | 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 | Filter | 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 | Filter | 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. |
| Operating System | operating_system | Text | Filter | Operating System (iOS, Windows, etc.) NB: (viewer_os_family) |
| Operating System Version | operating_system_version | Version | Filter | Operating System version (e.g. 10.6) NB: (viewer_os_version) |
| Page URL | page_url | URL | View | Page URL |
| Autoplay | player_autoplay | Boolean | Filter | 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. |
| Player Height | player_height | Integer | View | Height of the player as displayed, in logical pixels |
| Player Instance ID | player_instance_id | Unique ID | API | Identifies the instance of the Player class that is created when a video is initialized |
| Player Language | player_language | Text | API | Player's text language |
| Poster | player_poster | URL | API | The image shown as the pre-visualization before play |
| Preload | player_preload | Boolean | View | Specifies if the player was configured to load the video when the page loads. |
| Remote Played | player_remote_played | Boolean | Filter | If the video is remote played to AirPlay as specified by the SDK. |
| Player Software | player_software_name | Text | Filter | 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 | Filter | Player Software Version (e.g. 2.45.5) |
| Source Height | player_source_height | Integer | View | Height of the source video being sent to the player, in pixels |
| Source Width | player_source_width | Integer | View | Width of the source video being as seen by the player |
| Player Width | player_width | Integer | View | Width of the player as displayed, in logical pixels |
| Source Type | source_type | Text | View | 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 | View | Indicates whether the viewer used full screen to watch the video. |
| Connection Type | viewer_connection_type | Text | Filter | 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 | Filter | Device Manufacturer (e.g. Apple, Microsoft, etc.) |
| Device Category | viewer_device_category | Text | Filter | 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 | Filter | View | Device Model (e.g. iPhone11,2) |
| Device Name | viewer_device_name | Filter | View | Device Name (e.g. iPhone 12) |
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.