The Mux Developer Hub

Welcome to the Mux developer hub. You'll find comprehensive guides and documentation to help you start working with Mux as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started

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, and MUXSDKCustomerViewData objects. See the header directories for a complete list of names:

In the Java SDK, options are provided via the CustomerPlayerData and CustomerVideoData 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_typeTextAPIProvide 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 or
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 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. 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 am SDK that supports CDN header extraction, this value will be auto-populated.
Content Typevideo_content_typeTextAPIThe type of content: 'short', 'movie', 'episode', 'clip', 'trailer', or 'event'
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.

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.)
NB: (viewer_application_name)
Browser Versionbrowser_versionVersionFilterBrowser version (eg. Chrome 66.0.3359.158)
NB: (viewer_application_version)
CDNcdnTextFilterCDN delivering the video view (either determined by Mux (network metrics), or provided as video_cdn (Custom Metadata))
Operating Systemoperating_systemTextFilterOperating System (iOS, Windows, etc)
NB: (viewer_os_family)
Operating System Versionoperating_system_versionVersionFilterOperating System version (eg. OS X 10.6)
NB: (viewer_os_version)
Page URLpage_urlURLViewPage URL
Autoplayplayer_autoplayBooleanFilterIndicates whether the player was set to autoplay the video or not. This is tracks wether the video has autoplay=true set, it is not always able to tell if the browser disregarded the setting or otherwise prevented the video from playing or if the the video play was triggered via a script.
Player Heightplayer_heightIntegerViewHeight of the player as displayed in page, in pixels
Player Instance IDplayer_instance_idUnique IDViewIdentifies 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_softwareTextFilterPlayer Software being used to play the Video (eg. Video.js, JW Player, etc.)
Player Software Versionplayer_software_versionTextFilterPlayer Software Version (eg. 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 page, in pixels
Source Typesource_typeTextViewFormat of the source, as determined by the player. E.g. 'dash', 'x-application/mpegUrl', 'mp4', etc.
Used Fullscreenused_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 Categoryviewer_device_categoryTextFilterThe form factor of the device: tv, phone, tablet, etc.
Device Brandviewer_device_manufacturerTextFilterDevice Manufacturer (e.g. Apple, Microsoft)
Device Nameviewer_device_nameFilterViewDevice Name (e.g. iPhone)

Updated 3 days ago


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.