Communitygithub.com

JordanCoin/ios-skills-collection

Erstelle Media-Player-Erlebnisse mit AVKit. Verwende es, wenn du Video-Player mit AVPlayerViewController hinzufügst, Bild-in-Bild aktivierst, Medien per AirPlay weiterleitest, SwiftUI VideoPlayer-Ansichten verwendest, Transportsteuerungen konfigurierst, Untertitel und Closed Captions anzeigst oder die AVFoundation-Wiedergabe mit der System-UI integrierst.

Was ist ios-skills-collection?

Diese AVKit-Fertigkeit ist für Entwickler konzipiert, die hochwertige Media-Player-Erlebnisse in iOS-Apps (Swift 6.3 / iOS 26+) erstellen. Sie behandelt die wichtigsten AVKit-Komponenten wie AVPlayerViewController (für UIKit mit Vollbild- und Inline-Wiedergabe), die SwiftUI VideoPlayer-Ansicht, die automatische Bild-in-Bild-Integration (PiP) und die AirPlay-Unterstützung. Die Fertigkeit bietet klare, ausführbare Code-Beispiele für die Konfiguration von Audio-Sessions, Steuerung der Transport-Controls und Wiedergabegeschwindigkeit, Verwaltung von Untertiteln und Closed Captions sowie Vermeidung häufiger Fehler (z. B. das Subklassifizieren von AVPlayerViewController oder das Vergessen der PiP-Wiederherstellungsmethode). Sie enthält auch eine Checkliste für Code-Reviews und Verweise auf erweiterte Muster (benutzerdefinierte Player-UI, Interstitials, Hintergrundwiedergabe). Ideal für die Integration von AU-Player-Funktionen in vorhandene Projekte oder für die Entwicklung neuer Medien-Apps mit nativer Systemunterstützung.

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

In Ihrer bevorzugten KI fragen

Öffnet einen neuen Chat, in dem dieser Agent-Skill bereits geladen ist.

Dokumentation

AVKit

Hochwertige Media-Player-Benutzeroberfläche auf Basis von AVFoundation. Bietet systemstandardisierte Video-Player, Bild-in-Bild (Picture-in-Picture), AirPlay-Routing, Transportsteuerungen und Untertitel-/Caption-Anzeige. Zielplattform: Swift 6.3 / iOS 26+.

Inhaltsverzeichnis

Einrichtung

Audiokonfiguration

Konfiguriere die Audio-Session und die Hintergrundmodi vor der ersten Wiedergabe. Ohne diese Schritte schlagen PiP und Hintergrundaudio lautlos fehl.

  1. Füge den Hintergrundmodus audio zu UIBackgroundModes in der Infoplist hinzu.
  2. Setze die Kategorie der Audio-Session auf .playback.
import AVFoundation

func configureAudioSession() {
    let session = AVAudioSession.sharedInstance()
    do {
        try session.setCategory(.playback, mode: .moviePlayback)
        try session.setActive(true)
    } catch {
        print("Konfiguration der Audio-Session fehlgeschlagen: \(error)")
    }
}

Imports

import AVKit          // AVPlayerViewController, VideoPlayer, PiP
import AVFoundation   // AVPlayer, AVPlayerItem, AVAsset

AVPlayerViewController

AVPlayerViewController ist der standardmäßige UIKit-Player. Er bietet sofort einsatzbereit System-Playback-Steuerungen, PiP, AirPlay, Untertitel und Bildanalyse. Nicht ableiten (subclassing).

Grundlegende Darstellung (Vollbild)

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

Inline (Eingebettete) Wiedergabe

Füge AVPlayerViewController als untergeordneten View-Controller für die Inline-Wiedergabe hinzu. Rufe addChild auf, füge die Ansicht mit Constraints hinzu und rufe dann didMove(toParent:) auf.

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

Wichtige Eigenschaften

playerVC.showsPlaybackControls = true                    // Systemsteuerungen ein-/ausblenden
playerVC.videoGravity = .resizeAspect                    // .resizeAspectFill zum Zuschneiden
playerVC.entersFullScreenWhenPlaybackBegins = false
playerVC.exitsFullScreenWhenPlaybackEnds = true
playerVC.updatesNowPlayingInfoCenter = true              // Automatische Aktualisierung von MPNowPlayingInfoCenter

