AVKit
High-level media playback UI built on AVFoundation. Provides system-standard
video players, Picture-in-Picture, AirPlay routing, transport controls, and
subtitle/caption display. Targets Swift 6.4 / iOS 26+.
Contents
Workflow
- Define playback ownership, media source, audio-session policy, background behavior, and supported system controls.
- Choose
AVPlayerViewController for full system playback UI or SwiftUI VideoPlayer for simpler embedding.
- Keep
AVPlayer in stable state outside transient view initialization and observe readiness/errors deliberately.
- Configure Picture in Picture, AirPlay, Now Playing, subtitles, and seeking only when the product needs them.
- Verify interruptions, route changes, foreground/background transitions, PiP restoration, captions, and teardown.
Route by Task
- Read core implementation details for audio session, player controllers,
VideoPlayer, PiP, AirPlay, controls, and subtitles.
- Read extended AVKit patterns for custom player UI, interstitials, background playback, error handling, and advanced hosting.
Core Decisions
- Prefer system playback UI and delegation over subclassing
AVPlayerViewController.
- Configure the audio session for the intended playback/background contract.
- Complete every PiP restoration callback and retain objects required by PiP.
- Keep player identity and observation lifetime stable across SwiftUI body updates.
Common Mistakes
DON'T: Subclass AVPlayerViewController
Apple explicitly states this is unsupported. It may cause undefined behavior or
crash on future OS versions.
// WRONG
class MyPlayerVC: AVPlayerViewController { } // Unsupported
// CORRECT: Use composition with delegation
let playerVC = AVPlayerViewController()
playerVC.delegate = coordinator
DON'T: Skip audio session configuration for PiP
PiP and background playback depend on the playback audio session category and
the Audio, AirPlay, and Picture in Picture background mode.
// WRONG: Default audio session
let playerVC = AVPlayerViewController()
playerVC.player = player // PiP won't work
// CORRECT: Configure the category, then activate when playback starts
try AVAudioSession.sharedInstance().setCategory(.playback, mode: .moviePlayback)
try AVAudioSession.sharedInstance().setActive(true)
let playerVC = AVPlayerViewController()
playerVC.player = player
DON'T: Forget the PiP restore delegate or its completion handler
Without restoreUserInterfaceForPictureInPictureStopWithCompletionHandler, the
system cannot return the user to your player. Failing to call
completionHandler(true) leaves the system in an inconsistent state.
// WRONG: No delegate method or missing completionHandler call
// User taps restore in PiP -> nothing happens or animation hangs
// CORRECT
func playerViewController(
_ playerViewController: AVPlayerViewController,
restoreUserInterfaceForPictureInPictureStopWithCompletionHandler completionHandler: @escaping (Bool) -> Void
) {
present(playerViewController, animated: false) {
completionHandler(true)
}
}
DON'T: Create AVPlayer in a SwiftUI view's init
Creating the player eagerly causes performance issues. SwiftUI may recreate the
view multiple times.
// WRONG: Created on every view init
struct PlayerView: View {
let player = AVPlayer(url: videoURL) // Re-created on every view evaluation
var body: some View { VideoPlayer(player: player) }
}
// CORRECT: Use @State and defer creation
struct PlayerView: View {
@State private var player: AVPlayer?
var body: some View {
VideoPlayer(player: player)
.task { player = AVPlayer(url: videoURL) }
}
}
Review Checklist
References
1---2name: avkit3description: "Create media playback experiences using AVKit. Use when adding video players with AVPlayerViewController, enabling Picture-in-Picture, routing media with AirPlay, using SwiftUI VideoPlayer views, configuring transport controls, displaying subtitles and closed captions, or integrating AVFoundation playback with system UI."4metadata:5 source: https://skillmd.com/skills/thiennc-tesoglobal/avkit6---78# AVKit910High-level media playback UI built on AVFoundation. Provides system-standard11video players, Picture-in-Picture, AirPlay routing, transport controls, and12subtitle/caption display. Targets Swift 6.4 / iOS 26+.1314## Contents1516- [Workflow](#workflow)17- [Route by Task](#route-by-task)18- [Core Decisions](#core-decisions)19- [Common Mistakes](#common-mistakes)20- [Review Checklist](#review-checklist)21- [References](#references)2223## Workflow24251. Define playback ownership, media source, audio-session policy, background behavior, and supported system controls.262. Choose `AVPlayerViewController` for full system playback UI or SwiftUI `VideoPlayer` for simpler embedding.273. Keep `AVPlayer` in stable state outside transient view initialization and observe readiness/errors deliberately.284. Configure Picture in Picture, AirPlay, Now Playing, subtitles, and seeking only when the product needs them.295. Verify interruptions, route changes, foreground/background transitions, PiP restoration, captions, and teardown.3031## Route by Task3233- Read [core implementation details](references/core-implementation.md) for audio session, player controllers, `VideoPlayer`, PiP, AirPlay, controls, and subtitles.34- Read [extended AVKit patterns](references/avkit-patterns.md) for custom player UI, interstitials, background playback, error handling, and advanced hosting.3536## Core Decisions3738- Prefer system playback UI and delegation over subclassing `AVPlayerViewController`.39- Configure the audio session for the intended playback/background contract.40- Complete every PiP restoration callback and retain objects required by PiP.41- Keep player identity and observation lifetime stable across SwiftUI body updates.4243## Common Mistakes4445### DON'T: Subclass AVPlayerViewController4647Apple explicitly states this is unsupported. It may cause undefined behavior or48crash on future OS versions.4950```swift51// WRONG52class MyPlayerVC: AVPlayerViewController { } // Unsupported5354// CORRECT: Use composition with delegation55let playerVC = AVPlayerViewController()56playerVC.delegate = coordinator57```5859### DON'T: Skip audio session configuration for PiP6061PiP and background playback depend on the playback audio session category and62the Audio, AirPlay, and Picture in Picture background mode.6364```swift65// WRONG: Default audio session66let playerVC = AVPlayerViewController()67playerVC.player = player // PiP won't work6869// CORRECT: Configure the category, then activate when playback starts70try AVAudioSession.sharedInstance().setCategory(.playback, mode: .moviePlayback)71try AVAudioSession.sharedInstance().setActive(true)72let playerVC = AVPlayerViewController()73playerVC.player = player74```7576### DON'T: Forget the PiP restore delegate or its completion handler7778Without `restoreUserInterfaceForPictureInPictureStopWithCompletionHandler`, the79system cannot return the user to your player. Failing to call80`completionHandler(true)` leaves the system in an inconsistent state.8182```swift83// WRONG: No delegate method or missing completionHandler call84// User taps restore in PiP -> nothing happens or animation hangs8586// CORRECT87func playerViewController(88 _ playerViewController: AVPlayerViewController,89 restoreUserInterfaceForPictureInPictureStopWithCompletionHandler completionHandler: @escaping (Bool) -> Void90) {91 present(playerViewController, animated: false) {92 completionHandler(true)93 }94}95```9697### DON'T: Create AVPlayer in a SwiftUI view's init9899Creating the player eagerly causes performance issues. SwiftUI may recreate the100view multiple times.101102```swift103// WRONG: Created on every view init104struct PlayerView: View {105 let player = AVPlayer(url: videoURL) // Re-created on every view evaluation106107 var body: some View { VideoPlayer(player: player) }108}109110// CORRECT: Use @State and defer creation111struct PlayerView: View {112 @State private var player: AVPlayer?113114 var body: some View {115 VideoPlayer(player: player)116 .task { player = AVPlayer(url: videoURL) }117 }118}119```120121## Review Checklist122123- [ ] Audio session category set to `.playback` with `mode: .moviePlayback`124- [ ] Audio session activation deferred until playback begins125- [ ] Audio, AirPlay, and Picture in Picture background mode added to `UIBackgroundModes`126- [ ] `AVPlayerViewController` is not subclassed127- [ ] PiP tested with supported video media, not only app/device setup128- [ ] PiP restore delegate method implemented and calls `completionHandler(true)`129- [ ] Custom PiP checks both device support and current `isPictureInPicturePossible`130- [ ] Custom PiP starts only from explicit user interaction131- [ ] `AVPlayer` deferred to `.task` in SwiftUI (not created eagerly)132- [ ] `canStartPictureInPictureAutomaticallyFromInline` set for inline players133- [ ] `requiresLinearPlayback` toggled only during required ad/legal segments134- [ ] tvOS-only skipping APIs are not used for iOS transport controls135- [ ] External playback is not disabled accidentally when AirPlay is required136- [ ] Subtitle selection tested with actual media tracks137- [ ] Video gravity set appropriately (`.resizeAspect` vs `.resizeAspectFill`)138- [ ] `isReadyForDisplay` observed before showing the player view139- [ ] Error handling for network-streamed content (HLS failures, timeouts)140141## References142143- Advanced patterns (custom player UI, interstitials, background playback, error handling): [references/avkit-patterns.md](references/avkit-patterns.md)144- [AVKit framework](https://sosumi.ai/documentation/avkit)145- [AVPlayerViewController](https://sosumi.ai/documentation/avkit/avplayerviewcontroller)146- [VideoPlayer (SwiftUI)](https://sosumi.ai/documentation/avkit/videoplayer)147- [AVPictureInPictureController](https://sosumi.ai/documentation/avkit/avpictureinpicturecontroller)148- [AVRoutePickerView](https://sosumi.ai/documentation/avkit/avroutepickerview)149- [AVPlaybackSpeed](https://sosumi.ai/documentation/avkit/avplaybackspeed)150- [Configuring your app for media playback](https://sosumi.ai/documentation/avfoundation/configuring-your-app-for-media-playback)151- [Adopting Picture in Picture in a Standard Player](https://sosumi.ai/documentation/avkit/adopting-picture-in-picture-in-a-standard-player)152- [Playing video content in a standard user interface](https://sosumi.ai/documentation/avkit/playing-video-content-in-a-standard-user-interface)153- [Core implementation details](references/core-implementation.md) -- setup, API wiring, and focused implementation recipes moved out of the entrypoint.