AVPlayerViewController: what it is, integration methods in iOS

What is AVPlayerViewController?

AVPlayerViewController is a component of the AVKit framework that provides a ready-made interface for playing video in Apple applications. It relieves developers from having to create a custom player from scratch by offering standard controls: play/pause, scrubbing, volume adjustment, and full-screen mode.

Unlike the low-level AVPlayerLayer, which requires manual UI construction, AVPlayerViewController fully manages the player lifecycle. The controller automatically handles screen rotation, adapts to the Safe Area on iPhones with a notch, and supports multitasking on iPad.

According to Apple Documentation (2026), AVPlayerViewController is compatible with AVPlayer and AVQueuePlayer, allowing playback of both single files and playlists. URLs from local storage, HLS network streams, and encrypted FairPlay content are supported.

History and Versions of AVPlayerViewController

The component appeared in iOS 8 along with AVKit as a replacement for the deprecated MPMoviePlayerController. In iOS 11, support for Picture in Picture and subtitle display was added. In iOS 14, the controller received a customizable transport bar through the AVPlayerViewControllerDelegate. Starting with iOS 16, support for dynamic media file replacement without recreating the player was introduced.

The modern AVPlayerViewController is optimized for ProMotion displays — the video frame rate automatically synchronizes with the screen refresh rate. On tvOS, the component adapts to the Siri Remote focus interface, and on macOS, to the QuickTime Player windowed mode.

How AVPlayerViewController Works

At the core of the controller is the AVPlayer and AVPlayerItem pairing. AVPlayer is the playback object that manages the timeline, speed, and state. AVPlayerItem is a wrapper around a specific media file, containing metadata, tracks, and loading information.

When initialized, AVPlayerViewController receives a reference to AVPlayer and automatically creates an AVPlayerLayer for displaying video. The controller subscribes to AVPlayer KVO notifications about status changes such as readyToPlay, loading errors, and playback completion.

The controls (transport bar) are displayed on tap. In iOS 15+, they support customization through AVPlayerViewControllerCustomizationDelegate, allowing you to hide or replace standard buttons.

Controller Lifecycle

After creating the controller and assigning AVPlayer, the viewDidLoad method is called, which starts preparing the video stream. When AVPlayerItem transitions to the AVPlayerItemStatusReadyToPlay status, the player is ready to display frames. When the play() method is called, video stream decoding begins via Video Toolbox.

When leaving the screen, the controller automatically pauses playback and releases decoder resources. On iOS 13+, to maintain playback when the app is minimized, Background Modes and Audio Session must be configured. According to WWDC 2024, it is recommended to use AVPlayerPlaybackCoordinator for synchronization with the iOS media center.

Key Features of AVPlayerViewController

The component provides a rich set of features out of the box, making it attractive for most projects. Below are key capabilities that require no additional code.

• Transport bar with play/pause, 15-second skip, volume control, and progress slider.
• Subtitle support — automatic display of embedded and external subtitles in VTT, SRT, and iTunes Timed Text formats.
• AirPlay — ability to stream video to Apple TV and other AirPlay-compatible devices.
• Picture in Picture — playback in a floating window when tapping a special button (on iPad and iPhone with iOS 14+).
• Full-screen mode — automatic switching when rotating the device and tapping the enlarge button.
• Speed control — built-in controller for selecting playback speed (0.5x, 1.0x, 1.5x, 2.0x).
• Protected content — native support for FairPlay Streaming for HLS content with DRM.

AVPlayerViewController Transport Bar

The transport bar is the bottom part of the interface containing the main control buttons. By default, the bar hides after 3 seconds of user inactivity and appears on tap. In iOS 16+, the delegate can be used to control the visibility of individual elements.

In debug mode, the transport bar can be forced to show using the AVPlayerViewController.requiresLinearPlayback property, which also prevents the video from being paused. This is useful for ad breaks and educational content.

Integrating AVPlayerViewController into Your Project

Basic integration of the controller takes no more than 10 lines of code. First, create an AVPlayer instance with the media file URL, then pass it to AVPlayerViewController and display the controller on screen.

Creating a Basic Player in Swift

import AVKit

let player = AVPlayer(url: URL(string: "https://example.com/video.mp4")!)
let playerVC = AVPlayerViewController()
playerVC.player = player