Verwende contentOverlayView, um nicht interaktive Ansichten (Wasserzeichen, Logos) zwischen dem Video und den Transportsteuerungen zu platzieren.

Delegat

Implementiere AVPlayerViewControllerDelegate, um auf Vollbild-Übergänge, PiP-Lebenszyklus-Ereignisse, Interstitial-Wiedergabe und Medienauswahl-Änderungen zu reagieren. Verwende den Koordinator für Übergänge mit animate(alongsideTransition:completion:), um deine UI mit Vollbild-Animationen zu synchronisieren.

Anzeigebereitschaft

Beobachte isReadyForDisplay, bevor du den Player anzeigst, um einen schwarzen Blitz zu vermeiden:

let observation = playerVC.observe(\.isReadyForDisplay) { observed, _ in
    if observed.isReadyForDisplay {
        // Sicher, die Player-Ansicht anzuzeigen
    }
}

SwiftUI VideoPlayer

Die SwiftUI-Ansicht VideoPlayer kapselt die Wiedergabe-UI von AVKit.

Grundlegende Verwendung

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

Video-Overlay

Füge eine nicht interaktive SwiftUI-Overlay über dem Videoinhalt hinzu.

VideoPlayer(player: player) {
    VStack {
        Spacer()
        HStack {
            Image("logo")
                .resizable()
                .frame(width: 40, height: 40)
                .padding()
            Spacer()
        }
    }
}

UIKit-Hosting für erweiterte Steuerung

VideoPlayer gibt nicht alle Eigenschaften von AVPlayerViewController frei. Für PiP-Konfiguration, Delegat-Rückrufe oder Steuerung der Wiedergabegeschwindigkeit, kapsle AVPlayerViewController in ein UIViewControllerRepresentable. Das vollständige Muster findest du in referenzen/avkit-patterns.md.

Bild-in-Bild

PiP ermöglicht es Benutzern, Videos in einem schwebenden Fenster anzusehen, während sie andere Apps verwenden. AVPlayerViewController unterstützt PiP automatisch, sobald die Audio-Session konfiguriert ist. Für benutzerdefinierte Player-UI verwende direkt AVPictureInPictureController.

Voraussetzungen

  1. Kategorie der Audio-Session auf .playback gesetzt (siehe Einrichtung).
  2. Hintergrundmodus audio in UIBackgroundModes.

Standard-Player PiP

PiP ist standardmäßig bei AVPlayerViewController aktiviert. Steuere die automatische Aktivierung und Inline-zu-PiP-Übergänge:

let playerVC = AVPlayerViewController()
playerVC.player = player

// PiP standardmäßig aktiviert; auf false setzen zum Deaktivieren
playerVC.allowsPictureInPicturePlayback = true

// PiP automatisch starten, wenn die App in den Hintergrund geht (für Inline-/Nicht-Vollbild-Player)
playerVC.canStartPictureInPictureAutomaticallyFromInline = true

Wiederherstellen der UI beim Stoppen von PiP

Wenn der Benutzer die Wiederherstellen-Schaltfläche in PiP tippt, implementiere die Delegat-Methode, um deinen Player erneut anzuzeigen. Rufe den Completion-Handler mit true auf, um dem System zu signalisieren, dass die Wiederherstellungsanimation abgeschlossen werden kann.

func playerViewController(
    _ playerViewController: AVPlayerViewController,
    restoreUserInterfaceForPictureInPictureStopWithCompletionHandler completionHandler: @escaping (Bool) -> Void
) {
    // Player-View-Controller erneut anzeigen oder einbetten
    present(playerViewController, animated: false) {
        completionHandler(true)
    }
}

Benutzerdefinierter Player PiP

Für benutzerdefinierte Player-UI verwende AVPictureInPictureController mit einer AVPlayerLayer oder einer Sample-Buffer-Inhaltsquelle. Überprüfe zuerst isPictureInPictureSupported(). Vollständige Muster für benutzerdefinierte Player und Sample-Buffer-PiP findest du in referenzen/avkit-patterns.md.

