AVPlayerViewController: wat is het, manieren van integratie in iOS

Wat is AVPlayerViewController?

AVPlayerViewController is een component van het AVKit-framework dat een kant-en-klare interface biedt voor het afspelen van video in Apple-apps. Het bespaart de ontwikkelaar de noodzaak om een aangepaste speler helemaal zelf te bouwen en biedt standaard bedieningselementen: play/pauze, vooruitspoelen, volumenregeling en volledig scherm.

In tegenstelling tot de low-level AVPlayerLayer, die handmatige UI-opbouw vereist, beheert AVPlayerViewController de volledige levenscyclus van de speler. De controller verwerkt automatisch schermrotatie, past zich aan de Safe Area aan op iPhones met een uitsparing en ondersteunt multitasking op de iPad.

Volgens Apple Documentation (2026) is AVPlayerViewController compatibel met AVPlayer en AVQueuePlayer, waardoor zowel afzonderlijke bestanden als afspeellijsten kunnen worden afgespeeld. URL's uit lokale opslag, HLS-netwerkstromen en gecodeerde FairPlay-content worden ondersteund.

Geschiedenis en versies van AVPlayerViewController

De component verscheen in iOS 8 samen met AVKit als vervanging voor de verouderde MPMoviePlayerController. In iOS 11 werd ondersteuning voor Picture in Picture en het weergeven van ondertiteling toegevoegd. In iOS 14 kreeg de controller een aanpasbare bedieningsbalk via de delegate AVPlayerViewControllerDelegate. Sinds iOS 16 is er ondersteuning voor het dynamisch vervangen van het mediabestand zonder de speler opnieuw te maken.

De moderne AVPlayerViewController is geoptimaliseerd voor ProMotion-schermen — de videoframesnelheid wordt automatisch gesynchroniseerd met de verversingssnelheid van het scherm. Op tvOS past de component zich aan de focusinterface van de Siri Remote aan, en op macOS aan de venstermodus van QuickTime Player.

Hoe werkt AVPlayerViewController

Aan de basis van de controller ligt de koppeling tussen AVPlayer en AVPlayerItem. AVPlayer is het afspeelobject dat de tijdlijn, snelheid en status beheert. AVPlayerItem is een wrapper rond een specifiek mediabestand met metadata, tracks en laadinformatie.

Bij initialisatie krijgt AVPlayerViewController een verwijzing naar AVPlayer en maakt automatisch AVPlayerLayer aan voor het weergeven van video. De controller abonneert zich op KVO-meldingen van AVPlayer over statuswijzigingen van readyToPlay, laadfouten en het einde van het afspelen.

De bedieningselementen (transportbalk) worden weergegeven door op het scherm te tikken. In iOS 15+ ondersteunen ze aanpassing via AVPlayerViewControllerCustomizationDelegate, waarmee standaardknoppen kunnen worden verborgen of vervangen.

Levenscyclus van de controller

Na het maken van de controller en het toewijzen van AVPlayer wordt de methode viewDidLoad aangeroepen, die de voorbereiding van de videostroom start. Wanneer AVPlayerItem de status AVPlayerItemStatusReadyToPlay bereikt, is de speler klaar om frames weer te geven. Bij het aanroepen van de methode play() start het decoderen van de videostroom via Video Toolbox.

Bij het verlaten van het scherm stopt de controller automatisch het afspelen en geeft de decoderbronnen vrij. Op iOS 13+ is voor het behouden van het afspelen bij het minimaliseren van de app het configureren van Background Modes en Audio Session vereist. Volgens WWDC 2024 wordt aanbevolen AVPlayerPlaybackCoordinator te gebruiken voor synchronisatie met het iOS-mediacentrum.

Belangrijkste functies van AVPlayerViewController

De component biedt een rijke set functies uit de doos, wat het aantrekkelijk maakt voor de meeste projecten. Hieronder staan de belangrijkste mogelijkheden die geen extra code vereisen.

• Transportbalk met play/pauze, 15 seconden vooruitspoelen, volumeregelaar en voortgangsschuif.
• Ondertitelingsondersteuning — automatische weergave van ingebouwde en externe ondertiteling in VTT-, SRT- en iTunes Timed Text-formaten.
• AirPlay — mogelijkheid om video naar Apple TV en andere AirPlay-compatibele apparaten te streamen.
• Picture in Picture — afspelen in een zwevend venster bij het indrukken van een speciale knop (op iPad en iPhone met iOS 14+).
• Volledig scherm — automatisch schakelen bij draaien van het apparaat en bij tikken op de vergrootknop.
• Snelheid wijzigen — ingebouwde regelaar voor het kiezen van de afspeelsnelheid (0.5x, 1.0x, 1.5x, 2.0x).
• Beschermde content — native ondersteuning voor FairPlay Streaming voor HLS-content met DRM.

De transportbalk van AVPlayerViewController

