AVPlayerViewController: cos'è, metodi di integrazione in iOS

Cos'è AVPlayerViewController?

AVPlayerViewController è un componente del framework AVKit che fornisce un'interfaccia pronta per riprodurre video nelle applicazioni Apple. Solleva lo sviluppatore dalla necessità di creare un lettore personalizzato da zero, offrendo controlli standard: riproduzione/pausa, avanzamento, regolazione del volume e modalità schermo intero.

A differenza di AVPlayerLayer di basso livello, che richiede la costruzione manuale dell'interfaccia utente, AVPlayerViewController gestisce completamente il ciclo di vita del lettore. Il controller gestisce automaticamente la rotazione dello schermo, si adatta all'area sicura sugli iPhone con notch e supporta il multitasking su iPad.

Secondo la Documentazione Apple (2026), AVPlayerViewController è compatibile con AVPlayer e AVQueuePlayer, consentendo di riprodurre sia file singoli che playlist. Sono supportati URL da archiviazione locale, flussi di rete HLS e contenuti FairPlay crittografati.

Storia e versioni di AVPlayerViewController

Il componente è apparso in iOS 8 insieme ad AVKit come sostituto del deprecato MPMoviePlayerController. In iOS 11 è stato aggiunto il supporto per Picture in Picture e la visualizzazione dei sottotitoli. In iOS 14, il controller ha ricevuto una barra di trasporto personalizzabile tramite AVPlayerViewControllerDelegate. A partire da iOS 16, è stato introdotto il supporto per la sostituzione dinamica dei file multimediali senza ricreare il lettore.

L'AVPlayerViewController moderno è ottimizzato per i display ProMotion — la frequenza dei fotogrammi video si sincronizza automaticamente con la frequenza di aggiornamento dello schermo. Su tvOS, il componente si adatta all'interfaccia di focus del Siri Remote e su macOS alla modalità finestra del QuickTime Player.

Come funziona AVPlayerViewController

Al centro del controller si trova l'abbinamento di AVPlayer e AVPlayerItem. AVPlayer è l'oggetto di riproduzione che gestisce la timeline, la velocità e lo stato. AVPlayerItem è un wrapper attorno a un file multimediale specifico, contenente metadati, tracce e informazioni di caricamento.

Quando viene inizializzato, AVPlayerViewController riceve un riferimento ad AVPlayer e crea automaticamente un AVPlayerLayer per visualizzare il video. Il controller si abbina alle notifiche KVO di AVPlayer sui cambiamenti di stato come readyToPlay, errori di caricamento e completamento della riproduzione.

I controlli (barra di trasporto) vengono visualizzati toccando lo schermo. In iOS 15+, supportano la personalizzazione tramite AVPlayerViewControllerCustomizationDelegate, consentendo di nascondere o sostituire i pulsanti standard.

Ciclo di vita del controller

Dopo aver creato il controller e assegnato AVPlayer, viene chiamato il metodo viewDidLoad, che inizia a preparare il flusso video. Quando AVPlayerItem passa allo stato AVPlayerItemStatusReadyToPlay, il lettore è pronto per visualizzare i fotogrammi. Quando viene chiamato il metodo play(), inizia la decodifica del flusso video tramite Video Toolbox.

Quando si lascia lo schermo, il controller mette automaticamente in pausa la riproduzione e rilascia le risorse del decodificatore. In iOS 13+, per mantenere la riproduzione quando l'app viene minimizzata, è necessario configurare le Modalità di background e la Sessione audio. Secondo WWDC 2024, si consiglia di utilizzare AVPlayerPlaybackCoordinator per la sincronizzazione con il centro multimediale iOS.

Caratteristiche principali di AVPlayerViewController

Il componente fornisce un ricco set di funzionalità pronte all'uso, rendendolo interessante per la maggior parte dei progetti. Di seguito sono elencate le capacità principali che non richiedono codice aggiuntivo.

• Barra di trasporto con riproduzione/pausa, salto di 15 secondi, controllo del volume e cursore di avanzamento.
• Supporto sottotitoli — visualizzazione automatica di sottotitoli incorporati ed esterni nei formati VTT, SRT e iTunes Timed Text.
• AirPlay — possibilità di trasmettere video ad Apple TV e altri dispositivi compatibili con AirPlay.
• Picture in Picture — riproduzione in una finestra fluttuante toccando un pulsante speciale (su iPad e iPhone con iOS 14+).
• Modalità schermo intero — commutazione automatica quando si ruota il dispositivo e quando si tocca il pulsante di ingrandimento.
• Controllo velocità — controllo integrato per selezionare la velocità di riproduzione (0,5x, 1,0x, 1,5x, 2,0x).
• Contenuti protetti — supporto nativo per FairPlay Streaming per contenuti HLS con DRM.

Barra di trasporto di AVPlayerViewController