guard AVPictureInPictureController.isPictureInPictureSupported() else { return }
let pipController = AVPictureInPictureController(playerLayer: playerLayer)
pipController.delegate = self
pipController.canStartPictureInPictureAutomaticallyFromInline = true

Lineare Wiedergabe während Werbung

Verhindere das Vor- oder Zurückspulen während Werbung oder rechtlicher Hinweise, indem du requiresLinearPlayback umschaltest:

// Während einer Werbung
playerVC.requiresLinearPlayback = true

// Nach Abschluss der Werbung
playerVC.requiresLinearPlayback = false

AirPlay

AVPlayerViewController unterstützt AirPlay automatisch. Es ist kein zusätzlicher Code erforderlich, wenn du den Standard-Player verwendest. Das System zeigt die AirPlay-Schaltfläche in den Transportsteuerungen an, wenn AirPlay-fähige Geräte verfügbar sind.

AVRoutePickerView

Füge eine eigenständige AirPlay-Routenauswahl-Schaltfläche außerhalb der Player-UI hinzu:

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  // Zeige videofähige Routen zuerst
    containerView.addSubview(routePicker)
}

Externe Wiedergabe aktivieren

Stelle sicher, dass AVPlayer die externe Wiedergabe erlaubt (standardmäßig aktiviert):

player.allowsExternalPlayback = true
player.usesExternalPlaybackWhileExternalScreenIsActive = true

Transportsteuerungen und Wiedergabegeschwindigkeit

Benutzerdefinierte Wiedergabegeschwindigkeiten

Biete benutzerwählbare Wiedergabegeschwindigkeiten in der Player-UI an:

let playerVC = AVPlayerViewController()
playerVC.speeds = [
    AVPlaybackSpeed(rate: 0.5, localizedName: "Halbe Geschwindigkeit"),
    AVPlaybackSpeed(rate: 1.0, localizedName: "Normal"),
    AVPlaybackSpeed(rate: 1.5, localizedName: "1.5x"),
    AVPlaybackSpeed(rate: 2.0, localizedName: "Doppelte Geschwindigkeit")
]

Verwende AVPlaybackSpeed.systemDefaultSpeeds, um die standardmäßigen Geschwindigkeitsoptionen wiederherzustellen.

Vor-/Zurückspulen-Verhalten

Konfiguriere die Vorwärts/Rückwärts-Sprungsteuerungen:

playerVC.isSkipForwardEnabled = true
playerVC.isSkipBackwardEnabled = true

Now Playing Integration

AVPlayerViewController aktualisiert MPNowPlayingInfoCenter standardmäßig automatisch. Deaktiviere dies, wenn du die Now-Playing-Informationen manuell verwaltest:

playerVC.updatesNowPlayingInfoCenter = false

Untertitel und Closed Captions

AVKit kümmert sich automatisch um die Anzeige von Untertiteln und Closed Captions, wenn das Medium entsprechende Textspuren enthält. Benutzer steuern die Untertitel-Einstellungen in Einstellungen > Bedienungshilfen > Untertitel & Beschriftungen.

Untertitel-Sprachen einschränken

// Zeige nur Englisch- und Spanisch-Untertiteloptionen
playerVC.allowedSubtitleOptionLanguages = ["en", "es"]

Untertitel erzwingen

Erzwinge die dauerhafte Anzeige von Untertiteln (der Benutzer kann sie nicht ausschalten):

playerVC.requiresFullSubtitles = true

Medienauswahl (Delegat)

Reagiere auf die Benutzerauswahl von Untertiteln oder Audiospuren:

func playerViewController(
    _ playerViewController: AVPlayerViewController,
    didSelect mediaSelectionOption: AVMediaSelectionOption?,
    in mediaSelectionGroup: AVMediaSelectionGroup
) {
    if let option = mediaSelectionOption {
        print("Ausgewählt: \(option.displayName)")
    }
}

Bereitstellen von Untertitel-Spuren in HLS

Untertitel und Closed Captions sind in HLS-Manifeste eingebettet. AVKit liest sie aus AVMediaSelectionGroup auf dem AVAsset. Für lokale Dateien verwende AVMutableComposition, um Spuren mit der AVMediaCharacteristic.legible-Eigenschaft hinzuzufügen.