De transportbalk is het onderste deel van de interface met de belangrijkste bedieningsknoppen. Standaard wordt de balk na 3 seconden inactiviteit van de gebruiker verborgen en verschijnt bij tikken. In iOS 16+ kan via de delegate de zichtbaarheid van afzonderlijke elementen worden beheerd.

In de foutopsporingsmodus kan de transportbalk gedwongen worden weergegeven via de eigenschap AVPlayerViewController.requiresLinearPlayback, die ook de mogelijkheid blokkeert om video te pauzeren. Dit is handig voor reclameblokken en educatieve content.

Integratie van AVPlayerViewController in een project

De basisintegratie van de controller kost niet meer dan 10 regels code. Eerst moet een AVPlayer-instantie worden gemaakt met de URL van het mediabestand, vervolgens worden doorgegeven aan AVPlayerViewController en de controller op het scherm worden weergegeven.

Een basisspeler maken 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()
}

Na het aanroepen van present wordt de controller op het volledige scherm weergegeven. De video begint met laden uit het netwerk en zodra de buffer de readyToPlay-drempel bereikt, start het afspelen automatisch na het aanroepen van play().

AVPlayerItem configureren voor geavanceerd beheer

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

let metadata = AVMutableMetadataItem()
metadata.key = AVMetadataKey.commonKeyTitle
metadata.value = "Mijn video"
item.addMetadata(metadata)

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

Het gebruik van AVPlayerItem biedt controle over metadata, tijdcodes, selectie van audiotracks en ondertiteling. Via AVPlayerItem kan ook de laadvoortgang, buffering en netwerkfouten worden gevolgd met KVO op de eigenschap status.

Bedieningselementen aanpassen

Sinds iOS 11 kan de ontwikkelaar de transportbalk aanpassen via het protocol AVPlayerViewControllerDelegate. De methode playerViewController(_:willBeginFullScreenPresentationWithAnimationCoordinator:) wordt aangeroepen voordat de volledig schermmodus wordt ingegaan en maakt voorbereiding van de UI mogelijk.

Voor het verbergen van afzonderlijke knoppen wordt de eigenschap AVPlayerViewController.showsPlaybackControls gebruikt. Indien ingesteld op false, verdwijnt de transportbalk volledig en blijft alleen de videostroom over. Handig voor aangepaste overlay-elementen.

Aanpassing met behulp van de 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
    ) {
        // Overlay-knop toevoegen
    }

    func playerViewController(
        _ playerViewController: AVPlayerViewController,
        didUpdate legibleMediaSelection: AVMediaSelectionGroup
    ) {
        print("Nieuwe ondertitelingstaal geselecteerd")
    }
}

De delegate maakt het mogelijk om gebeurtenissen van het wijzigen van ondertiteling, het in- en uitgaan van de volledig schermmodus en het starten en stoppen van Picture in Picture te onderscheppen. Op WWDC 2024 raadde Apple aan de delegate te gebruiken voor analytics — elke overgang loggen tot 100 ms.

Werken met ondertiteling en audiotracks

AVPlayerViewController geeft automatisch alle beschikbare ondertiteling en audiotracks weer, als deze zijn ingebed in het mediabestand of vermeld in het HLS-manifest. De gebruiker kan ze schakelen via het menu dat verschijnt bij tikken op het ondertitelingspictogram in de transportbalk.

Voor HLS-streams bevat het M3U8-manifest een lijst met beschikbare taalvarianten. AVPlayer laadt de overeenkomstige ondertitelingssegmenten in WebVTT-formaat en geeft ze door voor weergave via AVPlayerLayer. In iOS 16+ is ondersteuning voor het stylen van ondertiteling via AVTextStyleRule toegevoegd.

Programmatisch selecteren van audiotracks

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)
        }
    }
}

De methode selectAudioTrack zoekt tussen de audio-opties van de audiable-groep naar de variant waarvan de extendedLanguageTag overeenkomt met de gewenste taalcode. Dit maakt het mogelijk om de functie “Originele audio” te implementeren in apps met meertalige content.

Picture in Picture op iPad

De Picture in Picture (PiP)-modus maakt het mogelijk om video weer te geven in een zwevend venster boven andere apps. Op de iPad is deze functie beschikbaar sinds iOS 9, op de iPhone sinds iOS 14. AVPlayerViewController voegt automatisch de PiP-knop toe aan de transportbalk wanneer er een abonnement op UIBackgroundModes is.

Voor het activeren van PiP moet in Info.plist de sleutel UIBackgroundModes met de waarde audio en airplay worden toegevoegd. Daarna verschijnt in de controller de PiP-knop, bij indrukken wordt de video verkleind tot een zwevend venster van 192x108 punten.

PiP-gebeurtenissen worden verwerkt via de delegate: playerViewController(_:willStartPictureInPictureFromFullScreen:) en playerViewController(_:didStopPictureInPicture:). Volgens Apple HIG moet de minimale grootte van het PiP-venster ten minste 120x68 punten zijn om de leesbaarheid van de content te behouden.