AVPlayerViewController: що це, способи інтеграції в iOS

Що таке AVPlayerViewController?

AVPlayerViewController — це компонент фреймворку AVKit, який надає готовий інтерфейс для відтворення відео в додатках Apple. Він позбавляє розробника необхідності створювати кастомний плеєр з нуля, пропонуючи стандартні елементи керування: play/pause, перемотування, регулювання гучності та повноекранний режим.

На відміну від низькорівневого AVPlayerLayer, який вимагає ручної побудови UI, AVPlayerViewController повністю керує життєвим циклом плеєра. Контролер автоматично обробляє поворот екрану, адаптується під Safe Area на iPhone з вирізом та підтримує багатозадачність на iPad.

За даними Apple Documentation (2026), AVPlayerViewController сумісний з AVPlayer та AVQueuePlayer, що дозволяє відтворювати як одиночні файли, так і плейлисти. Підтримуються URL з локального сховища, мережеві потоки HLS та зашифровані FairPlay-контенти.

Історія та версії AVPlayerViewController

Компонент з’явився в iOS 8 разом з AVKit як заміна застарілому MPMoviePlayerController. В iOS 11 була додана підтримка Picture in Picture та відображення субтитрів. В iOS 14 контролер отримав кастомізовану транспортну панель через делегат AVPlayerViewControllerDelegate. Починаючи з iOS 16, з’явилася підтримка динамічної заміни медіафайлу без перестворення плеєра.

Сучасний AVPlayerViewController оптимізований під ProMotion дисплеї — частота кадрів відео автоматично синхронізується з частотою оновлення екрану. На tvOS компонент адаптується під фокус-інтерфейс Siri Remote, а на macOS — під віконний режим QuickTime Player.

Як працює AVPlayerViewController

В основі контролера лежить зв’язка AVPlayer та AVPlayerItem. AVPlayer — це об’єкт відтворення, який керує таймлайном, швидкістю та станом. AVPlayerItem — обгортка над конкретним медіафайлом, що містить метадані, треки та інформацію про завантаження.

При ініціалізації AVPlayerViewController отримує посилання на AVPlayer та автоматично створює AVPlayerLayer для відображення відео. Контролер підписується на KVO-повідомлення AVPlayer про зміну статусу readyToPlay, помилки завантаження та закінчення відтворення.

Елементи керування (транспортна панель) відображаються по натисканню на екран. В iOS 15+ вони підтримують кастомізацію через AVPlayerViewControllerCustomizationDelegate, дозволяючи приховувати або замінювати стандартні кнопки.

Життєвий цикл контролера

Після створення контролера та присвоєння AVPlayer викликається метод viewDidLoad, який запускає підготовку відеопотоку. Коли AVPlayerItem переходить в статус AVPlayerItemStatusReadyToPlay, плеєр готовий до показу кадрів. При виклику методу play() запускається декодування відеопотоку через Video Toolbox.

При виході з екрану контролер автоматично призупиняє відтворення та звільняє ресурси декодера. На iOS 13+ для збереження відтворення при згортанні додатка потрібно налаштувати Background Modes та Audio Session. За даними WWDC 2024, рекомендується використовувати AVPlayerPlaybackCoordinator для синхронізації з медіацентром iOS.

Основні можливості AVPlayerViewController

Компонент надає багатий набір функцій з коробки, що робить його привабливим для більшості проектів. Нижче наведені ключові можливості, які не вимагають додаткового коду.

• Транспортна панель з play/pause, перемоткою на 15 секунд, регулятором гучності та слайдером прогресу.
• Підтримка субтитрів — автоматичне відображення вбудованих та зовнішніх субтитрів у форматах VTT, SRT та iTunes Timed Text.
• AirPlay — можливість транслювати відео на Apple TV та інші AirPlay-сумісні пристрої.
• Picture in Picture — відтворення в плаваючому вікні при натисканні на спеціальну кнопку (на iPad та iPhone з iOS 14+).
• Повноекранний режим — автоматичне перемикання при повороті пристрою та при тапі на кнопку збільшення.
• Зміна швидкості — вбудований контрол вибору швидкості відтворення (0.5x, 1.0x, 1.5x, 2.0x).
• Захищений контент — нативна підтримка FairPlay Streaming для HLS контенту з DRM.

Транспортна панель AVPlayerViewController

