AVPlayerViewController: czym jest, sposoby integracji w iOS

Czym jest AVPlayerViewController?

AVPlayerViewController to komponent frameworku AVKit zapewniający gotowy interfejs do odtwarzania wideo w aplikacjach Apple. Uwalnia dewelopera od konieczności tworzenia własnego odtwarzacza od podstaw, oferując standardowe elementy sterowania: play/pause, przewijanie, regulację głośności i tryb pełnoekranowy.

W przeciwieństwie do niskopoziomowego AVPlayerLayer, który wymaga ręcznego budowania UI, AVPlayerViewController w pełni zarządza cyklem życia odtwarzacza. Kontroler automatycznie obsługuje obrót ekranu, dostosowuje się do Safe Area na iPhone z notchem i obsługuje wielozadaniowość na iPad.

Według Apple Documentation (2026), AVPlayerViewController jest kompatybilny z AVPlayer i AVQueuePlayer, co pozwala odtwarzać zarówno pojedyncze pliki, jak i playlisty. Obsługiwane są URL z lokalnego przechowywania, strumienie sieciowe HLS i zaszyfrowane treści FairPlay.

Historia i wersje AVPlayerViewController

Komponent pojawił się w iOS 8 wraz z AVKit jako zamiennik dla przestarzałego MPMoviePlayerController. W iOS 11 dodano obsługę Picture in Picture i wyświetlanie napisów. W iOS 14 kontroler otrzymał konfigurowalny pasek sterowania przez delegata AVPlayerViewControllerDelegate. Od iOS 16 dostępna jest obsługa dynamicznej wymiany pliku multimedialnego bez odtwarzania odtwarzacza.

Nowoczesny AVPlayerViewController jest zoptymalizowany pod wyświetlacze ProMotion — częstotliwość klatek wideo automatycznie synchronizuje się z częstotliwością odświeżania ekranu. Na tvOS komponent dostosowuje się do interfejsu fokusu Siri Remote, a na macOS — do trybu okienkowego QuickTime Player.

Jak działa AVPlayerViewController

U podstaw kontrolera leży powiązanie AVPlayer i AVPlayerItem. AVPlayer to obiekt odtwarzania, który zarządzą osią czasu, prędkością i stanem. AVPlayerItem to otoczka wokół konkretnego pliku multimedialnego zawierająca metadane, ścieżki i informacje o ładowaniu.

Podczas inicjalizacji AVPlayerViewController otrzymuje referencję do AVPlayer i automatycznie tworzy AVPlayerLayer do wyświetlania wideo. Kontroler subskrybuje KVO-powiadomienia AVPlayer o zmianie statusu readyToPlay, błędach ładowania i zakończeniu odtwarzania.

Elementy sterowania (pasek transportowy) wyświetlane są po dotknięciu ekranu. W iOS 15+ obsługują one konfigurację przez AVPlayerViewControllerCustomizationDelegate, pozwalając ukrywać lub zastępować standardowe przyciski.

Cykl życia kontrolera

Po utworzeniu kontrolera i przypisaniu AVPlayer wywoływana jest metoda viewDidLoad, która uruchamia przygotowanie strumienia wideo. Gdy AVPlayerItem przechodzi w stan AVPlayerItemStatusReadyToPlay, odtwarzacz jest gotowy do wyświetlania klatek. Po wywołaniu metody play() uruchamiane jest dekodowanie strumienia wideo przez Video Toolbox.

Przy opuszczaniu ekranu kontroler automatycznie wstrzymuje odtwarzanie i zwalnia zasoby dekodera. Na iOS 13+ do zachowania odtwarzania podczas minimalizowania aplikacji wymagane jest skonfigurowanie Background Modes i Audio Session. Według WWDC 2024, zaleca się używanie AVPlayerPlaybackCoordinator do synchronizacji z centrum multimedialnym iOS.

Główne funkcje AVPlayerViewController

Komponent zapewnia bogaty zestaw funkcji od razu po wyjęciu z pudełka, co czyni go atrakcyjnym dla większości projektów. Poniżej przedstawiono kluczowe możliwości, które nie wymagają dodatkowego kodu.

• Pasek transportowy z play/pause, przewijaniem o 15 sekund, regulatorem głośności i suwakiem postępu.
• Obsługa napisów — automatyczne wyświetlanie wbudowanych i zewnętrznych napisów w formatach VTT, SRT i iTunes Timed Text.
• AirPlay — możliwość przesyłania wideo na Apple TV i inne urządzenia kompatybilne z AirPlay.
• Picture in Picture — odtwarzanie w pływającym oknie po naciśnięciu specjalnego przycisku (na iPad i iPhone z iOS 14+).
• Tryb pełnoekranowy — automatyczne przełączanie przy obrocie urządzenia i po dotknięciu przycisku powiększenia.
• Zmiana prędkości — wbudowany kontroler wyboru prędkości odtwarzania (0.5x, 1.0x, 1.5x, 2.0x).
• Treści chronione — natywna obsługa FairPlay Streaming dla treści HLS z DRM.

