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
- AVPlayerViewController
- SwiftUI VideoPlayer
- Bild-in-Bild
- AirPlay
- Transportsteuerungen und Wiedergabegeschwindigkeit
- Untertitel und Closed Captions
- Häufige Fehler
- Review-Checkliste
- Referenzen
Einrichtung
Audiokonfiguration
Konfiguriere die Audio-Session und die Hintergrundmodi vor der ersten Wiedergabe. Ohne diese Schritte schlagen PiP und Hintergrundaudio lautlos fehl.
- Füge den Hintergrundmodus
audiozuUIBackgroundModesin der Infoplist hinzu. - 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
- Kategorie der Audio-Session auf
.playbackgesetzt (siehe Einrichtung). - Hintergrundmodus
audioinUIBackgroundModes.
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
.playbackmitmode: .moviePlaybackgesetzt - Hintergrundmodus
audiozuUIBackgroundModesin Info.plist hinzugefügt -
AVPlayerViewControllerwird nicht abgeleitet (subclassed) - PiP-Wiederherstellungs-Delegat-Methode implementiert und ruft
completionHandler(true)auf -
AVPlayerin SwiftUI in.taskverzögert (nicht vorzeitig erstellt) -
canStartPictureInPictureAutomaticallyFromInlinefür Inline-Player gesetzt -
requiresLinearPlaybacknur bei erforderlichen Werbe-/Rechtssegmenten umgeschaltet -
allowsExternalPlaybackaufAVPlayerfür AirPlay-Unterstützung aktiviert - Beschränkungen für Untertitel-Sprachen mit tatsächlichen Medienspuren getestet
- Video-Gravity angemessen eingestellt (
.resizeAspectvs..resizeAspectFill) -
isReadyForDisplaybeobachtet, bevor die Player-Ansicht angezeigt wird - Fehlerbehandlung für netzwerkgestreamte Inhalte (HLS-Fehler, Zeitüberschreitungen)
Referenzen
- Erweiterte Muster (benutzerdefinierte Player-UI, Interstitials, Hintergrundwiedergabe, Fehlerbehandlung): referenzen/avkit-patterns.md
- AVKit-Framework
- AVPlayerViewController
- VideoPlayer (SwiftUI)