AVKit
Interfaz de usuario de reproducción multimedia de alto nivel construida sobre AVFoundation. Proporciona reproductores de video estándar del sistema, Picture-in-Picture, enrutamiento AirPlay, controles de transporte y visualización de subtítulos/closed captions. Apunta a Swift 6.3 / iOS 26+.
Contenido
- Configuración
- AVPlayerViewController
- VideoPlayer de SwiftUI
- Picture-in-Picture
- AirPlay
- Controles de Transporte y Velocidad de Reproducción
- Subtítulos y Closed Captions
- Errores Comunes
- Lista de Verificación para Revisión
- Referencias
Configuración
Configuración de la Sesión de Audio
Configura la sesión de audio y los modos en segundo plano antes de cualquier reproducción. Sin esto, PiP y el audio en segundo plano fallan silenciosamente.
- Agrega el modo en segundo plano
audioaUIBackgroundModesen Info.plist - Establece la categoría de la sesión de audio en
.playback
import AVFoundation
func configureAudioSession() {
let session = AVAudioSession.sharedInstance()
do {
try session.setCategory(.playback, mode: .moviePlayback)
try session.setActive(true)
} catch {
print("La configuración de la sesión de audio falló: \(error)")
}
}
Importaciones
import AVKit // AVPlayerViewController, VideoPlayer, PiP
import AVFoundation // AVPlayer, AVPlayerItem, AVAsset
AVPlayerViewController
AVPlayerViewController es el reproductor UIKit estándar. Proporciona controles
de reproducción del sistema, PiP, AirPlay, subtítulos y análisis de fotogramas de forma nativa.
No lo subclases.
Presentación Básica (Pantalla Completa)
import AVKit
func presentPlayer(from viewController: UIViewController, url: URL) {
let player = AVPlayer(url: url)
let playerVC = AVPlayerViewController()
playerVC.player = player
viewController.present(playerVC, animated: true) {
player.play()
}
}
Reproducción Incrustada (Integrada)
Agrega AVPlayerViewController como un controlador hijo para reproducción incrustada.
Llama a addChild, agrega la vista con restricciones y luego llama a didMove(toParent:).
func embedPlayer(in parent: UIViewController, container: UIView, url: URL) {
let playerVC = AVPlayerViewController()
playerVC.player = AVPlayer(url: url)
parent.addChild(playerVC)
container.addSubview(playerVC.view)
playerVC.view.translatesAutoresizingMaskIntoConstraints = false
NSLayoutConstraint.activate([
playerVC.view.leadingAnchor.constraint(equalTo: container.leadingAnchor),
playerVC.view.trailingAnchor.constraint(equalTo: container.trailingAnchor),
playerVC.view.topAnchor.constraint(equalTo: container.topAnchor),
playerVC.view.bottomAnchor.constraint(equalTo: container.bottomAnchor)
])
playerVC.didMove(toParent: parent)
}
Propiedades Clave
playerVC.showsPlaybackControls = true // Mostrar/ocultar controles del sistema
playerVC.videoGravity = .resizeAspect // .resizeAspectFill para recortar
playerVC.entersFullScreenWhenPlaybackBegins = false
playerVC.exitsFullScreenWhenPlaybackEnds = true
playerVC.updatesNowPlayingInfoCenter = true // Actualiza MPNowPlayingInfoCenter automáticamente
Usa contentOverlayView para agregar vistas no interactivas (marcas de agua, logotipos)
entre el video y los controles de transporte.
Delegado
Adopta AVPlayerViewControllerDelegate para responder a transiciones de pantalla completa,
eventos del ciclo de vida de PiP, reproducción de intersticiales y cambios en la selección de medios.
Usa el coordinador de transición con animate(alongsideTransition:completion:) para
sincronizar tu interfaz de usuario con las animaciones de pantalla completa.
Estado de Visualización
Observa isReadyForDisplay antes de mostrar el reproductor para evitar un parpadeo negro:
let observation = playerVC.observe(\.isReadyForDisplay) { observed, _ in
if observed.isReadyForDisplay {
// Seguro para mostrar la vista del reproductor
}
}
VideoPlayer de SwiftUI
La vista SwiftUI VideoPlayer envuelve la interfaz de reproducción de AVKit.
Uso Básico
import SwiftUI
import AVKit
struct PlayerView: View {
@State private var player: AVPlayer?
var body: some View {
Group {
if let player {
VideoPlayer(player: player)
.frame(height: 300)
} else {
ProgressView()
}
}
.task {
let url = URL(string: "https://example.com/video.m3u8")!
player = AVPlayer(url: url)
}
}
}
Superposición de Video
Agrega una superposición SwiftUI no interactiva sobre el contenido de video.
VideoPlayer(player: player) {
VStack {
Spacer()
HStack {
Image("logo")
.resizable()
.frame(width: 40, height: 40)
.padding()
Spacer()
}
}
}
Alojamiento UIKit para Control Avanzado
VideoPlayer no expone todas las propiedades de AVPlayerViewController. Para configurar PiP,
callbacks de delegado o control de velocidad de reproducción, envuelve
AVPlayerViewController en un UIViewControllerRepresentable. Consulta el patrón completo
en referencias/patrones-avkit.md.
Picture-in-Picture
PiP permite a los usuarios ver video en una ventana flotante mientras usan otras aplicaciones.
AVPlayerViewController admite PiP automáticamente una vez que la sesión de audio está
configurada. Para interfaces de reproductor personalizadas, usa AVPictureInPictureController directamente.
Prerrequisitos
- Categoría de sesión de audio configurada en
.playback(ver Configuración) - Modo en segundo plano
audioenUIBackgroundModes
PiP del Reproductor Estándar
PiP está habilitado por defecto en AVPlayerViewController. Controla la activación
automática y las transiciones de incrustado a PiP:
let playerVC = AVPlayerViewController()
playerVC.player = player
// PiP habilitado por defecto; establece false para deshabilitar
playerVC.allowsPictureInPicturePlayback = true
// Inicia PiP automáticamente cuando la app pasa a segundo plano (para reproductores incrustados/no pantalla completa)
playerVC.canStartPictureInPictureAutomaticallyFromInline = true
Restaurar la Interfaz de Usuario Cuando PiP se Detiene
Cuando el usuario toca el botón de restaurar en PiP, implementa el método del delegado para
volver a presentar tu reproductor. Llama al controlador de finalización con true para indicar al
sistema que finalice la animación de restauración.
func playerViewController(
_ playerViewController: AVPlayerViewController,
restoreUserInterfaceForPictureInPictureStopWithCompletionHandler completionHandler: @escaping (Bool) -> Void
) {
// Vuelve a presentar o incrustar el controlador de vista del reproductor
present(playerViewController, animated: false) {
completionHandler(true)
}
}
PiP del Reproductor Personalizado
Para interfaces de reproductor personalizadas, usa AVPictureInPictureController con un AVPlayerLayer
o una fuente de contenido de búfer de muestra. Verifica primero isPictureInPictureSupported().
Consulta referencias/patrones-avkit.md para patrones completos de reproductor personalizado y PiP con búfer de muestra.
guard AVPictureInPictureController.isPictureInPictureSupported() else { return }
let pipController = AVPictureInPictureController(playerLayer: playerLayer)
pipController.delegate = self
pipController.canStartPictureInPictureAutomaticallyFromInline = true
Reproducción Lineal Durante Anuncios
Evita la búsqueda durante anuncios o avisos legales alternando requiresLinearPlayback:
// Durante un anuncio
playerVC.requiresLinearPlayback = true
// Después de que el anuncio termine
playerVC.requiresLinearPlayback = false
AirPlay
AVPlayerViewController admite AirPlay automáticamente. No se requiere código adicional
cuando se usa el reproductor estándar. El sistema muestra el botón de AirPlay en los controles
de transporte cuando hay dispositivos compatibles con AirPlay disponibles.
AVRoutePickerView
Agrega un botón selector de ruta AirPlay independiente fuera de la interfaz del reproductor:
import AVKit
func addRoutePicker(to containerView: UIView) {
let routePicker = AVRoutePickerView(frame: CGRect(x: 0, y: 0, width: 44, height: 44))
routePicker.activeTintColor = .systemBlue
routePicker.prioritizesVideoDevices = true // Muestra primero las rutas compatibles con video
containerView.addSubview(routePicker)
}
Habilitar Reproducción Externa
Asegúrate de que AVPlayer permita la reproducción externa (habilitada por defecto):
player.allowsExternalPlayback = true
player.usesExternalPlaybackWhileExternalScreenIsActive = true
Controles de Transporte y Velocidad de Reproducción
Velocidades de Reproducción Personalizadas
Proporciona velocidades de reproducción seleccionables por el usuario en la interfaz del reproductor:
let playerVC = AVPlayerViewController()
playerVC.speeds = [
AVPlaybackSpeed(rate: 0.5, localizedName: "Media Velocidad"),
AVPlaybackSpeed(rate: 1.0, localizedName: "Normal"),
AVPlaybackSpeed(rate: 1.5, localizedName: "1.5x"),
AVPlaybackSpeed(rate: 2.0, localizedName: "Doble Velocidad")
]
Usa AVPlaybackSpeed.systemDefaultSpeeds para restaurar las opciones de velocidad predeterminadas.
Comportamiento de Salto
Configura los controles de salto hacia adelante/atrás:
playerVC.isSkipForwardEnabled = true
playerVC.isSkipBackwardEnabled = true
Integración con Now Playing
AVPlayerViewController actualiza MPNowPlayingInfoCenter automáticamente de forma
predeterminada. Deshabilita esto si gestionas la información de Now Playing manualmente:
playerVC.updatesNowPlayingInfoCenter = false
Subtítulos y Closed Captions
AVKit maneja la visualización de subtítulos y closed captions automáticamente cuando el medio contiene pistas de texto apropiadas. Los usuarios controlan las preferencias de subtítulos en Configuración > Accesibilidad > Subtítulos y subtítulos opcionales.
Restringir Idiomas de Subtítulos
// Muestra solo opciones de subtítulos en inglés y español
playerVC.allowedSubtitleOptionLanguages = ["en", "es"]
Exigir Subtítulos
Obliga a que los subtítulos se muestren siempre (el usuario no puede desactivarlos):
playerVC.requiresFullSubtitles = true
Selección de Medios (Delegado)
Responde a los cambios del usuario en la selección de pistas de subtítulos o audio:
func playerViewController(
_ playerViewController: AVPlayerViewController,
didSelect mediaSelectionOption: AVMediaSelectionOption?,
in mediaSelectionGroup: AVMediaSelectionGroup
) {
if let option = mediaSelectionOption {
print("Seleccionado: \(option.displayName)")
}
}
Proporcionar Pistas de Subtítulos en HLS
Los subtítulos y closed captions están incrustados en los manifiestos HLS. AVKit los lee
desde AVMediaSelectionGroup en el AVAsset. Para archivos locales, usa
AVMutableComposition para agregar pistas con AVMediaCharacteristic.legible.
Errores Comunes
NO HAGAS: Subclases de AVPlayerViewController
Apple declara explícitamente que esto no es compatible. Puede causar comportamiento indefinido o bloqueo en futuras versiones del sistema operativo.
// INCORRECTO
class MyPlayerVC: AVPlayerViewController { } // No compatible
// CORRECTO: Usa composición con delegación
let playerVC = AVPlayerViewController()
playerVC.delegate = coordinator
NO HAGAS: Omitir la configuración de la sesión de audio para PiP
PiP falla silenciosamente si la sesión de audio no está configurada en .playback. El audio
en segundo plano también deja de funcionar.
// INCORRECTO: Sesión de audio predeterminada
let playerVC = AVPlayerViewController()
playerVC.player = player // PiP no funcionará
// CORRECTO: Configura la sesión de audio primero
try AVAudioSession.sharedInstance().setCategory(.playback, mode: .moviePlayback)
try AVAudioSession.sharedInstance().setActive(true)
let playerVC = AVPlayerViewController()
playerVC.player = player
NO HAGAS: Olvidar el delegado de restauración de PiP o su controlador de finalización
Sin restoreUserInterfaceForPictureInPictureStopWithCompletionHandler, el
sistema no puede devolver al usuario a tu reproductor. No llamar a
completionHandler(true) deja al sistema en un estado inconsistente.
// INCORRECTO: Sin método de delegado o falta la llamada a completionHandler
// El usuario toca restaurar en PiP -> no pasa nada o la animación se cuelga
// CORRECTO
func playerViewController(
_ playerViewController: AVPlayerViewController,
restoreUserInterfaceForPictureInPictureStopWithCompletionHandler completionHandler: @escaping (Bool) -> Void
) {
present(playerViewController, animated: false) {
completionHandler(true)
}
}
NO HAGAS: Crear AVPlayer en el init de una vista SwiftUI
Crear el reproductor de forma anticipada causa problemas de rendimiento. SwiftUI puede recrear la vista múltiples veces.
// INCORRECTO: Creado en cada init de la vista
struct PlayerView: View {
let player = AVPlayer(url: videoURL) // Se recrea en cada evaluación de la vista
var body: some View { VideoPlayer(player: player) }
}
// CORRECTO: Usa @State y difiere la creación
struct PlayerView: View {
@State private var player: AVPlayer?
var body: some View {
VideoPlayer(player: player)
.task { player = AVPlayer(url: videoURL) }
}
}
Lista de Verificación para Revisión
- Categoría de sesión de audio configurada en
.playbackconmode: .moviePlayback - Modo en segundo plano
audioagregado aUIBackgroundModesen Info.plist -
AVPlayerViewControllerno está subclasado - Método de delegado de restauración de PiP implementado y llama a
completionHandler(true) -
AVPlayerdiferido a.tasken SwiftUI (no creado de forma anticipada) -
canStartPictureInPictureAutomaticallyFromInlineconfigurado para reproductores incrustados -
requiresLinearPlaybackalternado solo durante segmentos requeridos de anuncios/legales -
allowsExternalPlaybackhabilitado enAVPlayerpara compatibilidad con AirPlay - Restricciones de idioma de subtítulos probadas con pistas de medios reales
- Gravedad de video configurada apropiadamente (
.resizeAspectvs.resizeAspectFill) -
isReadyForDisplayobservado antes de mostrar la vista del reproductor - Manejo de errores para contenido transmitido por red (fallos HLS, tiempos de espera)
Referencias
- Patrones avanzados (interfaz de reproductor personalizada, intersticiales, reproducción en segundo plano, manejo de errores): referencias/patrones-avkit.md
- Framework AVKit
- AVPlayerViewController
- VideoPlayer (SwiftUI)
…
[truncado para traducción]