Skip to Content
Mux Docs: Home

Make your data actionable with metadata

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 details (prepended by 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 details (prepended by 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.
  • All other details will persist until explicitly changed.

iOS/Android Metadata

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 Details

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.

High Priority Configurable Metadata

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.

NameKey NameUnitTypeDescription
Environmentenv_keyUnique IDRequiredYour env key from the Mux dashboard. Note this was previously named property_key
Video IDvideo_idTextFilterYour internal ID for the video
Video Titlevideo_titleTextFilterTitle of the video player (e.g.: 'Awesome Show: Pilot')
Viewer IDviewer_user_idUnique IDFilterAn 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.

Optional Configurable Metadata

The following metadata fields can be set manually and will be reported by Mux Data.

NameKey NameUnitTypeDescription
Experiment Nameexperiment_nameTextFilterYou 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 Typepage_typeTextFilterProvide 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 Timeplayer_init_timeMilliseconds since EpochMetricsIf 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 Nameplayer_nameTextFilterYou 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 Versionplayer_versionTextFilterAs 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 IDsub_property_idTextFilterA 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.
CDNvideo_cdnTextFilterThe Content Delivery Network used to deliver the video. If using an SDK that supports CDN header extraction, this value will be auto-populated.
Content Typevideo_content_typeTextFilterThe type of content: 'short', 'movie', 'episode', 'clip', 'trailer', or 'event'
DRM Typeview_drm_typeTextFilterThe DRM SDK or service that is used for the video playback, such as 'widevine' or 'playready'
Durationvideo_durationMillisecondsViewThe length of the video in milliseconds
Encoding Variantvideo_encoding_variantTextFilterAllows 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 Languagevideo_language_codeTextAPIThe audio language of the video, assuming it's unchangeable after playing.
Producervideo_producerTextAPIThe producer of the video title
Seriesvideo_seriesTextFilterThe series of the video (e.g.: 'Season 1')
Video Stream Typevideo_stream_typeTextFilterThe type of video stream (e.g: 'live' or 'on-demand')
Variant Namevideo_variant_nameTextAPIAllows 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 IDvideo_variant_idTextAPIYour internal ID for a video variant
View Session IDview_session_idUnique IDFilterAn ID that can be used to correlate the view with platform services upstream such as CDN or origin logs.
Custom Dimensionscustom_1 - 10TextFilterCustomer-defined metadata

Overridable 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.

NameKey NameUnitTypeDescription
BrowserbrowserTextFilterBrowser used for the video view (Safari, Chrome, etc.). On Android and iOS applications this defaults to the bundle identifier. NB: (viewer_application_name)
Browser Versionbrowser_versionVersionFilterBrowser version (e.g. 66.0.3359.158). On Android and iOS applications this defaults to the bundle version. NB: (viewer_application_version)
CDNcdnTextFilterCDN 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 Systemoperating_systemTextFilterOperating System (iOS, Windows, etc) NB: (viewer_os_family)
Operating System Versionoperating_system_versionVersionFilterOperating System version (e.g. 10.6) NB: (viewer_os_version)
Page URLpage_urlURLViewPage URL
Autoplayplayer_autoplayBooleanFilterIndicates 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 Heightplayer_heightIntegerViewHeight of the player as displayed, in logical pixels
Player Instance IDplayer_instance_idUnique IDAPIIdentifies the instance of the Player class that is created when a video is initialized
Player Languageplayer_languageTextAPIPlayer's text language
Posterplayer_posterURLAPIThe image shown as the pre-visualisation before play
Preloadplayer_preloadBooleanViewSpecifies if the player was configured to load the video when the page loads.
Remote Playedplayer_remote_playedBooleanFilterIf the video is remote played to AirPlay as specified by the SDK.
Player Softwareplayer_software_nameTextFilterPlayer Software being used to play the Video (e.g. Video.js, JW Player, etc.). Note this was previously named player_software
Player Software Versionplayer_software_versionTextFilterPlayer Software Version (e.g. 2.45.5)
Source Heightplayer_source_heightIntegerViewHeight of the source video being sent to the player, in pixels
Source Widthplayer_source_widthIntegerViewWidth of the source video being as seen by the player
Player Widthplayer_widthIntegerViewWidth of the player as displayed, in logical pixels
Source Typesource_typeTextViewFormat of the source, as determined by the player. E.g. 'dash', 'x-application/mpegUrl', 'mp4', etc.
Used Full Screenused_fullscreenBooleanViewIndicates whether the viewer used full screen to watch the video.
Connection Typeviewer_connection_typeTextFilterThe type of connection used by the player, as reported by the client when available: cellular, other, wifi, wired
Device Brandviewer_device_manufacturerTextFilterDevice Manufacturer (e.g. Apple, Microsoft)
Device Categoryviewer_device_categoryTextFilterThe form factor of the device: tv, phone, tablet, etc.
Device Modelviewer_device_modelFilterViewDevice Model (e.g. iPhone11,2)
Device Nameviewer_device_nameFilterViewDevice Name (e.g. iPhone 12)

Set Metadata with Session Data

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_name
  • view_session_id
  • viewer_user_id

The 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.

Was this page helpful?