Welcome to the new Mux Docs (currently in beta). The old version is still available here
- Introduction to Data
- Track your video performance
- HTML5 video element
- HLS.js
- AVPlayer
- ExoPlayer
- Dash.js
- Video.js
- JW Player (web)
- JW Player (ios)
- Android MediaPlayer
- Bitmovin player
- Akamai media player
- Ooyala player
- Shaka player
- Azure media player
- THEOplayer (web)
- THEOplayer (ios)
- Flowplayer
- Brightcove (web)
- Brightcove (ios)
- Brightcove (android)
- CTS PDK
- Chromecast
- Roku
- Samsung (Tizen)
- LG
- Setup alerts
- Make your data actionable with Metadata
- Track autoplaying videos
- Track CDN for request metrics
- Build a custom integration
- Understand metric definitions
- Export raw video view data
- Mux Data FAQs
Monitor AVPlayer
This guide walks through integration with iOS and TVOS AVPlayer player to collect video performance metrics with Mux data.
In this guide:
1Install the Mux Data SDK
1
Install the Mux Data SDK
Install `Mux-Stats-AVPlayer` and import the framework into your application.
2Initialize the monitor for your AVPlayer instance
2
Initialize the monitor for your AVPlayer instance
The Mux monitor attaches to either AVPlayerLayer or AVPlayerViewController.
3Make your data actionable
3
Make your data actionable
Use metadata fields to make the data collected by Mux actionable and useful.
4Set or update metadata after monitor
4
Set or update metadata after monitor
If you do not have all the metadata available at initializaiton time update metadata fields later.
5Advanced
5
Advanced
Depending on the details of your implementation, you may want to leverage some of the advanced options of Mux-Stats-AVPlayer.
Release notes
Release notes
Mux Data Mux-Stats-AVPlayer
supports iOS 9.0 or newer and TVOS 9.0 or newer. The Mux integration with AVPlayerViewController
and AVPlayerLayer
is built on top of Mux's core Objective-C SDK, and the full code can be seen here: muxinc/mux-stats-sdk-avplayer.
This SDK is built with XCFramework bundle type and supports Mac Catalyst.
Installing with SwiftPM
- In XCode click "File" > "Swift Packages" > "Add Package Dependency..."
- The package repository URL is
https://github.com/muxinc/mux-stats-sdk-avplayer.git
- Click
next
. - Since the
MUXSDKStats
follows SemVer, we recommend setting the "Rules" to install the latest version and choosing the option "Up to Next Major".
Note that MUXSDKStats
has a dependency on MuxCore
, so you will see that MuxCore
gets install as well.
Installing with CocoaPods
To install with CocoaPods, modify your Podfile to use frameworks by including use_frameworks!
and then add the following pods to your Podfile:
pod 'Mux-Stats-AVPlayer', '~>2.0'
This will install Mux-Stats-AVPlayer
and the latests current release of our core Objective-C Library. There will be no breaking updates in major versions, so you can safely run pod update
for future versions.
Next, add correct import statement into your application.
@import MUXSDKStats;
Get your ENV_KEY
from the Mux environments dashboard.
Env Key is different than your API token
ENV_KEY
is a client-side key used for Mux Data monitoring. These are not to be confused with API tokens which are created in the admin settings dashboard and meant to access the Mux API from a trusted server.

