AVPlayerViewController: mi ez, integrációs módszerek iOS-ben

Mi az AVPlayerViewController?

AVPlayerViewController egy komponens az AVKit keretrendszerből, amely kész felületet biztosít videolejátszáshoz Apple alkalmazásokban. Megkíméli a fejlesztőt attól, hogy a nulláról hozzon létre egyedi lejátszót, és szabványos vezérlőelemeket kínál: play/szünet, visszatekerés, hangerőszabályzás és teljes képernyős mód.

Ellentétben az alacsony szintű AVPlayerLayer-rel, amely kézi UI-építést igényel, az AVPlayerViewController teljes mértékben kezeli a lejátszó életciklusát. A vezérlő automatikusan kezeli a képernyő elforgatását, alkalmazkodik a Safe Area-hoz a bevágással rendelkező iPhone-okon, és támogatja a többfeladatos munkát iPad-en.

Az Apple Documentation (2026) szerint az AVPlayerViewController kompatibilis az AVPlayer-rel és AVQueuePlayer-rel, lehetővé téve egyedi fájlok és lejátszási listák lejátszását is. Támogatottak a helyi tárolóból származó URL-ek, HLS hálózati streamek és titkosított FairPlay tartalmak.

Az AVPlayerViewController története és verziói

A komponens az iOS 8-ban jelent meg az AVKit-tel együtt, az elavult MPMoviePlayerController helyettesítéseként. Az iOS 11-ben hozzáadták a Picture in Picture támogatást és a feliratok megjelenítését. Az iOS 14-ben a vezérlő testreszabható vezérlősávot kapott az AVPlayerViewControllerDelegate delegátumon keresztül. Az iOS 16-tól kezdve megjelent a médiafájl dinamikus cseréjének támogatása a lejátszó újraépítése nélkül.

A modern AVPlayerViewController optimalizálva van a ProMotion kijelzőkhöz — a videó képkockasebessége automatikusan szinkronizálódik a képernyő frissítési sebességével. tvOS-en a komponens alkalmazkodik a Siri Remote fókusz interfészéhez, macOS-en pedig a QuickTime Player ablak módjához.

Hogyan működik az AVPlayerViewController

A vezérlő alapjában az AVPlayer és AVPlayerItem kapcsolata áll. Az AVPlayer a lejátszási objektum, amely kezeli az idővonalat, a sebességet és az állapotot. Az AVPlayerItem egy burkoló egy adott médiafájl körül, amely metaadatokat, sávokat és betöltési információkat tartalmaz.

Az inicializálás során az AVPlayerViewController hivatkozást kap az AVPlayer-re, és automatikusan létrehozza az AVPlayerLayer-t a videó megjelenítéséhez. A vezérlő feliratkozik az AVPlayer KVO-értesítéseire a readyToPlay állapotváltozásáról, betöltési hibákról és a lejátszás befejezéséről.

A vezérlőelemek (vezérlősáv) a képernyő megérintésével jelennek meg. iOS 15+-ban támogatják a testreszabást az AVPlayerViewControllerCustomizationDelegate-en keresztül, lehetővé téve a szabványos gombok elrejtését vagy cseréjét.

A vezérlő életciklusa

A vezérlő létrehozása és az AVPlayer hozzárendelése után a viewDidLoad metódus hívódik meg, amely elindítja a videó stream előkészítését. Amikor az AVPlayerItem eléri az AVPlayerItemStatusReadyToPlay állapotot, a lejátszó készen áll a képkockák megjelenítésére. A play() metódus meghívásakor elindul a videó stream dekódolása a Video Toolbox segítségével.

A képernyő elhagyásakor a vezérlő automatikusan szünetelteti a lejátszást és felszabadítja a dekódoló erőforrásait. iOS 13+-ban a lejátszás megőrzéséhez az alkalmazás minimalizálásakor a Background Modes és Audio Session konfigurálása szükséges. A WWDC 2024 szerint ajánlott az AVPlayerPlaybackCoordinator használata az iOS média központtal való szinkronizáláshoz.

Az AVPlayerViewController fő funkciói

A komponens gazdag funkciókészletet kínál rögtön a dobozból, ami vonzóvá teszi a legtöbb projekt számára. Az alábbiakban bemutatjuk a legfontosabb képességeket, amelyek nem igényelnek további kódot.

• Vezérlősáv play/szünettel, 15 másodperces visszatekeréssel, hangerőszabályzóval és előrehaladás csúszkával.
• Felirat támogatás — a beépített és külső feliratok automatikus megjelenítése VTT, SRT és iTunes Timed Text formátumokban.
• AirPlay — videó streamelésének lehetősége Apple TV-re és más AirPlay-kompatibilis eszközökre.
• Picture in Picture — lejátszás lebegő ablakban egy speciális gomb megnyomására (iPad-en és iPhone-on iOS 14+-szal).
• Teljes képernyős mód — automatikus váltás a készülék elforgatásakor és a nagyítás gomb megérintésekor.
• Sebességváltás — beépített vezérlő a lejátszási sebesség kiválasztásához (0.5x, 1.0x, 1.5x, 2.0x).
• Védett tartalom — natív támogatás a FairPlay Streaminghez DRM-mel védett HLS tartalomhoz.

