AVPlayerViewController: qué es, métodos de integración en iOS

¿Qué es AVPlayerViewController?

AVPlayerViewController es un componente del framework AVKit que proporciona una interfaz lista para reproducir video en aplicaciones Apple. Libera al desarrollador de tener que crear un reproductor personalizado desde cero, ofreciendo controles estándar: reproducir/pausar, avance rápido, ajuste de volumen y modo de pantalla completa.

A diferencia de AVPlayerLayer de bajo nivel, que requiere la construcción manual de la interfaz de usuario, AVPlayerViewController gestiona completamente el ciclo de vida del reproductor. El controlador maneja automáticamente la rotación de pantalla, se adapta al área segura en iPhones con notch y admite la multitarea en iPad.

Según la Documentación de Apple (2026), AVPlayerViewController es compatible con AVPlayer y AVQueuePlayer, lo que permite reproducir tanto archivos individuales como listas de reproducción. Se admiten URL de almacenamiento local, flujos de red HLS y contenido FairPlay cifrado.

Historia y versiones de AVPlayerViewController

El componente apareció en iOS 8 junto con AVKit como reemplazo del obsoleto MPMoviePlayerController. En iOS 11 se agregó soporte para Picture in Picture y visualización de subtítulos. En iOS 14, el controlador recibió una barra de transporte personalizable a través de AVPlayerViewControllerDelegate. A partir de iOS 16, se introdujo soporte para el reemplazo dinámico de archivos multimedia sin necesidad de recrear el reproductor.

El AVPlayerViewController moderno está optimizado para pantallas ProMotion — la frecuencia de cuadros del video se sincroniza automáticamente con la frecuencia de actualización de la pantalla. En tvOS, el componente se adapta a la interfaz de enfoque del Siri Remote, y en macOS, al modo de ventana de QuickTime Player.

Cómo funciona AVPlayerViewController

En el núcleo del controlador se encuentra el emparejamiento de AVPlayer y AVPlayerItem. AVPlayer es el objeto de reproducción que gestiona la línea de tiempo, la velocidad y el estado. AVPlayerItem es un envoltorio alrededor de un archivo multimedia específico, que contiene metadatos, pistas e información de carga.

Al inicializarse, AVPlayerViewController recibe una referencia a AVPlayer y crea automáticamente un AVPlayerLayer para mostrar el video. El controlador se suscribe a las notificaciones KVO de AVPlayer sobre cambios de estado como readyToPlay, errores de carga y finalización de la reproducción.

Los controles (barra de transporte) se muestran al tocar la pantalla. En iOS 15+, admiten personalización a través de AVPlayerViewControllerCustomizationDelegate, lo que permite ocultar o reemplazar botones estándar.

Ciclo de vida del controlador

Después de crear el controlador y asignar AVPlayer, se llama al método viewDidLoad, que comienza a preparar el flujo de video. Cuando AVPlayerItem transiciona al estado AVPlayerItemStatusReadyToPlay, el reproductor está listo para mostrar cuadros. Cuando se llama al método play(), comienza la decodificación del flujo de video a través de Video Toolbox.

Al salir de la pantalla, el controlador pausa automáticamente la reproducción y libera los recursos del decodificador. En iOS 13+, para mantener la reproducción cuando la aplicación se minimiza, es necesario configurar los Modos de fondo y la Sesión de audio. Según WWDC 2024, se recomienda usar AVPlayerPlaybackCoordinator para la sincronización con el centro multimedia de iOS.

Características principales de AVPlayerViewController

El componente proporciona un rico conjunto de funciones listas para usar, lo que lo hace atractivo para la mayoría de los proyectos. A continuación se presentan las capacidades clave que no requieren código adicional.

• Barra de transporte con reproducción/pausa, salto de 15 segundos, control de volumen y deslizador de progreso.
• Soporte de subtítulos — visualización automática de subtítulos incrustados y externos en formatos VTT, SRT y iTunes Timed Text.
• AirPlay — capacidad de transmitir video a Apple TV y otros dispositivos compatibles con AirPlay.
• Picture in Picture — reproducción en una ventana flotante al tocar un botón especial (en iPad y iPhone con iOS 14+).
• Modo de pantalla completa — cambio automático al rotar el dispositivo y al tocar el botón de ampliar.
• Control de velocidad — control incorporado para seleccionar la velocidad de reproducción (0.5x, 1.0x, 1.5x, 2.0x).
• Contenido protegido — soporte nativo para FairPlay Streaming para contenido HLS con DRM.

