Communitygithub.com

JordanCoin/ios-skills-collection

Crea experiencias de reproducción multimedia usando AVKit. Úsalo para añadir reproductores de video con AVPlayerViewController, activar Picture-in-Picture, enrutar contenido con AirPlay, usar vistas VideoPlayer de SwiftUI, configurar controles de transporte, mostrar subtítulos y closed captions, o integrar la reproducción de AVFoundation con la interfaz del sistema.

¿Qué es ios-skills-collection?

Esta habilidad proporciona una guía completa para implementar experiencias de reproducción multimedia en iOS utilizando AVKit, el framework de alto nivel de Apple construido sobre AVFoundation. Está diseñada para desarrolladores que trabajan con Swift 6.3 e iOS 26+, y cubre el uso de AVPlayerViewController para reproducción a pantalla completa o incrustada, el componente VideoPlayer de SwiftUI para integraciones modernas, y la configuración de Picture-in-Picture (PiP) para reproducción en segundo plano o multitarea. También incluye soporte para AirPlay, permitiendo el enrutamiento a dispositivos externos como Apple TV, así como la gestión de controles de transporte, velocidades de reproducción personalizadas, y subtítulos/closed captions. Además, la habilidad detalla errores comunes como no configurar la sesión de audio para PiP o subclasificar AVPlayerViewController, y ofrece una lista de verificación para revisiones de código. Es útil para cualquier agente de IA que necesite implementar reproductores de video con funcionalidades estándar del sistema, asegurando una integración robusta y evitando fallos silenciosos.

Compatible con~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/JordanCoin/ios-skills-collection/tree/HEAD/skills/dpearson2699--avkit

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

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

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.

  1. Agrega el modo en segundo plano audio a UIBackgroundModes en Info.plist
  2. 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

  1. Categoría de sesión de audio configurada en .playback (ver Configuración)
  2. Modo en segundo plano audio en UIBackgroundModes

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 .playback con mode: .moviePlayback
  • Modo en segundo plano audio agregado a UIBackgroundModes en Info.plist
  • AVPlayerViewController no está subclasado
  • Método de delegado de restauración de PiP implementado y llama a completionHandler(true)
  • AVPlayer diferido a .task en SwiftUI (no creado de forma anticipada)
  • canStartPictureInPictureAutomaticallyFromInline configurado para reproductores incrustados
  • requiresLinearPlayback alternado solo durante segmentos requeridos de anuncios/legales
  • allowsExternalPlayback habilitado en AVPlayer para compatibilidad con AirPlay
  • Restricciones de idioma de subtítulos probadas con pistas de medios reales
  • Gravedad de video configurada apropiadamente (.resizeAspect vs .resizeAspectFill)
  • isReadyForDisplay observado antes de mostrar la vista del reproductor
  • Manejo de errores para contenido transmitido por red (fallos HLS, tiempos de espera)

Referencias

…

[truncado para traducción]

Individual skills in this repo

This repo contains 11 individual skills — each has its own dedicated page.

JordanCoin/ios-skills-collection

Interact with GitHub using the `gh` CLI. Use `gh issue`, `gh pr`, `gh run`, and `gh api` for issues, PRs, CI runs, and advanced queries. Use when the user asks about GitHub issues, pull requests, workflows, or wants to interact with GitHub repositories from the command line — including tasks like check CI status, create PR, list issues, or query the GitHub API.

JordanCoin/ios-skills-collection

Integrate and optimize Core ML models in iOS apps for on-device machine learning inference. Covers model loading (.mlmodelc, .mlpackage), predictions with auto-generated classes and MLFeatureProvider, compute unit configuration (CPU, GPU, Neural Engine), MLTensor, VNCoreMLRequest, MLComputePlan, multi-model pipelines, and deployment strategies. Use when loading Core ML models, making predictions, configuring compute units, or profiling model performance.

JordanCoin/ios-skills-collection

Implement, review, or improve maps and location features in iOS/macOS apps using MapKit and CoreLocation. Use when working with Map views, annotations, markers, polylines, user location tracking, geocoding, reverse geocoding, search/autocomplete, directions and routes, geofencing, region monitoring, CLLocationUpdate async streams, or location authorization flows. Also use when working with maps, coordinates, addresses, places, directions, distance calculations, or location-based features in Swift apps.

JordanCoin/ios-skills-collection

Display and manipulate PDF documents using PDFKit. Use when embedding PDFView to show PDF files, creating or modifying PDFDocument instances, adding annotations (highlights, notes, signatures), extracting text with PDFSelection, navigating pages, generating thumbnails, filling PDF forms, or wrapping PDFView in SwiftUI.

JordanCoin/ios-skills-collection

Implement, review, or improve in-app tips and onboarding using Apple's TipKit framework. Use when adding feature discovery tooltips, onboarding flows, contextual tips, first-run experiences, coach marks, or working with Tip protocol, TipView, popoverTip, tip rules, tip events, or feature education UI.

JordanCoin/ios-skills-collection

When the user wants to optimize their Google Play Store listing — title, short description, full description, keywords, ratings, or Play Store-specific features. Use when the user mentions "Google Play", "Android", "Play Store", "Play Console", "short description", "full description indexed", "Google Play ASO", or wants Google Play-specific keyword, creative, or ratings strategy. For iOS App Store optimization, see aso-audit and metadata-optimization.

JordanCoin/ios-skills-collection

When the user wants to implement, optimize, or use App Clips for app discovery and conversion. Use when the user mentions "App Clip", "app clip code", "mini app", "instant app", "App Clip card", "App Clip link", "no download required", "instant experience", or wants to understand how App Clips appear in App Store search. For general App Store discoverability, see aso-audit. For marketing campaigns, see ua-campaign.

JordanCoin/ios-skills-collection

When the user wants to plan a launch strategy for a new app or major update. Also use when the user mentions "app launch", "launch plan", "launch checklist", "pre-launch", "launch day", or "how to launch my app". For ongoing ASO after launch, see aso-audit. For paid acquisition during launch, see ua-campaign.

JordanCoin/ios-skills-collection

When the user wants to analyze their own app's actual performance data from App Store Connect — real downloads, revenue, IAP, subscriptions, trials, or country breakdowns synced via Appeeky Connect. Use when the user asks about "my downloads", "my revenue", "how is my app performing", "ASC data", "sales and trends", "my subscription numbers", "App Store Connect metrics", or wants to compare periods or top markets. For third-party app estimates, see app-analytics. For subscription analytics depth, see monetization-strategy.

JordanCoin/ios-skills-collection

When the user wants a full ASO health audit, review their App Store listing quality, or diagnose why their app isn't ranking. Also use when the user mentions "ASO audit", "ASO score", "why am I not ranking", "listing review", or "optimize my app store page". For keyword-specific research, see keyword-research. For metadata writing, see metadata-optimization.

JordanCoin/ios-skills-collection

Always use when working on any iOS, macOS, Swift, SwiftUI, Xcode, or Apple platform project. Routes to the correct specialized skills based on development phase and task context. This collection contains 210 skills from 28 authors covering the full iOS lifecycle.

Skills relacionados