Skip to Content
Mux Docs: Home

Control playback resolution

Control the video resolution your users receive in order to give the best user experience as well as take advantage of Mux's resolution based pricing.

Default playback URL

The default playback URL will contain all available resolutions of your video. The resolutions available will depend on the video source file.

By default if the source file contains 1080p or higher, then the highest resolution provided by Mux will be 1080p. If the source file is lower than 1080p, the highest resolution available will be the resolution of the source.

You can also stream 4K content using Mux Video, which will be delivered at higher resolutions including 2.5K and 4K. For more details see the guide to streaming 4K videos.

https://stream.mux.com/{PLAYBACK_ID}.m3u8

Use the default playback URL for most use cases. The video player will determine the best resolution based on the available bandwidth of the viewer.

Specify maximum resolution

The playback URL below with the max_resolution query parameter modifies the resolutions available for the player to choose from.

https://stream.mux.com/{PLAYBACK_ID}.m3u8?max_resolution=720p

The max_resolution parameter can be set to 720p, 1080p, 1440p, or 2160p. You may want to do this in order to reduce your delivery costs, or build a feature to your product where only certain viewers get lower resolution video.

Secure max_resolution parameter

If you are using signed Playback IDs according to the Secure video playback guide then your max_resolution modifier must be encodded in the token that you generate on your server.

{
  "sub": "{PLAYBACK_ID}",
  "aud": "{AUDIENCE_TYPE}",
  "exp": "{EXPIRATION_TIME}",
  "redundant_streams": true,
  "max_resolution": "720p"
}

Usage in Mux Player

The max_resolution= parameter with Mux Player can be set via the max-resolution="720p" attribute (maxResolution="720p" in React). When setting this attribute Mux Player will internally add it on as a query parameter on the streaming URL.

As with all playback modifiers, if you're using signed URLs, the max_resolution parameter should be encoded in the playback-token attribute (tokens.playback in React).

When using AVPlayer on iOS

Set the max_resolution parameter by appending a URLQueryItem to the playback URL. Initialize AVPlayer using the URL itself as shown in an example below or initialize with an AVPlayerItem constructed with the URL.

import AVKit
import Foundation

let playbackID = "qxb01i6T202018GFS02vp9RIe01icTcDCjVzQpmaB00CUisJ4"

// Flag controlling if a max resolution is requested
let shouldLimitResolutionTo720p = true

let player = AVPlayer(
    using: playbackID,
    limitResolutionTo720p: shouldLimitResolutionTo720p
)

extension AVPlayer {
    /// Initializes a player configured to stream
    /// the provided asset's playback ID.
    /// - Parameters:
    ///   - playbackID: a playback ID of your asset
    ///   - limitResolutionTo720p: if true configures
    ///   the player to select a resolution no higher
    ///   than 720p. False by default. 
    convenience init(
        using playbackID: String,
        limitResolutionTo720p: Bool = false
    ) {
        let playbackURL = URL.makePlaybackURL(
            playbackID: playbackID,
            limitResolutionTo720p: limitResolutionTo720p
        )
        
        self.init(
            url: playbackURL
        )
    }
}

/// Convenience extensions for working with URLs
extension URL {
    /// Convenience initializer for a static URL
    /// - Parameters:
    ///   - staticString: a static representation
    ///   of a valid URL, supplying an invalid URL
    ///   results in precondition failure
    init(staticString: StaticString) {
        guard let url = URL(
            string: "\(staticString)"
        ) else {
            preconditionFailure("Invalid URL static string")
        }

        self = url
    }

    /// Convenience constructor for a playback URL with
    /// an optional 720p limit
    /// - Parameters:
    ///     - baseURL: either the Mux stream URL or can be
    ///     customized if using Custom Domains for Mux Video.
    ///     - playbackID: playback ID for the asset
    ///     - limitResolutionTo720p: set an upper threshold for the
    ///     resolution chosen by the player to 720p. By default no limit 
    ///     is set and the player can choose any available resolution.
    /// - Returns: a playback URL for a Mux Video asset with a resolution
    /// limit if it is requested
    static func makePlaybackURL(
        baseURL: StaticString = "https://stream.mux.com",
        playbackID: String,
        limitResolutionTo720p: Bool = false
     ) -> URL {
        var components = URLComponents(
            url: URL(
                staticString: baseURL
            ),
            resolvingAgainstBaseURL: false
        )

        components?.path = "/\(playbackID).m3u8"

        if limitResolutionTo720p {
            components?.queryItems = [
                URLQueryItem(
                    name: "max_resolution",
                    value: "720p"
                )
            ]
        }
    
        guard let playbackURL = components?.url else {
            preconditionFailure("Invalid playback URL component")
        }

        return playbackURL
     }
}

Was this page helpful?