AVPlayerViewController: o que é, métodos de integração no iOS

O que é AVPlayerViewController?

AVPlayerViewController é um componente do framework AVKit que fornece uma interface pronta para reproduzir vídeo em aplicativos Apple. Ele libera o desenvolvedor da necessidade de criar um player personalizado do zero, oferecendo controles padrão: reproduzir/pausar, avançar, ajuste de volume e modo tela cheia.

Ao contrário do AVPlayerLayer de baixo nível, que requer construção manual da interface, o AVPlayerViewController gerencia completamente o ciclo de vida do player. O controlador lida automaticamente com a rotação da tela, adapta-se à área segura em iPhones com notch e suporta multitarefa no iPad.

De acordo com a Documentação da Apple (2026), o AVPlayerViewController é compatível com AVPlayer e AVQueuePlayer, permitindo reproduzir tanto arquivos individuais quanto playlists. URLs de armazenamento local, streams de rede HLS e conteúdo FairPlay criptografado são suportados.

História e versões do AVPlayerViewController

O componente apareceu no iOS 8 junto com o AVKit como substituto do obsoleto MPMoviePlayerController. No iOS 11, foi adicionado suporte para Picture in Picture e exibição de legendas. No iOS 14, o controlador recebeu uma barra de transporte personalizável através do AVPlayerViewControllerDelegate. A partir do iOS 16, foi introduzido suporte para substituição dinâmica de arquivos de mídia sem recriar o player.

O AVPlayerViewController moderno é otimizado para telas ProMotion — a taxa de quadros do vídeo sincroniza automaticamente com a taxa de atualização da tela. No tvOS, o componente adapta-se à interface de foco do Siri Remote e, no macOS, ao modo de janela do QuickTime Player.

Como funciona o AVPlayerViewController

No núcleo do controlador está o emparelhamento de AVPlayer e AVPlayerItem. AVPlayer é o objeto de reprodução que gerencia a linha do tempo, velocidade e estado. AVPlayerItem é um invólucro em torno de um arquivo de mídia específico, contendo metadados, faixas e informações de carregamento.

Quando inicializado, o AVPlayerViewController recebe uma referência ao AVPlayer e cria automaticamente um AVPlayerLayer para exibir o vídeo. O controlador assina as notificações KVO do AVPlayer sobre mudanças de estado como readyToPlay, erros de carregamento e conclusão da reprodução.

Os controles (barra de transporte) são exibidos ao tocar na tela. No iOS 15+, eles suportam personalização através do AVPlayerViewControllerCustomizationDelegate, permitindo ocultar ou substituir botões padrão.

Ciclo de vida do controlador

Após criar o controlador e atribuir o AVPlayer, o método viewDidLoad é chamado, que começa a preparar o fluxo de vídeo. Quando o AVPlayerItem transiciona para o estado AVPlayerItemStatusReadyToPlay, o player está pronto para exibir quadros. Quando o método play() é chamado, a decodificação do fluxo de vídeo começa via Video Toolbox.

Ao sair da tela, o controlador pausa automaticamente a reprodução e libera os recursos do decodificador. No iOS 13+, para manter a reprodução quando o aplicativo é minimizado, os Modos de Fundo e a Sessão de Áudio devem ser configurados. De acordo com a WWDC 2024, recomenda-se usar AVPlayerPlaybackCoordinator para sincronização com o centro de mídia do iOS.

Principais recursos do AVPlayerViewController

O componente fornece um conjunto rico de recursos prontos para uso, tornando-o atraente para a maioria dos projetos. Abaixo estão as capacidades principais que não requerem código adicional.

• Barra de transporte com reprodução/pausa, salto de 15 segundos, controle de volume e slider de progresso.
• Suporte a legendas — exibição automática de legendas incorporadas e externas nos formatos VTT, SRT e iTunes Timed Text.
• AirPlay — capacidade de transmitir vídeo para Apple TV e outros dispositivos compatíveis com AirPlay.
• Picture in Picture — reprodução em uma janela flutuante ao tocar em um botão especial (no iPad e iPhone com iOS 14+).
• Modo tela cheia — alternância automática ao girar o dispositivo e ao tocar no botão de ampliar.
• Controle de velocidade — controle integrado para selecionar a velocidade de reprodução (0.5x, 1.0x, 1.5x, 2.0x).
• Conteúdo protegido — suporte nativo para FairPlay Streaming para conteúdo HLS com DRM.

Barra de transporte do AVPlayerViewController