Häufige Fehler

NICHT: AVPlayerViewController ableiten (subclassing)

Apple gibt ausdrücklich an, dass dies nicht unterstützt wird. Es kann zu undefiniertem Verhalten oder Abstürzen in zukünftigen OS-Versionen führen.

// FALSCH
class MyPlayerVC: AVPlayerViewController { } // Nicht unterstützt

// RICHTIG: Verwende Komposition mit Delegation
let playerVC = AVPlayerViewController()
playerVC.delegate = coordinator

NICHT: Audio-Session-Konfiguration für PiP überspringen

PiP schlägt lautlos fehl, wenn die Audio-Session nicht auf .playback gesetzt ist. Auch Hintergrundaudio funktioniert dann nicht mehr.

// FALSCH: Standard-Audio-Session
let playerVC = AVPlayerViewController()
playerVC.player = player // PiP funktioniert nicht

// RICHTIG: Audio-Session zuerst konfigurieren
try AVAudioSession.sharedInstance().setCategory(.playback, mode: .moviePlayback)
try AVAudioSession.sharedInstance().setActive(true)
let playerVC = AVPlayerViewController()
playerVC.player = player

NICHT: Den PiP-Wiederherstellungs-Delegaten (Delegate) oder seinen Completion-Handler vergessen

Ohne restoreUserInterfaceForPictureInPictureStopWithCompletionHandler kann das System den Benutzer nicht zu deinem Player zurückbringen. Wenn completionHandler(true) nicht aufgerufen wird, bleibt das System in einem inkonsistenten Zustand.

// FALSCH: Keine Delegat-Methode oder fehlender completionHandler-Aufruf
// Benutzer tippt auf „Wiederherstellen“ in PiP -> nichts passiert oder Animation hängt

// RICHTIG
func playerViewController(
    _ playerViewController: AVPlayerViewController,
    restoreUserInterfaceForPictureInPictureStopWithCompletionHandler completionHandler: @escaping (Bool) -> Void
) {
    present(playerViewController, animated: false) {
        completionHandler(true)
    }
}

NICHT: AVPlayer im Init einer SwiftUI-Ansicht erstellen

Ein vorzeitiges Erstellen des Players verursacht Leistungsprobleme. SwiftUI kann die Ansicht mehrmals neu erstellen.

// FALSCH: Wird bei jeder Init-Erstellung der Ansicht neu erstellt
struct PlayerView: View {
    let player = AVPlayer(url: videoURL) // Wird bei jeder Auswertung der Ansicht neu erstellt

    var body: some View { VideoPlayer(player: player) }
}

// RICHTIG: Verwende @State und verzögere die Erstellung
struct PlayerView: View {
    @State private var player: AVPlayer?

    var body: some View {
        VideoPlayer(player: player)
            .task { player = AVPlayer(url: videoURL) }
    }
}

Review-Checkliste

  • Kategorie der Audio-Session auf .playback mit mode: .moviePlayback gesetzt
  • Hintergrundmodus audio zu UIBackgroundModes in Info.plist hinzugefügt
  • AVPlayerViewController wird nicht abgeleitet (subclassed)
  • PiP-Wiederherstellungs-Delegat-Methode implementiert und ruft completionHandler(true) auf
  • AVPlayer in SwiftUI in .task verzögert (nicht vorzeitig erstellt)
  • canStartPictureInPictureAutomaticallyFromInline für Inline-Player gesetzt
  • requiresLinearPlayback nur bei erforderlichen Werbe-/Rechtssegmenten umgeschaltet
  • allowsExternalPlayback auf AVPlayer für AirPlay-Unterstützung aktiviert
  • Beschränkungen für Untertitel-Sprachen mit tatsächlichen Medienspuren getestet
  • Video-Gravity angemessen eingestellt (.resizeAspect vs. .resizeAspectFill)
  • isReadyForDisplay beobachtet, bevor die Player-Ansicht angezeigt wird
  • Fehlerbehandlung für netzwerkgestreamte Inhalte (HLS-Fehler, Zeitüberschreitungen)

Referenzen

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.

Verwandte Skills