La barra di trasporto è la parte inferiore dell'interfaccia che contiene i pulsanti di controllo principali. Per impostazione predefinita, la barra si nasconde dopo 3 secondi di inattività dell'utente e appare al tocco. In iOS 16+, il delegato può essere utilizzato per controllare la visibilità dei singoli elementi.

In modalità debug, la barra di trasporto può essere forzata a mostrarsi utilizzando la proprietà AVPlayerViewController.requiresLinearPlayback, che impedisce anche la messa in pausa del video. Utile per interruzioni pubblicitarie e contenuti educativi.

Integrazione di AVPlayerViewController nel tuo progetto

L'integrazione di base del controller non richiede più di 10 righe di codice. Innanzitutto, crea un'istanza di AVPlayer con l'URL del file multimediale, quindi passala ad AVPlayerViewController e visualizza il controller sullo schermo.

Creazione di un lettore di base in 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()
}

Dopo aver chiamato present, il controller viene visualizzato a schermo intero. Il video inizia a caricarsi dalla rete e, una volta che il buffer raggiunge la soglia readyToPlay, la riproduzione inizia automaticamente dopo la chiamata a play().

Configurazione di AVPlayerItem per il controllo avanzato

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

let metadata = AVMutableMetadataItem()
metadata.key = AVMetadataKey.commonKeyTitle
metadata.value = "Il Mio Video"
item.addMetadata(metadata)

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

L'uso di AVPlayerItem ti dà il controllo su metadati, timecode, selezione delle tracce audio e sottotitoli. Tramite AVPlayerItem, puoi anche monitorare l'avanzamento del caricamento, il buffering e gli errori di rete utilizzando KVO sulla proprietà status.

Personalizzazione dei controlli

A partire da iOS 11, gli sviluppatori possono personalizzare la barra di trasporto tramite il protocollo AVPlayerViewControllerDelegate. Il metodo playerViewController(_:willBeginFullScreenPresentationWithAnimationCoordinator:) viene chiamato prima di entrare in modalità schermo intero e consente di preparare l'interfaccia utente.

Per nascondere i singoli pulsanti, usa la proprietà AVPlayerViewController.showsPlaybackControls. Se impostata su false, la barra di trasporto scompare completamente, lasciando solo il flusso video. Utile per elementi sovrapposti personalizzati.

Personalizzazione tramite il delegato

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
    ) {
        // Aggiungi pulsante overlay
    }

    func playerViewController(
        _ playerViewController: AVPlayerViewController,
        didUpdate legibleMediaSelection: AVMediaSelectionGroup
    ) {
        print("Nuova lingua sottotitoli selezionata")
    }
}

Il delegato consente di intercettare gli eventi di cambio sottotitoli, l'entrata e l'uscita dalla modalità schermo intero, nonché l'avvio e la fine di Picture in Picture. Alla WWDC 2024, Apple ha raccomandato di utilizzare il delegato per l'analisi — registrare ogni transizione entro 100 ms.

Lavorare con sottotitoli e tracce audio

AVPlayerViewController visualizza automaticamente tutti i sottotitoli e le tracce audio disponibili se sono incorporati nel file multimediale o specificati nel manifesto HLS. Gli utenti possono cambiarli tramite il menu che appare toccando l'icona dei sottotitoli nella barra di trasporto.

Per i flussi HLS, il manifesto M3U8 contiene un elenco di varianti linguistiche disponibili. AVPlayer carica i segmenti di sottotitoli WebVTT corrispondenti e li passa ad AVPlayerLayer per il rendering. iOS 16+ ha introdotto il supporto per lo stile dei sottotitoli tramite AVTextStyleRule.

Selezione programmatica della traccia 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)
        }
    }
}

Il metodo selectAudioTrack cerca tra le opzioni audio del gruppo audible la variante il cui extendedLanguageTag corrisponde al codice lingua desiderato. Ciò consente di implementare la funzione “Audio originale” nelle app con contenuti multilingue.

Picture in Picture su iPad

La modalità Picture in Picture (PiP) consente di visualizzare il video in una finestra fluttuante sopra altre app. Su iPad, questa funzione è disponibile da iOS 9, su iPhone da iOS 14. AVPlayerViewController aggiunge automaticamente un pulsante PiP alla barra di trasporto quando si è abbonati a UIBackgroundModes.

Per attivare PiP, aggiungi la chiave UIBackgroundModes con i valori audio e airplay a Info.plist. Successivamente, appare un pulsante PiP nel controller che, quando toccato, riduce il video in una finestra fluttuante di 192x108 punti.

Gli eventi PiP vengono gestiti tramite il delegato: playerViewController(_:willStartPictureInPictureFromFullScreen:) e playerViewController(_:didStopPictureInPicture:). Secondo Apple HIG, la dimensione minima della finestra PiP dovrebbe essere di almeno 120x68 punti per mantenere la leggibilità del contenuto.