AVPlayerViewController: ce este, metode de integrare în iOS

Ce este AVPlayerViewController?

AVPlayerViewController este o componentă a framework-ului AVKit care oferă o interfață gata făcută pentru redarea video în aplicațiile Apple. Îl scutește pe dezvoltator de necesitatea de a crea un player personalizat de la zero, oferind elemente de control standard: play/pauză, derulare, reglare volum și mod ecran complet.

Spre deosebire de AVPlayerLayer de nivel scăzut, care necesită construirea manuală a UI-ului, AVPlayerViewController gestionează complet ciclul de viață al playerului. Controlerul procesează automat rotirea ecranului, se adaptează la Safe Area pe iPhone cu decupaj și suportă multitasking pe iPad.

Conform Apple Documentation (2026), AVPlayerViewController este compatibil cu AVPlayer și AVQueuePlayer, permițând redarea atât a fișierelor individuale, cât și a listelor de redare. Sunt suportate URL-urile din stocarea locală, fluxurile de rețea HLS și conținutul criptat FairPlay.

Istoricul și versiunile AVPlayerViewController

Componenta a apărut în iOS 8 împreună cu AVKit ca înlocuitor pentru MPMoviePlayerController învechit. În iOS 11 a fost adăugat suportul pentru Picture in Picture și afișarea subtitrărilor. În iOS 14 controlerul a primit o bară de transport personalizabilă prin delegatul AVPlayerViewControllerDelegate. Începând cu iOS 16, a apărut suportul pentru înlocuirea dinamică a fișierului media fără a recrea playerul.

AVPlayerViewController modern este optimizat pentru afișajele ProMotion — rata de cadre video se sincronizează automat cu rata de reîmprospătare a ecranului. Pe tvOS componenta se adaptează la interfața focalizată a Siri Remote, iar pe macOS — la modul fereastră al QuickTime Player.

Cum funcționează AVPlayerViewController

La baza controlerului se află legătura dintre AVPlayer și AVPlayerItem. AVPlayer este obiectul de redare care gestionează linia temporală, viteza și starea. AVPlayerItem este un înveliș în jurul unui fișier media specific, conținând metadate, piste și informații de încărcare.

La inițializare, AVPlayerViewController primește o referință către AVPlayer și creează automat AVPlayerLayer pentru afișarea video. Controlerul se abonează la notificările KVO ale AVPlayer despre schimbarea stării readyToPlay, erorile de încărcare și sfârșitul redării.

Elementele de control (bara de transport) se afișează la atingerea ecranului. În iOS 15+, acestea suportă personalizarea prin AVPlayerViewControllerCustomizationDelegate, permițând ascunderea sau înlocuirea butoanelor standard.

Ciclul de viață al controlerului

După crearea controlerului și atribuirea AVPlayer, este apelată metoda viewDidLoad, care inițiază pregătirea fluxului video. Când AVPlayerItem trece în starea AVPlayerItemStatusReadyToPlay, playerul este gata să afișeze cadre. La apelarea metodei play(), începe decodarea fluxului video prin Video Toolbox.

La părăsirea ecranului, controlerul oprește automat redarea și eliberează resursele decodorului. Pe iOS 13+, pentru a păstra redarea la minimizarea aplicației, este necesară configurarea Background Modes și Audio Session. Conform WWDC 2024, se recomandă utilizarea AVPlayerPlaybackCoordinator pentru sincronizarea cu centrul media iOS.

Funcționalitățile principale ale AVPlayerViewController

Componenta oferă un set bogat de funcții gata de utilizare, ceea ce o face atractivă pentru majoritatea proiectelor. Mai jos sunt prezentate capacitățile cheie care nu necesită cod suplimentar.

• Bară de transport cu play/pauză, derulare de 15 secunde, regulator de volum și glisor de progres.
• Suport pentru subtitrări — afișare automată a subtitrărilor încorporate și externe în formatele VTT, SRT și iTunes Timed Text.
• AirPlay — posibilitatea de a transmite video pe Apple TV și alte dispozitive compatibile AirPlay.
• Picture in Picture — redare într-o fereastră flotantă la apăsarea unui buton special (pe iPad și iPhone cu iOS 14+).
• Mod ecran complet — comutare automată la rotirea dispozitivului și la atingerea butonului de mărire.
• Schimbare viteză — control încorporat pentru selectarea vitezei de redare (0.5x, 1.0x, 1.5x, 2.0x).
• Conținut protejat — suport nativ pentru FairPlay Streaming pentru conținut HLS cu DRM.

Bara de transport AVPlayerViewController