Pasek transportowy AVPlayerViewController

Pasek transportowy to dolna część interfejsu zawierająca główne przyciski sterowania. Domyślnie pasek ukrywa się po 3 sekundach braku aktywności użytkownika i pojawia się po dotknięciu. W iOS 16+ przez delegata można zarządzać widocznością poszczególnych elementów.

W trybie debugowania pasek transportowy można wymusić do wyświetlania przez właściwość AVPlayerViewController.requiresLinearPlayback, która również blokuje możliwość wstrzymania wideo. Jest to przydatne dla reklam i treści edukacyjnych.

Integracja AVPlayerViewController w projekcie

Podstawowa integracja kontrolera zajmuje nie więcej niż 10 linii kodu. Najpierw należy utworzyć instancję AVPlayer z URL pliku multimedialnego, następnie przekazać go do AVPlayerViewController i wyświetlić kontroler na ekranie.

Tworzenie podstawowego odtwarzacza w 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()
}

Po wywołaniu present kontroler wyświetla się na całym ekranie. Wideo zaczyna ładować się z sieci, a gdy bufor osiągnie próg readyToPlay, automatycznie rozpoczyna się odtwarzanie po wywołaniu play().

Konfiguracja AVPlayerItem dla zaawansowanego zarządzania

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

let metadata = AVMutableMetadataItem()
metadata.key = AVMetadataKey.commonKeyTitle
metadata.value = "Moje wideo"
item.addMetadata(metadata)

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

Użycie AVPlayerItem daje kontrolę nad metadanymi, kodami czasowymi, wyborem ścieżek audio i napisów. Przez AVPlayerItem można również obserwować postęp ładowania, buforowanie i błędy sieci za pomocą KVO na właściwości status.

Dostosowywanie elementów sterowania

Od iOS 11 deweloper może konfigurować pasek transportowy przez protokół AVPlayerViewControllerDelegate. Metoda playerViewController(_:willBeginFullScreenPresentationWithAnimationCoordinator:) jest wywoływana przed wejściem w tryb pełnoekranowy i pozwala przygotować UI.

Do ukrywania poszczególnych przycisków używa się właściwości AVPlayerViewController.showsPlaybackControls. Jeśli ustawić ją na false, pasek transportowy całkowicie znika, pozostawiając tylko strumień wideo. Przydatne dla niestandardowych elementów overlay.

Konfiguracja z użyciem delegata

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
    ) {
        // Dodaj przycisk overlay
    }

    func playerViewController(
        _ playerViewController: AVPlayerViewController,
        didUpdate legibleMediaSelection: AVMediaSelectionGroup
    ) {
        print("Wybrano nowy język napisów")
    }
}

Delegat pozwala przechwytywać zdarzenia zmiany napisów, wejścia i wyjścia z trybu pełnoekranowego oraz rozpoczęcia i zakończenia Picture in Picture. Na WWDC 2024 Apple zalecała używanie delegata do analityki — logować każde przejście do 100 ms.

Praca z napisami i ścieżkami audio

AVPlayerViewController automatycznie wyświetla wszystkie dostępne napisy i ścieżki audio, jeśli są one wbudowane w plik multimedialny lub określone w manifeście HLS. Użytkownik może je przełączać przez menu, które pojawia się po dotknięciu ikony napisów na pasku transportowym.

Dla strumieni HLS manifest M3U8 zawiera listę dostępnych wariantów językowych. AVPlayer ładuje odpowiednie segmenty napisów w formacie WebVTT i przekazuje je do renderowania przez AVPlayerLayer. W iOS 16+ pojawiła się obsługa stylizacji napisów przez AVTextStyleRule.

Programowy wybór ścieżki 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 szuka wśród opcji audio grupy audible tego wariantu, którego extendedLanguageTag odpowiada żądanemu kodowi języka. Pozwala to zaimplementować funkcję „Oryginalna ścieżka dźwiękowa” w aplikacjach z treścią wielojęzyczną.

Picture in Picture na iPad

Tryb Picture in Picture (PiP) pozwala wyświetlać wideo w pływającym oknie nad innymi aplikacjami. Na iPad funkcja ta jest dostępna od iOS 9, na iPhone — od iOS 14. AVPlayerViewController automatycznie dodaje przycisk PiP na pasku transportowym przy subskrypcji UIBackgroundModes.

Do aktywacji PiP należy w Info.plist dodać klucz UIBackgroundModes z wartością audio i airplay. Po tym w kontrolerze pojawia się przycisk PiP, po naciśnięciu którego wideo zwija się do pływającego okna o rozmiarze 192x108 punktów.

Zdarzenia PiP są obsługiwane przez delegata: playerViewController(_:willStartPictureInPictureFromFullScreen:) i playerViewController(_:didStopPictureInPicture:). Według Apple HIG, minimalny rozmiar okna PiP powinien wynosić co najmniej 120x68 punktów dla zachowania czytelności treści.