Welcome to the new Mux Docs (currently in beta). The old version is still available here
Make your data actionable with metadata
Configure metadata with your SDK in order to search, filter and segment your video performance metrics.
In this guide:
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.
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
In the Objective-C SDKs, options are provided via the
MUXSDKCustomerViewData objects. See the header directories for a complete list of names:
In the Java SDK, options are provided via the
CustomerVideoData objects. Use your IDE to inspect these objects' API.
Metadata is used in five different ways.
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.
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.
|Environment||Unique ID||Required||Your env key from the Mux dashboard. Note this was previously named |
|Video ID||Text||Filter||Your internal ID for the video|
|Video Title||Text||Filter||Title of the video player (e.g.: 'Awesome Show: Pilot')|
|Viewer 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.
|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||Text||API||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||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||Text||Filter||You can provide a name for the 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||Text||Filter||As you make changes to your player you can compare how new versions of your player perform. This is not the player software version (e.g. Video.js 5.0.0), which is tracked automatically by the SDK.|
|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||Text||Filter||The Content Delivery Network used to deliver the video. If using am SDK that supports CDN header extraction, this value will be auto-populated.|
|Content Type||Text||API||The type of content: 'short', 'movie', 'episode', 'clip', 'trailer', or 'event'|
|Duration||Milliseconds||View||The length of the video in milliseconds|
|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||Text||API||The audio language of the video, assuming it's unchangeable after playing.|
|Producer||Text||API||The producer of the video title|
|Series||Text||Filter||The series of the video (e.g.: 'Season 1')|
|Video Stream Type||Text||Filter||The type of video stream (e.g: 'live' or 'on-demand')|
|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||Text||API||Your internal ID for a video variant|
|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.|
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.
|Browser||Text||Filter||Browser used for the video view (Safari, Chrome, etc.) NB: |
|Browser Version||Version||Filter||Browser version (eg. Chrome 66.0.3359.158) NB: |
|CDN||Text||Filter||CDN delivering the video view (either determined by Mux (network metrics), or provided as video_cdn (Custom Metadata))|
|Operating System||Text||Filter||Operating System (iOS, Windows, etc) NB: |
|Operating System Version||Version||Filter||Operating System version (eg. OS X 10.6) NB: |
|Page URL||URL||View||Page URL|
|Autoplay||Boolean||Filter||Indicates whether the player was set to autoplay the video or not. This is tracks wether the video has |
|Player Height||Integer||View||Height of the player as displayed in page, in pixels|
|Player Instance ID||Unique ID||View||Identifies the instance of the Player class that is created when a video is initialized|
|Player Language||Text||API||Player's text language|
|Poster||URL||API||The image shown as the pre-visualisation before play|
|Preload||Boolean||View||Specifies if the player was configured to load the video when the page loads.|
|Remote Played||Boolean||Filter||If the video is remote played to AirPlay as specified by the SDK.|
|Player Software||Text||Filter||Player Software being used to play the Video (eg. Video.js, JW Player, etc.)|
|Player Software Version||Text||Filter||Player Software Version (eg. 2.45.5)|
|Source Height||Integer||View||Height of the source video being sent to the player, in pixels|
|Source Width||Integer||View||Width of the source video being as seen by the player|
|Player Width||Integer||View||Width of the player as displayed in page, in pixels|
|Source Type||Text||View||Format of the source, as determined by the player. E.g. 'dash', 'x-application/mpegUrl', 'mp4', etc.|
|Used Fullscreen||Boolean||View||Indicates whether the viewer used full screen to watch the video.|
|Connection Type||Text||Filter||The type of connection used by the player, as reported by the client when available: cellular, other, wifi, wired"|
|Device Category||Text||Filter||The form factor of the device: tv, phone, tablet, etc.|
|Device Brand||Text||Filter||Device Manufacturer (e.g. Apple, Microsoft)|
|Device Name||Filter||View||Device Name (e.g. iPhone)|