Learn how to use Mux Player SDK to play video delivered by Mux in your iOS or iPadOS application
Beta
This SDK is currently in private beta. If you encounter any issues please let us know by filing an issue on Github.
Let's start by installing the SDK. We'll use the Swift Package Manager. Step-by-step guide on using Swift Package Manager in Xcode.
Open your applications project in Xcode. In the Xcode menu bar select File > Add Packages. In the top-right corner of the modal window that opens enter the SDK repository URL which is https://github.com/muxinc/mux-player-swift
.
By default Xcode will fetch the latest version of the SDK available on the main
branch. If you need a specific package version or to restrict the range of package versions used in your application, select a different Dependency Rule. Here's an overview of the different SPM Dependency Rules and their semantics.
Click on Add Package to begin resolving and downloading the SDK package. When completed, select your application target as the destination for the MuxPlayerSwift
package product. To use the SDK in your application, import it's module: import MuxPlayerSwift
.
We'd love to hear your feedback about our approach, shoot us a note at avplayer@mux.com with feature requests, API feedback, or just to let us know what you'd like to build.
Use MuxPlayerSwift
to setup an AVPlayerViewController
or AVPlayerLayer
that can download and stream a Mux asset with only a playback ID. The SDK will also enable Mux Data monitoring to help you measure the performance and quality of your application's video experiences.
import AVFoundationimport AVKitimport MuxPlayerSwift/// After you're done testing, you can check out this video out to learn more about video and players (as well as some philosophy)let playbackID = "qxb01i6T202018GFS02vp9RIe01icTcDCjVzQpmaB00CUisJ4"/// Prepare an AVPlayerViewController to stream and monitor a Mux assetfunc preparePlayerViewController( playbackID: String) -> AVPlayerViewController { let playerViewController = AVPlayerViewController( playbackID: playbackID ) return playerViewController}let examplePlayerViewController = preparePlayerViewController(playbackID: playbackID)/// Prepare an AVPlayerLayer to stream and monitor a Mux assetfunc preparePlayerLayer( playbackID: String) -> AVPlayerLayer { let playerLayer = AVPlayerLayer( playbackID: playbackID ) return playerLayer}
Your application can customize how Mux Video delivers video to the player using playback URL modifiers. A playback URL modifier is appended as a query parameter to a public playback URL. The MuxPlayerSwift
exposes a type-safe Swift API that constructs these URLs.
import AVFoundationimport AVKitimport MuxPlayerSwift/// After you're done testing, you can check out this video out to learn more about video and players (as well as some philosophy)let playbackID = "qxb01i6T202018GFS02vp9RIe01icTcDCjVzQpmaB00CUisJ4"/// Prepares a ready-for-display AVPlayer instance that will not exceed 720 x 1280 resolution/// when streaming videofunc preparePlayerViewController( playbackID: String) -> AVPlayerViewController { let playbackOptions = PlaybackOptions( maximumResolution: .upTo720p ) let playerViewController = AVPlayerViewController( playbackID: playbackID, playbackOptions: playbackOptions ) return playerViewController}let examplePlayerViewController = preparePlayerViewController(playbackID: playbackID)
The example above delegated constructing the playback URL and appending playback modifiers to the SDK.
When using the AVPlayerViewController
or AVPlayerLayer
convenience initializers provided by the MuxPlayerSwift
there are no required steps to enable Mux Data monitoring for video streamed from a Mux playback URL.
See the below section for more details and how to customize Mux Data monitoring.
If you're using UIView
that is backed by an AVPlayerLayer
to display video, MuxPlayerSwift
exposes APIs to setup an existing AVPlayerLayer
for playback.
import AVFoundationimport UIKitimport MuxPlayerSwift/// Prepare an already initialized AVPlayerLayer to stream and monitor a Mux assetfunc preparePlayerLayer( playbackID: String, playerView: UIView) { // Check to make sure the player view backing // layer is of the correct type and get a // reference if it is guard let playerLayer = playerView.layer as? AVPlayerLayer else { print("Unexpected backing layer type!") return } // Prepares the player layer to stream media // and monitor playback with Data playerLayer.prepare( playbackID: playbackID )}
Your application can also customize playback or monitoring with Mux Data by using the same parameters as shown for the AVPlayerLayer
initializers above.
By default Mux Data metrics will be populated in the same environment as your playback ID. Learn more about Mux Data metric definitions here.
Read on for additional (and optional) setup steps to modify or extend the information Mux Data tracks.
Use MonitoringOptions
to set custom monitoring-related parameters.
If you're already using the Mux Data SDK for AVPlayer this initializer allows you to any of your existing logic for constructing MUXSDKCustomerData
.
import AVKitimport MuxPlayerSwiftfunc preparePlayerViewController( playbackID: String) -> AVPlayerViewController { let customEnvironmentKey = "ENV_KEY" let playerData = MUXSDKCustomerPlayerData() playerData.environmentKey = customEnvironmentKey let videoData = = MUXSDKCustomerVideoData() videoData.videoTitle = "Video Behind the Scenes" videoData.videoSeries = "Video101" let customerData = MUXSDKCustomerData() customerData.playerData = playerData customerData.videoData = videoData let monitoringOptions = MonitoringOptions( customerData: customerData ) let playerViewController = AVPlayerViewController( playbackID: playbackID, monitoringOptions: monitoringOptions ) return playerViewController}
Mux Video supports playback access control. See here for more. The MuxPlayerSwift
supports streaming with playback IDs that have a signed playback policy.
A signed playback policy enables playback URLs that need to include a valid JSON Web Token (JWT) in order to gain access. Your application should generate and sign the JWT in a trusted environment that you control like a server-side application. As a security measure any playback modifiers must be passed through the JWT as additional claims.
Once your application receives the JWT, use it to initialize PlaybackOptions
. Then, initialize AVPlayerViewController
or AVPlayerLayer
as before.
import AVFoundationimport AVKitimport UIKitimport MuxPlayerSwift/// Prepare an AVPlayerViewController to stream and monitor a Mux asset /// with a playback ID that has a signed playback policyfunc preparePlayerViewController( playbackID: String, playbackToken: String) -> AVPlayerViewController { let playbackOptions = PlaybackOptions(playbackToken: playbackToken) let playerViewController = AVPlayerViewController( playbackID: playbackID, playbackOptions: playbackOptions ) return playerViewController}/// Prepare an AVPlayerLayer to stream and monitor a Mux asset /// with a playback ID that has a signed playback policyfunc preparePlayerLayer( playbackID: String, playbackToken: String) -> AVPlayerLayer { let playbackOptions = PlaybackOptions(playbackToken: playbackToken) let playerLayer = AVPlayerLayer( playbackID: playbackID, playbackOptions: playbackOptions ) return playerLayer}/// Prepare an already initialized AVPlayerLayer to stream and monitor a Mux asset/// with a playback ID that has a signed playback policyfunc preparePlayerLayer( playbackID: String, playbackToken: String, playerView: UIView) { let playbackOptions = PlaybackOptions(playbackToken: playbackToken) // Check to make sure the player view backing // layer is of the correct type and get a // reference if it is guard let playerLayer = playerView.layer as? AVPlayerLayer else { print("Unexpected backing layer type!") return } // Prepares the player layer to stream media // and monitor playback with Data playerLayer.prepare( playbackID: playbackID, playbackOptions: playbackOptions )}
If your JWT includes a playback restriction, Mux will not be able perform domain validation when the playback URL is loaded by AVPlayer
because no referrer information is supplied.
To allow AVPlayer
playback of referrer restricted assets set the allow_no_referrer
boolean parameter to true
when creating a playback restriction. Conversely, a playback restriction with allow_no_referrer
to false
will disallow AVPlayer
playback. See here for more.
Mux Video gives you extra control over the available resolutions of your video.
MuxPlayerSwift
exposes convenience APIs to adjust the maximum and minimum resolutions if they are available.
Setting a maximum resolution helps reduce delivery costs while setting a minimum resolution helps ensure visual quality of your video. Maximum and minimum resolutions can be set independently or composed together.
If you're using signed URLs, you'll need to embed min_resolution
and max_resolution
into the JWT claims. Full documentation available here.
This example restricts the resolution range AVPlayer
requests to be between 720p and 1080p.
/// Prepare an AVPlayerViewController to stream a Mux asset/// with a resolution range between 720p and 1080pfunc preparePlayerViewController( playbackID: String, maximumResolution: MaxResolutionTier, minimumResolution: MinResolutionTier) -> AVPlayerViewController { let playbackOptions = PlaybackOptions( maximumResolutionTier: .upTo1080p, minimumResolutionTier: .atLeast720p ) let playerViewController = AVPlayerViewController( playbackID: playbackID, playbackOptions: playbackOptions ) return playerViewController}
This example restricts the resolution AVPlayer
requests to a single fixed resolution, in our case 720p.
/// Prepare an AVPlayerViewController to stream a Mux asset/// at a fixed 720p resolutionfunc preparePlayerViewController( playbackID: String, maximumResolution: MaxResolutionTier, minimumResolution: MinResolutionTier) -> AVPlayerViewController { let playbackOptions = PlaybackOptions( maximumResolutionTier: .upTo720p, minimumResolutionTier: .atLeast720p ) let playerViewController = AVPlayerViewController( playbackID: playbackID, playbackOptions: playbackOptions ) return playerViewController}
When AVPlayer
requests delivery of HLS content, it first downloads a series of text files, commonly called manifests or playlists, to describe the available qualities of a video and the location of all the segments that comprise the video.
The order of renditions in the initial manifest or playlist can influence the resolution level a player selects. When using the Mux Player Swift SDK your application can manipulate that order in the PlaybackOptions
provided to AVPlayerViewController
or AVPlayerLayer
.
If your Mux asset is publicly playable, specify a RenditionOrder
.
/// Prepare an AVPlayerViewController to stream a Mux asset/// with a descending rendition orderfunc preparePlayerViewController( playbackID: String) -> AVPlayerViewController { let playbackOptions = PlaybackOptions( renditionOrder: .descending ) let playerViewController = AVPlayerViewController( playbackID: playbackID, playbackOptions: playbackOptions ) return playerViewController}
The available values for rendition order are listed here.
If you're using signed URLs, you'll need "rendition_order" : "desc" for descending rendition order into your JWT claims. Full documentation available here.
See this Mux blogpost and this guide for more on these options.