The example below uses monitorAVPlayerViewController
. If you are using AVPlayerLayer
, use monitorAVPlayerLayer
instead.
The playerName
parameter is a string that identifies this instance of your player. When calling destroyPlayer
or videoChangeForPlayer
later on, you will need this string. Each instance of a player that runs simultaneously in your application should have a different playerName
.
let playName = "iOS AVPlayer"
let playerData = MUXSDKCustomerPlayerData(environmentKey: "ENV_KEY");
// insert player metadata
let videoData = MUXSDKCustomerVideoData();
// insert video metadata
MUXSDKStats.monitorAVPlayerViewController(self, withPlayerName: playName, playerData: playerData!, videoData: videoData);
// if you're using AVPlayerLayer instead of AVPlayerViewController use this instead:
// MUXSDKStats.monitorAVPlayerLayer(self, withPlayerName: playName, playerData: playerData!, videoData: videoData);
For more complete examples check the 3 demo apps in the repo. There is one demo app for iOS objective-c, one for iOS swift and another one for TVOS.
After you've integrated, start playing a video in your player. A few minutes after you stop watching, you'll see the results in your Mux data dashboard. Login to the dashboard and find the environment that corresponds to your env_key
and look for video views.
The only required field is env_key
. But without some more metadata the metrics in your dashboard will lack the necessary information to take meaningful actions. Metadata allows you to search and filter on important fields in order to diagnose issues and optimize the playback experience for your end users.
Metadata fields are provided via the MUXSDKCustomerPlayerData
and MUXSDKCustomerVideoData
objects.
For the full list of properties view the header files for this interfaces:
For more details about each property, view the Make your data actionable guide.
let playName = "iOS AVPlayer"
let playerData = MUXSDKCustomerPlayerData(environmentKey: "ENV_KEY");
playerData.viewerUserId = "1234"
playerData.experimentName = "player_test_A"
// note that the 'playerName' field here is unrelated to the 'playName' variable above
playerData.playerName = "My Main Player"
playerData.playerVersion = "1.0.0"
let videoData = MUXSDKCustomerVideoData();
videoData.videoId = "abcd123"
videoData.videoTitle = "My Great Video"
videoData.videoSeries = "Weekly Great Videos"
videoData.videoDuration = 120000 // in milliseconds
videoData.videoIsLive = false
videoData.videoCdn = "cdn"
MUXSDKStats.monitorAVPlayerViewController(self, withPlayerName: playName, playerData: playerData!, videoData: videoData);
// if you're using AVPlayerLayer instead of AVPlayerViewController use this instead:
// MUXSDKStats.monitorAVPlayerLayer(self, withPlayerName: playName, playerData: playerData!, videoData: videoData);
There are some cases where you may not have the full set of metadata until after the video playback has started. In this case, you should omit the values when you first call monitorAVPlayer*
. Then, once you have the metadata, you can update the metadata with the updateCustomerDataForPlayer
method.
// Sometime later before the player is destroyed you can do this:
// The player name ("iOS AVPlayer" in this example) should be a player that
// you have already called one of the `monitorAvPlayer` methods with
let videoData = MUXSDKCustomerVideoData()
videoData.videoTitle = "Video title"
videoData.videoId = @"bigbuckbunny"
// In this example we are updating videoData, but the same can be done
// for updating playerData
MUXSDKStats.updateCustomerData(forPlayer: "iOS AVPlayer", with: nil, with: videoData)
Changing the Video
There are two cases where the underlying tracking of the video view need to be reset. First, when you load a new source URL into an existing player, and secondly when the program within a singular stream changes (such as a program within a live stream).
Note: You do not need to change the video info when changing to a different source of the same video content (e.g. different resolution or video format).
New source
When you change to a new video (in the same player) you need to update the information that Mux knows about the current video. Examples of when this is needed are:
- The player advances to the next video in a playlist
- The user selects a different video to play
This is done by calling videoChangeForPlayer:
which will remove all previous video data and reset all metrics for the video view. You can include any metadata when changing the video but you should only need to update the values that start with video_
.
It is required to call videoChangeForPlayer:
immediately before telling the player which new source to play. This recommendation changed in v1.2.0
.
It is also required to call player.play
after replacing the current item.
If you have new player data you instead call videoChangeForPlayer
.
// Example of changing the AVPlayerItem let videoData = MUXSDKCustomerVideoData() videoData.videoId = "abcd123" videoData.videoTitle = "My Great Video" videoData.videoSeries = "Weekly Great Videos" videoData.videoDuration = 120000 // in milliseconds videoData.videoIsLive = false videoData.videoCdn = "cdn" MUXSDKStats.videoChange(forPlayer: "AVPlayer", with: videoData) player.replaceCurrentItem(with: AVPlayerItem(url: url!)) // calling `play()` here is necessary player.play()
New program (in single stream)
In some cases, you may have the program change within a stream, and you may want to track each program as a view on its own. An example of this is a live stream that streams multiple programs back to back, with no interruptions.
In this case, call programChangeForPlayer:withVideoData:
. This will remove all previous video data and reset all metrics for the video view, creating a new video view. You can include any metadata when changing the video but you should only need to update the values that start with video
.
Usage with Google Interactive Media Ads (IMA)
If you are using Google Interactive Media Ads, and specifically either the iOS sdk GoogleAds-IMA-iOS-SDK
or the TvOS SDK GoogleAds-IMA-tvOS-SDK
then we have another library that integrates for tracking ad playback events.
You should have a fully functioning GoogleAds-IMA integration working in your iOS or TvOS application before adding the Mux tracking. To add Mux ad tracking follow these steps:
- Add the
pod 'Mux-Stats-Google-IMA' ~> '0.6
to your Podfile and runpod install
- import
Mux_Stats_Google_IMA
- After initializing the Mux monitor with
monitorAVPlayerViewController
ormonitorAVPlayerLayer
, save this value to a variable (below it's calledplayerBinding
) - Create an
imaListener
instance by callingMuxImaListener.init(playerBinding: playerBinding!)
. - Dispatch events to the
imaListener
in youradsLoader
andadsManager
delegate methods.
import MuxCore
import MUXSDKStats
import GoogleInteractiveMediaAds
import Mux_Stats_Google_IMA
override func viewDidLoad() {
// Follow the instructions from pod 'GoogleAds-IMA-iOS-SDK' to set up
// your adsLoader and set your ViewController as the delegate
//
// From your ViewController, when you call either
// monitorAVPlayerViewController
// monitorAVPlayerLayer
//
// You will get back a MUXSDKPlayerBinding object
adsLoader.delegate = self
let playerBinding = MUXSDKStats.monitorAVPlayerViewController(self, withPlayerName: playName, playerData: cpd!, videoData: cvd)
// Use the MUXSDKPlayerBinding object to initialize the MuxImaListener class
imaListener = MuxImaListener.init(playerBinding: playerBinding!)
}
// the adsLoader delegate will fire this and give access to the adsManager
// the application needs to register as a delegate for the adsManager too
func adsLoader(_ loader: IMAAdsLoader!, adsLoadedWith adsLoadedData: IMAAdsLoadedData!) {
adsManager = adsLoadedData.adsManager;
adsManager.delegate = self;
}
// all of these events get fired by the adsManager delegate
// when this happens, the application needs to do some stuff and send the events
// to our sdk
func adsManager(_ adsManager: IMAAdsManager!, didReceive event: IMAAdEvent!) {
if (event.type == kIMAAdEvent_LOADED) {
adsManager.start()
}
imaListener.dispatchEvent(event)
}
func adsManager(_ adsManager: IMAAdsManager!, didReceive error: IMAAdError!)
avPlayer.play()
imaListener.dispatchError(error.message)
}
func adsManagerDidRequestContentPause(_ adsManager: IMAAdsManager!) {
avPlayer.pause()
imaListener.onContentPauseOrResume(true)
}
func adsManagerDidRequestContentResume(_ adsManager: IMAAdsManager!) {
avPlayer.play()
imaListener.onContentPauseOrResume(false)
}
For complete example projects look in the "/apps" directory of mux-stats-sdk-avplayer on Github.
All of these apps have examples with Google IMA ads.
DemoApp
is an iOS app written in objective-cvideo-demo
is an iOS app written in SwiftTVDemoApp
is a TVOS app written in objective-c
Track orientation change events
As of 1.3.0 Mux-Stats-AVPlayer can optionally track orientationchange
events. To use this functionality, call the orientationChangeForPlayer
method.
These events will show up on the events log on the view views page.
class VideoPlayerController: AVPlayerViewController {
override func viewWillTransition(to size: CGSize, with coordinator: UIViewControllerTransitionCoordinator) {
MUXSDKStats.orientationChange(forPlayer: playName, with: self.viewOrientationForSize(size: size))
}
func viewOrientationForSize(size: CGSize) -> MUXSDKViewOrientation {
return (size.width > size.height) ? MUXSDKViewOrientation.landscape : MUXSDKViewOrientation.portrait
}
}
Usage with AVQueuePlayer
To use with AVQueuePlayer
you will need to follow these steps:
- Listen for
AVPlayerItemDidPlayToEndTime
in your application - When that notification fires, call
videoChangeForPlayer:withVideoData
Here is an example that sets up a AVQueuePlayer with two items, and listener after the first item finishes playing and passes in new videoData
.
let playName = "iOS AVPlayer" override func viewDidLoad() { super.viewDidLoad() let item1 = AVPlayerItem(url: URL(string: "https://stream.mux.com/jY02nK1sxQKmJiQ7ltXY01w9LZQWdtNetE.m3u8")!) let item2 = AVPlayerItem(url: URL(string: "https://bitdash-a.akamaihd.net/content/sintel/hls/playlist.m3u8")!) NotificationCenter.default.addObserver( self, selector: #selector(self.playerItemDidReachEnd), name: NSNotification.Name.AVPlayerItemDidPlayToEndTime, object: item1 ) player = AVQueuePlayer(items: [item1, item2]) let playerData = MUXSDKCustomerPlayerData(environmentKey: "ENV_KEY"); playerData?.playerName = "AVPlayer" let videoData = MUXSDKCustomerVideoData(); videoData.videoIsLive = false; videoData.videoTitle = "Title1" MUXSDKStats.monitorAVPlayerViewController(self, withPlayerName: playName, playerData: playerData!, videoData: videoData); player!.play() } @objc func playerItemDidReachEnd (notification: NSNotification) { let videoData = MUXSDKCustomerVideoData(); videoData.videoTitle = "Title2" videoData.videoId = "applekeynote2010-2" MUXSDKStats.videoChange(forPlayer: playName, with: videoData) }
Handling errors manually
By default, automaticErrorTracking
is enabled which means the Mux SDK will catch errors that the player throws and track an error
event. Error tracking is meant for fatal errors. When an error is thrown it will mark the view as errored in the Mux dashboard and the view will no longer be monitored.
If you want to disable automatic and track errors manually you can do by passing in automaticErrorTracking: false
to the monitor*
method that you are using.
Weather automatic error tracking is enabled or disabled, you can dispatch errors manually with dispatchError
.
let playName = "iOS AVPlayer"
let playerData = MUXSDKCustomerPlayerData(environmentKey: "ENV_KEY");
// insert player metadata
let videoData = MUXSDKCustomerVideoData();
// insert video metadata
MUXSDKStats.monitorAVPlayerViewController(self,
withPlayerName: playName,
playerData: playerData!,
videoData: videoData
automaticErrorTracking: false);
//
// Later, you can dispatch an error yourself
//
MUXSDKStats.dispatchError("1234",
withMessage: "Something is not right",
forPlayer: playName)
Installing manually with carthage (not recommended)
The recommended way to install the Mux SDKs is with Cocoapods. However, if you want to install manually via Carthage that is supported only for version 1.x of Mux-Stats-AVPlayer. Carthage does not work with Xcode 12, so if you are using Carthage with Xcode 12, please see the following workaround.
If you are installing Mux-Stats-AVPlayer your Cartfile will also need to specify the mux-core library. Like this:
github "muxinc/mux-stats-sdk-avplayer" ~> 1.3.0 github "muxinc/stats-sdk-objc" ~> 2.2.2
After running carthage update --platform iOS
follow the usual instructions for linking the frameworks. The Carthage README on Github walks through that and this guide is a good walkthrough.
If you are using the Google IMA integration there are a few extra steps. Your Cartfile will have these dependencies:
github "muxinc/mux-stats-sdk-avplayer" ~> 1.3.0 github "muxinc/stats-sdk-objc" ~> 2.2.0 github "muxinc/mux-stats-google-ima" ~> 0.5.0
In addition to specifying these dependencies in the Cartfile and linking them up, you will also need to follow Google's documentation for "Manually, using the SDK download".
App Store warning: ITMS-90809: Deprecated API Usage
It has come up a few times that users of our iOS library get this warning from Apple.
Apple will stop accepting submissions of apps that use UIWebView APIs . See https://developer.apple.com/documentation/uikit/uiwebview for more information.
If you run grep -r "UIWebView" .
in your project you will see a match coming from the dSYM/
directory in Mux-Core. At first glance, we too thought our SDK was triggering this warning.
However, after looking into this with several different applications we found that the warning was not being triggered by our SDK. In every case it was coming from another 3rd party.
Note that none of the Mux iOS libraries (including Mux-Core
and Mux-Stats-AVPlayer
) use UIWebView
. If you are getting this warning you must have another sdk that is using UIWebView
.
The reason there is some confusion around this and the reason you get a match in the dSYM/
directory in Mux-Core is because our SDK links to UIKit and targets a version of iOS that may include UIWebView
. The dSYM
files are used for debugging purposes and they do not contain any functional code. You may see that this same confusion came up in other SDKs like Mapbox and Stripe (listed below).
Resources:
Current release
v2.2.1
- Fixes a bug where AirPlay rebuffering was incorrectly reported as paused
Previous Releases
v2.2.0
- Add Swift PM support
v2.1.0
- Submits
viewer_device_model
field - Updates our implementation of the Google IMA SDK in demo apps to work with the latest version
- Automated UI test for ads
v2.0.0
This release moves the build process to use XCFramework bundle type. For iOS, there are no changes required to your application code.
If you are using this SDK with TVOS the name of the module has changed (the Tv
suffix is no longer needed):
TVOS before 2.0:
@import MuxCoreTv; @import MUXSDKStatsTv;
TVOS after 2.0:
@import MuxCore; @import MUXSDKStats;
v1.7.0
- Adds support for
view_session_id
. - Adds support for
player_remote_played
- this will be true when a video is shown over Airplay.
v1.6.0
- Add
viewer_connection_type
for iOS (either "wifi" or "cellular"). Detecting viewer_connection type is done off the main thread to make sure this doesn't interfere with the performance of your application. Note thatviewer_connection_type
is omitted from TVOS because in versions before TVOS 12 there is no reliable way to detect "wifi" vs. "ethernet".
v1.4.1
- (bugfix)
monitorAVPlayerLayer
with optional argumentautomaticErrorTracking
was misnamed towithAutomaticErrorTracking
. This has been changed to the correct name which is consistent with the correspondingmonitorAVPlayerViewController
method (thanks @hlung in #58) - (bugfix) nullability warnings for MUXSDKStats (thanks @hlung in #58)
v1.4.0
- add option to disable automatic error tracking when calling either
monitorAVPlayerViewController
ormonitorAVPlayerLayer
- add
MUXSDKStats.dispatchError
method to manually dispatch an error
You probably will not need to use these features, but if your player is throwing noisy non-fatal errors or you want to catch the player errors yourself and take precise control over the error code and error message then you now have that ability.
Dispatching an error should only be used for fatal errors. When the player goes into the error state then it is no longer being tracked and the view will show up as errored in the Mux dashboard.
v1.3.8
- Performance updates that optimize main thread usage.
v1.3.7
- Bugfix: Update our framework build process to be compatible with
carthage 0.35.0
. See the github issue for more details. The gist of it is that Carthage no longer ignores dSYM files, so those need to be packaged up correctly with the framework.
v1.3.6
- Bugfix: Rebuild frameworks without importing UIKit (we don't use it). This came to our attention when it was reported that our SDK was triggering this warning from Apple “The App Store will no longer accept new apps using UIWebView as of April 2020 and app updates using UIWebView as of December 2020.”
v1.3.5
- Bugfix for usage with
AVQueuePlayer
. Unlike other methods of changing theplayerItem
on anAVPlayer
instance, whenAVQueuePlayer
progresses from one item to the next therate
observer does not fire so we have to handle it in a special case. See instructions above for usage withAVQueuePlayer
.
v1.3.4
- Update scaling logic to report upscaling based on logical resolution, not physical resolution. This will result in lower upscaling percentages, but correlates more closely with perceived visual quality
v1.3.3
- Fix a bug to make sure all needed header files are included in the
tvOS
framework
v1.3.2
- Fix a bug in request metrics tracking, request metric event timestamps should always be sent in unix millisecond timestamps, not seconds.
v1.3.1
- Fix an issue where multiple AVPlayer instances that are tracked simultaneously report the same throughput metrics.
v1.3.0
- Add support for
orientationchange
events. This can be dispatched withMUXSDKStats orientationChangeForPlayer: withOrientation:
- Add support for automatically tracking
renditionchange
events. You can see this new event in the events list for a view. - Improve implementation for bandwidth metrics calculation. Instead of polling for changes on the access log, use
AVPlayerItemNewAccessLogEntryNotification
- Fix bug in
programChange
so that it works consistently now - Dispatch
viewend
whendestoryPlayer
is called. Previously this was not called which didn't affect metrics, but resulted in aviewdropped
event in the events list.
v1.2.1
- Fix bug that prevents request metrics tracking from working. AVPlayer gives us requestStart and requestResponseEnd, so with those datapoints we can track throughput. This bugfix requires Mux-Stats-Core v2.1.3 or greater. Run
pod update Mux-Stats-AVPlayer
andpod update Mux-Stats-Core
to get the latest versions.
v1.2.0
- Fix bug in Mux-Stats-AVPlayer that prevents
videoChangeForPlayer
from working - Fix bug in AVPlayer SDK where it misses initial play event at times if SDK is initialized too late. This could cause some iOS views to not be displayed in the real-time dashboard, and to potentially have incomplete metrics such as Video Startup Time.
- Add ability to optionally pass in new player data when calling
videoChangeForPlayer
:videoChangeForPlayer:withPlayerData:withVideoData
v1.1.3
- Fix a bug to prevent an edge-case scenario where crashes can happen after calling
destroyPlayer
when observers have not yet bet set up on the player instance.
v1.1.2
- bump dependency version of Mux-Stats-Core to 2.1
v1.1.1
- bugfix - report the correct Mux Plugin Version. This sdk was erroneously reporting the incorrect 'Mux Plugin Version' attribute for views
v1.1.0
- Added new static method to
MUXSDKStats
updateCustomerDataForPlayer:withPlayerData:withVideoData
. This allows a developer to update customerPlayerData and/or customerVideoData after the sdk has been initialized. Not all metadata can be changed if it was previously set, but all metadata that was not set initially can be updated to the intended values.
v1.0.2
- Fix a bug that caused slowness when loading AVPlayer due to checking currentItem.asset.duration before the duration was loaded
v1.0.1
- Fix a bug with incorrect source video duration
v1.0.0
- Extract GoogleAds-IMA-iOS-SDK into a separate library (Mux-Stats-Google-IMA). The reason for this change was to remove the hard dependency on GoogleAds-IMA-iOS-SDK
- In order to implement ad events tracking, please follow the instructions to use this library (Mux-Stats-AVPlayer) in conjunction with Mux-Stats-Google-IMA and GoogleAds-IMA-iOS-SDK
0.1.5
- add support for tracking ad playback with GoogleAds-IMA-iOS-SDK
0.1.1
- add support for AVPlayer monitoring