Barra de transporte de AVPlayerViewController

La barra de transporte es la parte inferior de la interfaz que contiene los botones principales de control. Por defecto, la barra se oculta después de 3 segundos de inactividad del usuario y aparece al tocar. En iOS 16+, se puede usar el delegado para controlar la visibilidad de elementos individuales.

En modo de depuración, la barra de transporte se puede forzar a mostrar usando la propiedad AVPlayerViewController.requiresLinearPlayback, que también evita que el video se pause. Esto es útil para pausas publicitarias y contenido educativo.

Integración de AVPlayerViewController en tu proyecto

La integración básica del controlador no lleva más de 10 líneas de código. Primero, crea una instancia de AVPlayer con la URL del archivo multimedia, luego pásala a AVPlayerViewController y muestra el controlador en pantalla.

Creación de un reproductor básico en 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()
}

Después de llamar a present, el controlador se muestra en pantalla completa. El video comienza a cargarse desde la red, y una vez que el búfer alcanza el umbral readyToPlay, la reproducción comienza automáticamente después de llamar a play().

Configuración de AVPlayerItem para control avanzado

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

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

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

Usar AVPlayerItem te da control sobre metadatos, códigos de tiempo, selección de pistas de audio y subtítulos. A través de AVPlayerItem, también puedes monitorear el progreso de carga, el buffering y los errores de red usando KVO en la propiedad status.

Personalización de controles

A partir de iOS 11, los desarrolladores pueden personalizar la barra de transporte a través del protocolo AVPlayerViewControllerDelegate. El método playerViewController(_:willBeginFullScreenPresentationWithAnimationCoordinator:) se llama antes de entrar en modo de pantalla completa y permite preparar la interfaz de usuario.

Para ocultar botones individuales, usa la propiedad AVPlayerViewController.showsPlaybackControls. Si se establece en false, la barra de transporte desaparece por completo, dejando solo el flujo de video. Útil para elementos superpuestos personalizados.

Personalización usando el 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
    ) {
        // Agregar botón superpuesto
    }

    func playerViewController(
        _ playerViewController: AVPlayerViewController,
        didUpdate legibleMediaSelection: AVMediaSelectionGroup
    ) {
        print("Nuevo idioma de subtítulos seleccionado")
    }
}

El delegado permite interceptar eventos de cambio de subtítulos, entrada y salida del modo de pantalla completa, así como inicio y fin de Picture in Picture. En WWDC 2024, Apple recomendó usar el delegado para análisis — registrar cada transición dentro de 100 ms.

Trabajar con subtítulos y pistas de audio

AVPlayerViewController muestra automáticamente todos los subtítulos y pistas de audio disponibles si están incrustados en el archivo multimedia o especificados en el manifiesto HLS. Los usuarios pueden cambiarlos a través del menú que aparece al tocar el icono de subtítulos en la barra de transporte.

Para flujos HLS, el manifiesto M3U8 contiene una lista de variantes de idioma disponibles. AVPlayer carga los segmentos de subtítulos WebVTT correspondientes y los pasa a AVPlayerLayer para su renderizado. iOS 16+ introdujo soporte para el estilo de subtítulos a través de AVTextStyleRule.

Selección programática de pista de 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)
        }
    }
}

El método selectAudioTrack busca entre las opciones de audio del grupo audible la variante cuyo extendedLanguageTag coincida con el código de idioma deseado. Esto permite implementar la función “Audio original” en aplicaciones con contenido multilingüe.

Picture in Picture en iPad

El modo Picture in Picture (PiP) permite mostrar video en una ventana flotante sobre otras aplicaciones. En iPad, esta función ha estado disponible desde iOS 9, en iPhone — desde iOS 14. AVPlayerViewController agrega automáticamente un botón PiP a la barra de transporte cuando se está suscrito a UIBackgroundModes.

Para activar PiP, agrega la clave UIBackgroundModes con los valores audio y airplay a Info.plist. Después de eso, aparece un botón PiP en el controlador que, al tocarlo, colapsa el video en una ventana flotante de 192x108 puntos.

Los eventos de PiP se manejan a través del delegado: playerViewController(_:willStartPictureInPictureFromFullScreen:) y playerViewController(_:didStopPictureInPicture:). Según Apple HIG, el tamaño mínimo de la ventana PiP debe ser de al menos 120x68 puntos para mantener la legibilidad del contenido.