A barra de transporte é a parte inferior da interface que contém os botões principais de controle. Por padrão, a barra é ocultada após 3 segundos de inatividade do usuário e aparece ao tocar. No iOS 16+, o delegado pode ser usado para controlar a visibilidade de elementos individuais.

No modo de depuração, a barra de transporte pode ser forçada a aparecer usando a propriedade AVPlayerViewController.requiresLinearPlayback, que também impede que o vídeo seja pausado. Isso é útil para pausas publicitárias e conteúdo educacional.

Integração do AVPlayerViewController no seu projeto

A integração básica do controlador não leva mais de 10 linhas de código. Primeiro, crie uma instância do AVPlayer com a URL do arquivo de mídia, depois passe-a para o AVPlayerViewController e exiba o controlador na tela.

Criação de um player básico em 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()
}

Após chamar present, o controlador é exibido em tela cheia. O vídeo começa a carregar da rede e, assim que o buffer atinge o limite readyToPlay, a reprodução começa automaticamente após chamar play().

Configuração do AVPlayerItem para controle avançado

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

let metadata = AVMutableMetadataItem()
metadata.key = AVMetadataKey.commonKeyTitle
metadata.value = "Meu Vídeo"
item.addMetadata(metadata)

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

Usar AVPlayerItem dá a você controle sobre metadados, timecodes, seleção de faixas de áudio e legendas. Através do AVPlayerItem, você também pode monitorar o progresso do carregamento, buffer e erros de rede usando KVO na propriedade status.

Personalização dos controles

A partir do iOS 11, os desenvolvedores podem personalizar a barra de transporte através do protocolo AVPlayerViewControllerDelegate. O método playerViewController(_:willBeginFullScreenPresentationWithAnimationCoordinator:) é chamado antes de entrar no modo tela cheia e permite preparar a interface.

Para ocultar botões individuais, use a propriedade AVPlayerViewController.showsPlaybackControls. Se definida como false, a barra de transporte desaparece completamente, deixando apenas o fluxo de vídeo. Útil para elementos sobrepostos personalizados.

Personalização usando o delegado

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
    ) {
        // Adicionar botão sobreposto
    }

    func playerViewController(
        _ playerViewController: AVPlayerViewController,
        didUpdate legibleMediaSelection: AVMediaSelectionGroup
    ) {
        print("Novo idioma de legenda selecionado")
    }
}

O delegado permite interceptar eventos de mudança de legendas, entrada e saída do modo tela cheia, bem como início e fim do Picture in Picture. Na WWDC 2024, a Apple recomendou usar o delegado para análises — registrar cada transição em 100 ms.

Trabalhando com legendas e faixas de áudio

O AVPlayerViewController exibe automaticamente todas as legendas e faixas de áudio disponíveis se estiverem incorporadas no arquivo de mídia ou especificadas no manifesto HLS. Os usuários podem alterná-las através do menu que aparece ao tocar no ícone de legendas na barra de transporte.

Para streams HLS, o manifesto M3U8 contém uma lista de variantes de idioma disponíveis. O AVPlayer carrega os segmentos de legenda WebVTT correspondentes e os passa para o AVPlayerLayer para renderização. O iOS 16+ introduziu suporte para estilização de legendas através do AVTextStyleRule.

Seleção programática de faixa de áudio

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

O método selectAudioTrack busca entre as opções de áudio do grupo audible pela variante cujo extendedLanguageTag corresponde ao código de idioma desejado. Isso permite implementar o recurso “Áudio original” em aplicativos com conteúdo multilíngue.

Picture in Picture no iPad

O modo Picture in Picture (PiP) permite exibir vídeo em uma janela flutuante sobre outros aplicativos. No iPad, este recurso está disponível desde o iOS 9, no iPhone — desde o iOS 14. O AVPlayerViewController adiciona automaticamente um botão PiP à barra de transporte quando inscrito no UIBackgroundModes.

Para ativar o PiP, adicione a chave UIBackgroundModes com os valores audio e airplay ao Info.plist. Depois disso, um botão PiP aparece no controlador que, ao ser tocado, recolhe o vídeo em uma janela flutuante de 192x108 pontos.

Os eventos PiP são manipulados através do delegado: playerViewController(_:willStartPictureInPictureFromFullScreen:) e playerViewController(_:didStopPictureInPicture:). De acordo com o Apple HIG, o tamanho mínimo da janela PiP deve ser de pelo menos 120x68 pontos para manter a legibilidade do conteúdo.