Bara de transport este partea inferioară a interfeței care conține butoanele principale de control. Implicit, bara se ascunde după 3 secunde de inactivitate a utilizatorului și apare la atingere. În iOS 16+, prin delegat se poate gestiona vizibilitatea elementelor individuale.

În modul de depanare, bara de transport poate fi afișată forțat prin proprietatea AVPlayerViewController.requiresLinearPlayback, care blochează și posibilitatea de a pune video pe pauză. Acest lucru este util pentru inserții publicitare și conținut educațional.

Integrarea AVPlayerViewController în proiect

Integrarea de bază a controlerului nu durează mai mult de 10 linii de cod. Mai întâi, trebuie să creați o instanță AVPlayer cu URL-ul fișierului media, apoi să o transmiteți către AVPlayerViewController și să afișați controlerul pe ecran.

Crearea unui player de bază în 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()
}

După apelarea present, controlerul se afișează pe tot ecranul. Video începe încărcarea din rețea și, de îndată ce bufferul atinge pragul readyToPlay, redarea începe automat după apelarea play().

Configurarea AVPlayerItem pentru gestionare avansată

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

let metadata = AVMutableMetadataItem()
metadata.key = AVMetadataKey.commonKeyTitle
metadata.value = "Videoclipul meu"
item.addMetadata(metadata)

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

Utilizarea AVPlayerItem oferă control asupra metadatelor, codurilor de timp, selecției pistelor audio și subtitrărilor. Prin AVPlayerItem se poate monitoriza progresul încărcării, bufferizarea și erorile de rețea cu ajutorul KVO pe proprietatea status.

Configurarea elementelor de control

Începând cu iOS 11, dezvoltatorul poate personaliza bara de transport prin protocolul AVPlayerViewControllerDelegate. Metoda playerViewController(_:willBeginFullScreenPresentationWithAnimationCoordinator:) este apelată înainte de intrarea în modul ecran complet și permite pregătirea UI-ului.

Pentru ascunderea butoanelor individuale se utilizează proprietatea AVPlayerViewController.showsPlaybackControls. Dacă este setată pe false, bara de transport dispare complet, lăsând doar fluxul video. Utilă pentru elemente overlay personalizate.

Personalizarea cu ajutorul delegatului

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
    ) {
        // Adaugă buton overlay
    }

    func playerViewController(
        _ playerViewController: AVPlayerViewController,
        didUpdate legibleMediaSelection: AVMediaSelectionGroup
    ) {
        print("A fost selectată o nouă limbă pentru subtitrări")
    }
}

Delegatul permite interceptarea evenimentelor de schimbare a subtitrărilor, intrarea și ieșirea din modul ecran complet, precum și începerea și sfârșitul Picture in Picture. La WWDC 2024, Apple a recomandat utilizarea delegatului pentru analitică — logarea fiecărei tranziții sub 100 ms.

Lucrul cu subtitrări și piste audio

AVPlayerViewController afișează automat toate subtitrările și pistele audio disponibile, dacă sunt încorporate în fișierul media sau specificate în manifestul HLS. Utilizatorul le poate comuta prin meniul care apare la atingerea pictogramei de subtitrări din bara de transport.

Pentru fluxurile HLS, manifestul M3U8 conține o listă a variantelor lingvistice disponibile. AVPlayer încarcă segmentele corespunzătoare de subtitrări în format WebVTT și le trimite la randare prin AVPlayerLayer. În iOS 16+ a apărut suportul pentru stilizarea subtitrărilor prin AVTextStyleRule.

Selectarea programatică a pistelor audio

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

Metoda selectAudioTrack caută printre opțiunile audio ale grupului audiable acea variantă al cărei extendedLanguageTag se potrivește cu codul de limbă dorit. Astfel se poate implementa funcția «Audio original» în aplicațiile cu conținut multilingv.

Picture in Picture pe iPad

Modul Picture in Picture (PiP) permite afișarea video într-o fereastră flotantă deasupra altor aplicații. Pe iPad această funcție este disponibilă din iOS 9, pe iPhone — din iOS 14. AVPlayerViewController adaugă automat butonul PiP în bara de transport atunci când există abonamentul UIBackgroundModes.

Pentru activarea PiP, în Info.plist trebuie adăugată cheia UIBackgroundModes cu valoarea audio și airplay. După aceea, în controler apare butonul PiP, la apăsarea căruia video se minimizează într-o fereastră flotantă de 192x108 puncte.

Evenimentele PiP sunt procesate prin delegat: playerViewController(_:willStartPictureInPictureFromFullScreen:) și playerViewController(_:didStopPictureInPicture:). Conform Apple HIG, dimensiunea minimă a ferestrei PiP trebuie să fie de cel puțin 120x68 puncte pentru a păstra lizibilitatea conținutului.