present(playerVC, animated: true) {
    player.play()
}

After calling present, the controller displays full screen. The video starts loading from the network, and once the buffer reaches the readyToPlay threshold, playback automatically begins after calling play().

Configuring AVPlayerItem for Advanced Control

let asset = AVAsset(url: videoURL)
let item = AVPlayerItem(asset: asset)

let metadata = AVMutableMetadataItem()
metadata.key = AVMetadataKey.commonKeyTitle
metadata.value = "My Video"
item.addMetadata(metadata)

let player = AVPlayer(playerItem: item)
let playerVC = AVPlayerViewController()
playerVC.player = player

Using AVPlayerItem gives you control over metadata, timecodes, audio track selection, and subtitles. Through AVPlayerItem, you can also monitor loading progress, buffering, and network errors using KVO on the status property.

Customizing Controls

Starting with iOS 11, developers can customize the transport bar through the AVPlayerViewControllerDelegate protocol. The playerViewController(_:willBeginFullScreenPresentationWithAnimationCoordinator:) method is called before entering full-screen mode and allows you to prepare the UI.

To hide individual buttons, use the AVPlayerViewController.showsPlaybackControls property. If set to false, the transport bar completely disappears, leaving only the video stream. Useful for custom overlay elements.

Customization Using the Delegate

class CustomPlayerViewController: UIViewController {
    private let playerVC = AVPlayerViewController()

    override func viewDidLoad() {
        super.viewDidLoad()
        playerVC.delegate = self
        playerVC.showsPlaybackControls = true
        playerVC.entersFullScreenWhenPlaybackBegins = true
    }
}

extension CustomPlayerViewController: AVPlayerViewControllerDelegate {
    func playerViewController(
        _ playerViewController: AVPlayerViewController,
        willBeginFullScreenPresentationWithAnimationCoordinator coordinator: UIViewControllerTransitionCoordinator
    ) {
        // Add overlay button
    }

    func playerViewController(
        _ playerViewController: AVPlayerViewController,
        didUpdate legibleMediaSelection: AVMediaSelectionGroup
    ) {
        print("New subtitle language selected")
    }
}

The delegate allows intercepting subtitle change events, entering and exiting full-screen mode, as well as starting and ending Picture in Picture. At WWDC 2024, Apple recommended using the delegate for analytics — log each transition within 100 ms.

Working with Subtitles and Audio Tracks

AVPlayerViewController automatically displays all available subtitles and audio tracks if they are embedded in the media file or specified in the HLS manifest. Users can switch them via the menu that appears when tapping the subtitle icon in the transport bar.

For HLS streams, the M3U8 manifest contains a list of available language variants. AVPlayer loads the corresponding WebVTT subtitle segments and passes them to AVPlayerLayer for rendering. iOS 16+ introduced subtitle styling support through AVTextStyleRule.

Programmatic Audio Track Selection

func selectAudioTrack(languageCode: String) {
    guard let group = player.currentItem?
        .asset.mediaSelectionGroup(forMediaCharacteristic: AVMediaCharacteristic.audible)
    else { return }

    for option in group.options {
        if option.extendedLanguageTag?.hasPrefix(languageCode) == true {
            player.currentItem?.select(option, in: group)
        }
    }
}

The selectAudioTrack method searches among the audio options of the audible group for the variant whose extendedLanguageTag matches the desired language code. This allows implementing the “Original Audio” feature in apps with multilingual content.

Picture in Picture on iPad

Picture in Picture (PiP) mode allows displaying video in a floating window on top of other apps. On iPad, this feature has been available since iOS 9, on iPhone — since iOS 14. AVPlayerViewController automatically adds a PiP button to the transport bar when subscribed to UIBackgroundModes.

To activate PiP, add the UIBackgroundModes key with the audio and airplay values to Info.plist. After that, a PiP button appears in the controller, which collapses the video into a floating window of 192x108 points when tapped.

PiP events are handled through the delegate: playerViewController(_:willStartPictureInPictureFromFullScreen:) and playerViewController(_:didStopPictureInPicture:). According to Apple HIG, the minimum PiP window size should be at least 120x68 points to maintain content readability.