Az AVPlayerViewController vezérlősávja

A vezérlősáv a felület alsó része, amely a fő vezérlőgombokat tartalmazza. Alapértelmezés szerint a sáv 3 másodperc inaktivitás után elrejtőzik, és érintésre jelenik meg. iOS 16+-ban a delegátumon keresztül az egyes elemek láthatósága kezelhető.

Hibakeresési módban a vezérlősáv kényszeríthető az AVPlayerViewController.requiresLinearPlayback tulajdonságon keresztül, amely egyben blokkolja a videó szüneteltetésének lehetőségét is. Ez hasznos reklámblokkok és oktatási tartalmak esetén.

Az AVPlayerViewController integrációja a projektbe

A vezérlő alapintegrációja nem igényel 10 sornál több kódot. Először létre kell hozni egy AVPlayer példányt a médiafájl URL-jével, majd át kell adni az AVPlayerViewController-nak, és megjeleníteni a vezérlőt a képernyőn.

Alap lejátszó létrehozása Swift-ben

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

A present meghívása után a vezérlő teljes képernyőn jelenik meg. A videó elkezd betöltődni a hálózatról, és amint a buffer eléri a readyToPlay küszöböt, a lejátszás automatikusan elindul a play() meghívása után.

AVPlayerItem beállítása fejlett vezérléshez

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

let metadata = AVMutableMetadataItem()
metadata.key = AVMetadataKey.commonKeyTitle
metadata.value = "Az én videóm"
item.addMetadata(metadata)

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

Az AVPlayerItem használata lehetővé teszi a metaadatok, idő kódok, hangsávok és feliratok kiválasztásának vezérlését. Az AVPlayerItem-en keresztül a betöltés előrehaladása, pufferelés és hálózati hibák is figyelhetők KVO segítségével a status tulajdonságon.

Vezérlőelemek beállítása

Az iOS 11-től kezdve a fejlesztő testreszabhatja a vezérlősávot az AVPlayerViewControllerDelegate protokollon keresztül. A playerViewController(_:willBeginFullScreenPresentationWithAnimationCoordinator:) metódus a teljes képernyős módba lépés előtt hívódik meg, és lehetővé teszi a UI előkészítését.

Az egyes gombok elrejtéséhez az AVPlayerViewController.showsPlaybackControls tulajdonság használható. Ha false-ra állítjuk, a vezérlősáv teljesen eltűnik, csak a videó stream marad. Hasznos egyedi overlay elemekhez.

Testreszabás a delegátum használatával

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 gomb hozzáadása
    }

    func playerViewController(
        _ playerViewController: AVPlayerViewController,
        didUpdate legibleMediaSelection: AVMediaSelectionGroup
    ) {
        print("Új felirat nyelv kiválasztva")
    }
}

A delegátum lehetővé teszi a felirat váltásának, a teljes képernyős módba lépés és kilépés, valamint a Picture in Picture kezdetének és befejezésének eseményeinek elfogását. A WWDC 2024-en az Apple a delegátum használatát ajánlotta analitikához — minden átmenet naplózása 100 ms-ig.

Munka feliratokkal és hangsávokkal

Az AVPlayerViewController automatikusan megjeleníti az összes elérhető feliratot és hangsávot, ha azok be vannak ágyazva a médiafájlba vagy meg lettek adva a HLS manifesztben. A felhasználó válthat közöttük a vezérlősávon lévő felirat ikon megérintésével megjelenő menün keresztül.

HLS streamek esetén az M3U8 manifeszt tartalmazza az elérhető nyelvi változatok listáját. Az AVPlayer betölti a megfelelő felirat szegmenseket WebVTT formátumban, és továbbítja azokat megjelenítésre az AVPlayerLayer-en keresztül. Az iOS 16+-ban megjelent a feliratok stílusának támogatása az AVTextStyleRule segítségével.

Hangsáv programozott kiválasztása

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

A selectAudioTrack metódus az audiable csoport hang opciói között keresi azt a változatot, amelynek extendedLanguageTag-je megegyezik a kívánt nyelvkóddal. Ez lehetővé teszi az „Eredeti hang” funkció megvalósítását többnyelvű tartalommal rendelkező alkalmazásokban.

Picture in Picture iPad-en

A Picture in Picture (PiP) mód lehetővé teszi a videó megjelenítését egy lebegő ablakban más alkalmazások felett. iPad-en ez a funkció iOS 9 óta, iPhone-on iOS 14 óta elérhető. Az AVPlayerViewController automatikusan hozzáadja a PiP gombot a vezérlősávhoz, ha van UIBackgroundModes feliratkozás.

A PiP aktiválásához az Info.plist-ben hozzá kell adni az UIBackgroundModes kulcsot audio és airplay értékkel. Ezt követően megjelenik a PiP gomb a vezérlőben, melynek megnyomására a videó 192x108 pontos lebegő ablakba zsugorodik.

A PiP eseményeket a delegátum dolgozza fel: playerViewController(_:willStartPictureInPictureFromFullScreen:) és playerViewController(_:didStopPictureInPicture:). Az Apple HIG szerint a PiP ablak minimális méretének legalább 120x68 pontnak kell lennie a tartalom olvashatóságának megőrzéséhez.