Транспортна панель — це нижня частина інтерфейсу, що містить основні кнопки керування. За замовчуванням панель приховується через 3 секунди бездіяльності користувача та з’являється при тапі. В iOS 16+ через делегат можна керувати видимістю окремих елементів.

В дебаг-режимі транспортну панель можна примусово показувати через властивість AVPlayerViewController.requiresLinearPlayback, яка також блокує можливість ставити відео на паузу. Це корисно для рекламних вставок та освітнього контенту.

Інтеграція AVPlayerViewController в проект

Базова інтеграція контролера займає не більше 10 рядків коду. Спочатку необхідно створити екземпляр AVPlayer з URL медіафайлу, потім передати його в AVPlayerViewController та відобразити контролер на екрані.

Створення базового плеєра на 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()
}

Після виклику present контролер відображається на весь екран. Відео починає завантаження з мережі, і як тільки буфер досягає порогу readyToPlay, автоматично починається відтворення після виклику play().

Налаштування AVPlayerItem для продвинутого керування

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

let metadata = AVMutableMetadataItem()
metadata.key = AVMetadataKey.commonKeyTitle
metadata.value = "Моє відео"
item.addMetadata(metadata)

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

Використання AVPlayerItem дає контроль над метаданими, тайм-кодами, вибором аудіотреків та субтитрів. Через AVPlayerItem можна також спостерігати за прогресом завантаження, буферизацією та помилками мережі за допомогою KVO на властивості status.

Налаштування елементів керування

Починаючи з iOS 11 розробник може кастомізувати транспортну панель через протокол AVPlayerViewControllerDelegate. Метод playerViewController(_:willBeginFullScreenPresentationWithAnimationCoordinator:) викликається перед входом у повноекранний режим і дозволяє підготувати UI.

Для приховування окремих кнопок використовується властивість AVPlayerViewController.showsPlaybackControls. Якщо встановити його в false, транспортна панель повністю зникає, залишаючи тільки відеопотік. Корисно для кастомних оверлейних елементів.

Кастомізація з використанням делегата

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-кнопку
    }

    func playerViewController(
        _ playerViewController: AVPlayerViewController,
        didUpdate legibleMediaSelection: AVMediaSelectionGroup
    ) {
        print("Вибрано нову мову субтитрів")
    }
}

Делегат дозволяє перехоплювати події зміни субтитрів, входу та виходу з повноекранного режиму, а також початку та завершення Picture in Picture. На WWDC 2024 Apple рекомендувала використовувати делегат для аналітики — логувати кожен перехід до 100 мс.

Робота з субтитрами та аудіодоріжками

AVPlayerViewController автоматично відображає всі доступні субтитри та аудіодоріжки, якщо вони зашиті в медіафайлі або вказані в маніфесті HLS. Користувач може перемикати їх через меню, яке з’являється при тапі на іконку субтитрів у транспортній панелі.

Для HLS-потоків маніфест M3U8 містить список доступних мовних варіантів. AVPlayer завантажує відповідні сегменти субтитрів у форматі WebVTT та передає їх на рендеринг через AVPlayerLayer. На iOS 16+ з’явилася підтримка стилізації субтитрів через AVTextStyleRule.

Програмний вибір аудіодоріжки

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

Метод selectAudioTrack шукає серед аудіоопцій групи audiable той варіант, чий extendedLanguageTag збігається з потрібним кодом мови. Це дозволяє реалізувати функцію «Озвучка в оригіналі» в додатках з мультимовним контентом.

Picture in Picture на iPad

Режим Picture in Picture (PiP) дозволяє відображати відео в плаваючому вікні поверх інших додатків. На iPad ця функція доступна з iOS 9, на iPhone — з iOS 14. AVPlayerViewController автоматично додає кнопку PiP в транспортну панель при наявності підписки на UIBackgroundModes.

Для активації PiP необхідно в Info.plist додати ключ UIBackgroundModes зі значенням audio та airplay. Після цього в контролері з’являється кнопка PiP, при натисканні на яку відео згортається в плаваюче вікно розміром 192x108 точок.

Події PiP обробляються через делегат: playerViewController(_:willStartPictureInPictureFromFullScreen:) та playerViewController(_:didStopPictureInPicture:). За даними Apple HIG, мінімальний розмір PiP вікна повинен бути не менше 120x68 точок для збереження читабельності контенту.