@mmerterden/multi-agent-pipeline 20.7.0 → 20.8.0

package/pipeline/skills/shared/external/avkit/SKILL.md

@@ -1,499 +1,402 @@
 ---
 name: avkit
-description: "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."
+description: "AVKit playback UI: AVPlayerViewController, SwiftUI VideoPlayer, Picture-in-Picture, AirPlay routing, transport controls, subtitles and closed captions, audio session and background mode, AVFoundation playback in system UI. Use when building a video player or adding PiP, AirPlay, transport controls or captions."
 metadata:
-  source: "dpearson2699/swift-ios-skills (PolyForm Perimeter 1.0.0)"
+  source: multi-agent-pipeline
 ---
 
 # 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.3 / iOS 26+.
+AVKit is the playback UI layer over AVFoundation. It supplies the standard
+player, Picture-in-Picture (PiP), AirPlay, transport controls and subtitle and
+caption display. Code here is written for iOS 26 with Swift 6.3.
 
-## Contents
-
-- [Setup](#setup)
-- [AVPlayerViewController](#avplayerviewcontroller)
-- [SwiftUI VideoPlayer](#swiftui-videoplayer)
-- [Picture-in-Picture](#picture-in-picture)
-- [AirPlay](#airplay)
-- [Transport Controls and Playback Speed](#transport-controls-and-playback-speed)
-- [Subtitles and Closed Captions](#subtitles-and-closed-captions)
-- [Common Mistakes](#common-mistakes)
-- [Review Checklist](#review-checklist)
-- [References](#references)
+Covers: PiP for standard and custom players, AirPlay routing with
+`AVRoutePickerView`, playback speeds and interstitial ads.
 
 ## Setup
 
-### Audio Session Configuration
+### Audio session and background mode
 
-Playback apps need an audio session category and the matching background mode
-when they support background audio, AirPlay, or PiP.
+Background audio, AirPlay and PiP all depend on two things: an audio session
+in the playback category, and the background mode that goes with it.
 
-1. Enable Background Modes > Audio, AirPlay, and Picture in Picture (the
-   `audio` value in `UIBackgroundModes`)
-2. Set the audio session category to `.playback`
-3. Defer `setActive(true)` until playback begins so you do not interrupt other
-   audio prematurely
+1. In Signing & Capabilities, add Background Modes and tick "Audio, AirPlay,
+   and Picture in Picture". That adds `audio` to `UIBackgroundModes`.
+2. Set the category to `.playback`, with mode `.moviePlayback` for film and
+   video content.
+3. Activate the session only when playback actually starts, so the app does not
+   silence other audio before the user presses play.
 
 ```swift
 import AVFoundation
 
-func configureAudioSessionForPlayback() {
-    let session = AVAudioSession.sharedInstance()
-    do {
-        try session.setCategory(.playback, mode: .moviePlayback)
-    } catch {
-        print("Audio session category failed: \(error)")
+enum PlaybackAudio {
+    static func configure() {
+        do {
+            let session = AVAudioSession.sharedInstance()
+            try session.setCategory(.playback, mode: .moviePlayback)
+        } catch {
+            assertionFailure("Audio session category failed: \(error)")
+        }
     }
-}
 
-func activateAudioSessionWhenPlaybackBegins() {
-    do {
+    static func activateForPlayback() throws {
         try AVAudioSession.sharedInstance().setActive(true)
-    } catch {
-        print("Audio session activation failed: \(error)")
     }
 }
 ```
 
 ### Imports
 
-```swift
-import AVKit          // AVPlayerViewController, VideoPlayer, PiP
-import AVFoundation   // AVPlayer, AVPlayerItem, AVAsset
-```
+- `import AVKit` for `AVPlayerViewController`, `VideoPlayer` and PiP.
+- `import AVFoundation` for `AVPlayer`, `AVPlayerItem` and `AVAsset`.
 
 ## AVPlayerViewController
 
-`AVPlayerViewController` is the standard UIKit player. It provides system
-playback controls, PiP, AirPlay, subtitles, and frame analysis out of the box.
-Do not subclass it.
-
-### Basic Presentation (Full Screen)
+The standard UIKit player. It brings the system controls, PiP, AirPlay,
+subtitles and video frame analysis. Apple does not support subclassing it;
+configure it and use its delegate instead.
 
 ```swift
+import AVFoundation
 import AVKit
+import UIKit
+
+final class LessonViewController: UIViewController {
+    private let playerScreen = AVPlayerViewController()
 
-func presentPlayer(from viewController: UIViewController, url: URL) {
-    let player = AVPlayer(url: url)
-    let playerVC = AVPlayerViewController()
-    playerVC.player = player
+    func presentFullScreen(_ url: URL) {
+        let viewer = AVPlayerViewController()
+        viewer.player = AVPlayer(url: url)
+        present(viewer, animated: true) {
+            viewer.player?.play()
+        }
+    }
 
-    viewController.present(playerVC, animated: true) {
-        player.play()
+    func embed(_ url: URL, in holder: UIView) {
+        playerScreen.player = AVPlayer(url: url)
+        addChild(playerScreen)
+        holder.addSubview(playerScreen.view)
+        playerScreen.view.translatesAutoresizingMaskIntoConstraints = false
+        NSLayoutConstraint.activate([
+            playerScreen.view.topAnchor.constraint(equalTo: holder.topAnchor),
+            playerScreen.view.bottomAnchor.constraint(equalTo: holder.bottomAnchor),
+            playerScreen.view.leadingAnchor.constraint(equalTo: holder.leadingAnchor),
+            playerScreen.view.trailingAnchor.constraint(equalTo: holder.trailingAnchor)
+        ])
+        playerScreen.didMove(toParent: self)
     }
 }
 ```
 
-### Inline (Embedded) Playback
+### Key properties
 
-Add `AVPlayerViewController` as a child view controller for inline playback.
-Call `addChild`, add the view with constraints, then call `didMove(toParent:)`.
+| Property | Effect |
+|---|---|
+| `showsPlaybackControls` | shows or hides the system controls |
+| `videoGravity` | `.resizeAspect` fits the frame, `.resizeAspectFill` crops to fill |
+| `entersFullScreenWhenPlaybackBegins` | goes full screen when play starts |
+| `exitsFullScreenWhenPlaybackEnds` | leaves full screen at the end |
+| `updatesNowPlayingInfoCenter` | keeps `MPNowPlayingInfoCenter` in sync automatically |
+| `contentOverlayView` | holds non-interactive views (logos, watermarks) between the video and the controls |
 
-```swift
-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)
-}
-```
+### Delegate
 
-### Key Properties
+`AVPlayerViewControllerDelegate` reports full-screen transitions, the PiP
+lifecycle, ad interstitials and changes to the selected media options. To move your own
+UI in step with the full-screen animation, use the transition coordinator:
 
 ```swift
-playerVC.showsPlaybackControls = true                    // Show/hide system controls
-playerVC.videoGravity = .resizeAspect                    // .resizeAspectFill to crop
-playerVC.entersFullScreenWhenPlaybackBegins = false
-playerVC.exitsFullScreenWhenPlaybackEnds = true
-playerVC.updatesNowPlayingInfoCenter = true              // Auto-updates MPNowPlayingInfoCenter
-```
-
-Use `contentOverlayView` to add non-interactive views (watermarks, logos)
-between the video and transport controls.
+import AVKit
+import UIKit
 
-### Delegate
+@MainActor
+final class FullScreenSync: NSObject, @preconcurrency AVPlayerViewControllerDelegate {
+    var chrome: UIView?
 
-Adopt `AVPlayerViewControllerDelegate` to respond to full-screen transitions,
-PiP lifecycle events, interstitial playback, and media selection changes.
-Use the transition coordinator's `animate(alongsideTransition:completion:)` to
-synchronize your UI with full-screen animations.
+    func playerViewController(_ playerViewController: AVPlayerViewController,
+                              willBeginFullScreenPresentationWithAnimationCoordinator coordinator: any UIViewControllerTransitionCoordinator) {
+        coordinator.animate(alongsideTransition: { _ in self.chrome?.alpha = 0 }, completion: nil)
+    }
+}
+```
 
-### Display Readiness
+### Showing the player only when it has a frame
 
-Observe `isReadyForDisplay` before showing the player to avoid a black flash:
+Observe `isReadyForDisplay` and reveal the player when it turns `true`; this
+avoids a black flash.
 
 ```swift
-let observation = playerVC.observe(\.isReadyForDisplay) { observed, _ in
-    if observed.isReadyForDisplay {
-        // Safe to show the player view
+import AVKit
+
+@MainActor
+func revealWhenReady(_ viewer: AVPlayerViewController) -> NSKeyValueObservation {
+    viewer.view.alpha = 0
+    return viewer.observe(\.isReadyForDisplay, options: [.new]) { observed, _ in
+        MainActor.assumeIsolated {
+            if observed.isReadyForDisplay { observed.view.alpha = 1 }
+        }
     }
 }
 ```
 
 ## SwiftUI VideoPlayer
 
-The `VideoPlayer` SwiftUI view wraps AVKit's playback UI.
-
-### Basic Usage
+`VideoPlayer` is the SwiftUI view for AVKit's playback UI.
 
 ```swift
-import SwiftUI
 import AVKit
+import SwiftUI
 
-struct PlayerView: View {
+struct TrailerView: View {
+    let source: URL
     @State private var player: AVPlayer?
 
     var body: some View {
         Group {
             if let player {
-                VideoPlayer(player: player)
-                    .frame(height: 300)
+                VideoPlayer(player: player) {
+                    VStack {
+                        Spacer()
+                        Text("Preview")
+                            .font(.caption)
+                            .padding(6)
+                            .background(.ultraThinMaterial, in: Capsule())
+                    }
+                }
+                .frame(height: 240)
             } else {
                 ProgressView()
             }
         }
         .task {
-            let url = URL(string: "https://example.com/video.m3u8")!
-            player = AVPlayer(url: url)
-        }
-    }
-}
-```
-
-### Video Overlay
-
-Add a SwiftUI overlay above the video content and below the system playback
-controls. The overlay can be interactive, but it only receives events the system
-controls do not handle.
-
-```swift
-VideoPlayer(player: player) {
-    VStack {
-        Spacer()
-        HStack {
-            Image("logo")
-                .resizable()
-                .frame(width: 40, height: 40)
-                .padding()
-            Spacer()
+            player = AVPlayer(url: source)
         }
     }
 }
 ```
 
-### UIKit Hosting for Advanced Control
-
-`VideoPlayer` does not expose all `AVPlayerViewController` properties. For PiP
-configuration, delegate callbacks, or playback speed control, wrap
-`AVPlayerViewController` in a `UIViewControllerRepresentable`. See the full
-pattern in [references/avkit-patterns.md](references/avkit-patterns.md).
+- The trailing closure is a video overlay. It sits above the picture and below
+  the system controls. It may contain interactive views, but those only receive
+  events that the system controls did not handle.
+- `VideoPlayer` exposes only part of what `AVPlayerViewController` offers. For
+  PiP settings, delegate callbacks or playback speeds, wrap
+  `AVPlayerViewController` in a `UIViewControllerRepresentable` (see
+  [the patterns reference](references/avkit-patterns.md#wrapping-avplayerviewcontroller-for-swiftui)).
 
 ## Picture-in-Picture
 
-PiP lets users watch video in a floating window while using other apps.
-`AVPlayerViewController` supports PiP automatically once the app is configured,
-the device supports PiP, and the current `AVPlayerItem` is playable video
-content in an `AVPlayer`-compatible format. Audio-only items, unsupported
-containers/codecs, or items that are not ready to display video can make PiP
-unavailable even when app and device setup are correct. For custom player UIs,
-use `AVPictureInPictureController` directly.
+`AVPlayerViewController` provides PiP by itself once three conditions hold:
+setup is done, the hardware can do PiP, and the `AVPlayerItem` now loaded holds
+playable video in a format AVPlayer handles. Audio-only items, unsupported
+containers or codecs, and items not yet ready to display can all leave PiP
+unavailable even when setup is correct. Custom player UIs drive
+`AVPictureInPictureController` themselves.
 
 ### Prerequisites
 
-1. Audio session category set to `.playback` (see [Setup](#setup))
-2. Background Modes > Audio, AirPlay, and Picture in Picture enabled
-3. Ready `AVPlayerItem` with playable video media, not audio-only content
-4. Current playback context allows PiP; for custom players, observe `isPictureInPicturePossible`
+1. Audio session category `.playback`.
+2. Background mode `audio` enabled (shown in Xcode as "Audio, AirPlay, and Picture in Picture").
+3. A ready `AVPlayerItem` containing playable video, not only audio.
+4. A playback context that allows PiP; custom players watch
+   `isPictureInPicturePossible`.
 
-### Standard Player PiP
+### Standard player
 
-PiP is enabled by default on `AVPlayerViewController`. Control automatic
-activation and inline-to-PiP transitions:
+PiP is on by default. Turn it off with `allowsPictureInPicturePlayback = false`.
+For an inline (not full-screen) player, set
+`canStartPictureInPictureAutomaticallyFromInline = true` to enter PiP
+automatically when the app goes to the background.
 
-```swift
-let playerVC = AVPlayerViewController()
-playerVC.player = player
-
-// PiP enabled by default; set false to disable
-playerVC.allowsPictureInPicturePlayback = true
+### Restoring the app UI when PiP ends
 
-// Auto-start PiP when app backgrounds (for inline/non-fullscreen players)
-playerVC.canStartPictureInPictureAutomaticallyFromInline = true
-```
+When the user taps the button to return from PiP, the app must put the player
+back on screen and then pass `true` to the completion handler so the system
+can finish its animation.
 
-### Restoring the UI When PiP Stops
+```swift
+import AVKit
+import UIKit
 
-When the user taps the restore button in PiP, implement the delegate method to
-re-present your player. Call the completion handler with `true` to signal the
-system to finish the restore animation.
+@MainActor
+final class PiPReturn: NSObject, @preconcurrency AVPlayerViewControllerDelegate {
+    weak var host: UIViewController?
 
-```swift
-func playerViewController(
-    _ playerViewController: AVPlayerViewController,
-    restoreUserInterfaceForPictureInPictureStopWithCompletionHandler completionHandler: @escaping (Bool) -> Void
-) {
-    // Re-present or re-embed the player view controller
-    present(playerViewController, animated: false) {
-        completionHandler(true)
+    func playerViewController(_ playerViewController: AVPlayerViewController,
+                              restoreUserInterfaceForPictureInPictureStopWithCompletionHandler completionHandler: @escaping (Bool) -> Void) {
+        guard let host, playerViewController.presentingViewController == nil else {
+            completionHandler(true)
+            return
+        }
+        host.present(playerViewController, animated: false) {
+            completionHandler(true)
+        }
     }
 }
 ```
 
-### Custom Player PiP
+### Custom players
 
-For custom player UIs, use `AVPictureInPictureController` with an `AVPlayerLayer`
-or sample buffer content source. Check device support before creating PiP UI,
-then check the controller's `isPictureInPicturePossible` before starting PiP in
-the current playback context. See [references/avkit-patterns.md](references/avkit-patterns.md)
-for full custom player and sample buffer PiP patterns.
+Build an `AVPictureInPictureController` from an `AVPlayerLayer` or from a
+sample-buffer content source.
 
-```swift
-guard AVPictureInPictureController.isPictureInPictureSupported() else { return }
-let pipController = AVPictureInPictureController(playerLayer: playerLayer)
-pipController.delegate = self
-pipController.canStartPictureInPictureAutomaticallyFromInline = true
-
-// Call this from the user's PiP button action, never automatically.
-if pipController.isPictureInPicturePossible {
-    pipController.startPictureInPicture()
-}
-```
+- Check `AVPictureInPictureController.isPictureInPictureSupported()` before
+  showing any PiP control.
+- Check `isPictureInPicturePossible` right before `startPictureInPicture()`.
+- Call `startPictureInPicture()` only from the user's tap on a PiP button,
+  never on your own.
+- The controller also has `canStartPictureInPictureAutomaticallyFromInline` and
+  a `delegate`.
 
-### Linear Playback During Ads
+Full layer-based and sample-buffer examples are in
+[the patterns reference](references/avkit-patterns.md#custom-player-with-avplayerlayer).
 
-Interstitial breaks can come from the media stream/manifest, which AVFoundation
-exposes through `AVPlayerItem.interstitialTimeRanges`, or from an app-owned
-`AVPlayerInterstitialEventController` schedule. Do not assign
-`interstitialTimeRanges` directly on iOS. Use `requiresLinearPlayback` only to
-prevent seeking during required ad or legal segments:
+### Ads and linear playback
 
-```swift
-// During an ad
-playerVC.requiresLinearPlayback = true
+Interstitial breaks come either from the stream itself (HLS interstitials,
+which the item reports through `interstitialTimeRanges`) or from a schedule the app owns,
+built with `AVPlayerInterstitialEventController`. On iOS,
+`interstitialTimeRanges` is read-only; do not try to assign it.
 
-// After the ad completes
-playerVC.requiresLinearPlayback = false
-```
+Set `requiresLinearPlayback = true` only while a required ad or legal segment
+plays, to block seeking, and set it back to `false` afterwards.
 
 ## AirPlay
 
-`AVPlayerViewController` supports AirPlay automatically when app configuration,
-media, routes, and device support allow external playback. No additional code is
-required when using the standard player. The system displays the AirPlay button
-in the transport controls when AirPlay-capable devices are available.
+`AVPlayerViewController` supports AirPlay with no extra code when the setup,
+media, available routes and device allow it. The AirPlay button appears in the
+controls whenever a receiver is available.
 
 ### AVRoutePickerView
 
-Add a standalone AirPlay route picker button outside the player UI:
+For an AirPlay button outside the player, use `AVRoutePickerView`:
 
 ```swift
 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  // Show video-capable routes first
-    containerView.addSubview(routePicker)
+import UIKit
+
+@MainActor
+func castButton() -> AVRoutePickerView {
+    let picker = AVRoutePickerView(frame: CGRect(origin: .zero, size: CGSize(width: 44, height: 44)))
+    picker.activeTintColor = .systemTeal
+    picker.prioritizesVideoDevices = true
+    return picker
 }
 ```
 
-### External Playback
-
-`AVPlayer` allows external playback by default. Leave it enabled for AirPlay,
-or set it explicitly when code elsewhere may disable it:
-
-```swift
-player.allowsExternalPlayback = true
-```
-
-Set `usesExternalPlaybackWhileExternalScreenIsActive` only when you want the
-player to automatically switch to external playback while an external screen
-mode is active.
-
-## Transport Controls and Playback Speed
-
-### Custom Playback Speeds
-
-Provide user-selectable playback speeds in the player UI:
-
-```swift
-let playerVC = AVPlayerViewController()
-playerVC.speeds = [
-    AVPlaybackSpeed(rate: 0.5, localizedName: "Half Speed"),
-    AVPlaybackSpeed(rate: 1.0, localizedName: "Normal"),
-    AVPlaybackSpeed(rate: 1.5, localizedName: "1.5x"),
-    AVPlaybackSpeed(rate: 2.0, localizedName: "Double Speed")
-]
-```
-
-Use `AVPlaybackSpeed.systemDefaultSpeeds` to restore the default speed options.
-
-### Skipping and Seeking
-
-On iOS, use the standard transport controls and `AVPlayer.seek(...)` for custom
-app controls. `AVPlayerViewController` skipping behavior APIs such as
-`isSkipForwardEnabled`, `isSkipBackwardEnabled`, and `skippingBehavior` are
-tvOS-focused; keep them out of iOS player implementations.
-
-### Now Playing Integration
-
-`AVPlayerViewController` updates `MPNowPlayingInfoCenter` automatically by
-default. Disable this if you manage Now Playing info manually:
+`prioritizesVideoDevices = true` lists video-capable receivers first.
 
-```swift
-playerVC.updatesNowPlayingInfoCenter = false
-```
+### External playback
 
-## Subtitles and Closed Captions
+- `AVPlayer.allowsExternalPlayback` is `true` by default. Leave it on for
+  AirPlay, or set it explicitly if other code might have turned it off.
+- `usesExternalPlaybackWhileExternalScreenIsActive` is only for making the
+  player switch to external playback automatically while an external screen is
+  in use. It is not something AirPlay generally needs.
 
-AVKit handles subtitle and closed caption display automatically when the media
-contains appropriate text tracks. Users control subtitle preferences in
-Settings > Accessibility > Subtitles & Captioning.
+## Transport controls and speed
 
-### Programmatic Selection
+### Custom speeds
 
 ```swift
-let asset = player.currentItem?.asset
+import AVKit
 
-if let group = try await asset?.loadMediaSelectionGroup(for: .legible),
-   let english = group.options.first(where: { option in
-       option.locale?.language.languageCode?.identifier == "en"
-   }) {
-    player.currentItem?.select(english, in: group)
+@MainActor
+func offerLectureSpeeds(_ viewer: AVPlayerViewController) {
+    viewer.speeds = [
+        AVPlaybackSpeed(rate: 0.75, localizedName: "0.75x"),
+        AVPlaybackSpeed(rate: 1, localizedName: "1x"),
+        AVPlaybackSpeed(rate: 1.25, localizedName: "1.25x"),
+        AVPlaybackSpeed(rate: 1.75, localizedName: "1.75x")
+    ]
 }
-```
-
-`allowedSubtitleOptionLanguages`, `requiresFullSubtitles`, and the
-`AVPlayerViewControllerDelegate` media-selection callback are tvOS-only. For iOS,
-load the asset's `.legible` media selection group and select an option on the
-`AVPlayerItem` when the app needs a default.
-
-### Providing Subtitle Tracks in HLS
 
-Subtitles and closed captions are embedded in HLS manifests. AVKit reads them
-from `AVMediaSelectionGroup` on the `AVAsset`. For local files, use media that
-already includes legible subtitle or closed-caption tracks, or author those
-tracks into the playable asset before presenting it with AVKit.
-
-## Common Mistakes
-
-### DON'T: Subclass AVPlayerViewController
-
-Apple explicitly states this is unsupported. It may cause undefined behavior or
-crash on future OS versions.
-
-```swift
-// WRONG
-class MyPlayerVC: AVPlayerViewController { } // Unsupported
-
-// CORRECT: Use composition with delegation
-let playerVC = AVPlayerViewController()
-playerVC.delegate = coordinator
+@MainActor
+func restoreDefaultSpeeds(_ viewer: AVPlayerViewController) {
+    viewer.speeds = AVPlaybackSpeed.systemDefaultSpeeds
+}
 ```
 
-### DON'T: Skip audio session configuration for PiP
+### Skipping and seeking
 
-PiP and background playback depend on the playback audio session category and
-the Audio, AirPlay, and Picture in Picture background mode.
+On iOS rely on the standard transport controls, and use `AVPlayer.seek(...)`
+behind any custom buttons. `isSkipForwardEnabled`, `isSkipBackwardEnabled` and
+`skippingBehavior` are tvOS APIs; keep them out of iOS code.
 
-```swift
-// 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
-```
+### Now Playing
 
-### DON'T: Forget the PiP restore delegate or its completion handler
+`AVPlayerViewController` updates `MPNowPlayingInfoCenter` by default. Set
+`updatesNowPlayingInfoCenter = false` if the app manages Now Playing itself.
 
-Without `restoreUserInterfaceForPictureInPictureStopWithCompletionHandler`, the
-system cannot return the user to your player. Failing to call
-`completionHandler(true)` leaves the system in an inconsistent state.
+## Subtitles and closed captions
 
-```swift
-// 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.
+When the media has text tracks, AVKit shows subtitles and captions
+automatically according to the user's choices in Settings > Accessibility >
+Subtitles & Captioning.
 
 ```swift
-// 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?
+import AVFoundation
 
-    var body: some View {
-        VideoPlayer(player: player)
-            .task { player = AVPlayer(url: videoURL) }
-    }
+@MainActor
+func chooseSubtitles(language code: String, for item: AVPlayerItem) async throws {
+    let media = item.asset
+    guard let legible = try await media.loadMediaSelectionGroup(for: .legible) else { return }
+    let match = legible.options.first { $0.locale?.language.languageCode?.identifier == code }
+    item.select(match, in: legible)
 }
 ```
 
-## Review Checklist
-
-- [ ] Audio session category set to `.playback` with `mode: .moviePlayback`
-- [ ] Audio session activation deferred until playback begins
-- [ ] Audio, AirPlay, and Picture in Picture background mode added to `UIBackgroundModes`
+- `allowedSubtitleOptionLanguages`, `requiresFullSubtitles` and the delegate
+  callback for media selection exist only on tvOS. On iOS, select within the item's
+  `.legible` group as above.
+- HLS carries subtitles and captions in its manifests, and AVKit reads them
+  from the `AVAsset`'s `AVMediaSelectionGroup`.
+- Local files need the legible tracks already inside the file, or authored
+  into the asset.
+
+## Common mistakes
+
+- **Subclassing `AVPlayerViewController`.** Apple does not support it and it
+  can break on a future OS. Compose it and use the delegate.
+- **Leaving the default audio session.** PiP will not work. Set
+  `.playback` with `.moviePlayback`, and activate when playback begins.
+- **No PiP restore handler, or no `completionHandler(true)`.** Without the
+  handler the user cannot get back to the player; without the completion call
+  the restore does nothing or the animation hangs.
+- **`AVPlayer` as a stored property of a SwiftUI view.** It is recreated every
+  time the view value is rebuilt. Hold an optional in `@State` and create it in
+  `.task`.
+
+## Review checklist
+
+- [ ] Audio session is `.playback` with `.moviePlayback`
+- [ ] The session is activated only when playback starts
+- [ ] `UIBackgroundModes` contains `audio`
 - [ ] `AVPlayerViewController` is not subclassed
-- [ ] PiP tested with supported video media, not only app/device setup
-- [ ] PiP restore delegate method implemented and calls `completionHandler(true)`
-- [ ] Custom PiP checks both device support and current `isPictureInPicturePossible`
-- [ ] Custom PiP starts only from explicit user interaction
-- [ ] `AVPlayer` deferred to `.task` in SwiftUI (not created eagerly)
-- [ ] `canStartPictureInPictureAutomaticallyFromInline` set for inline players
-- [ ] `requiresLinearPlayback` toggled only during required ad/legal segments
-- [ ] tvOS-only skipping APIs are not used for iOS transport controls
-- [ ] External playback is not disabled accidentally when AirPlay is required
-- [ ] Subtitle selection tested with actual media tracks
-- [ ] Video gravity set appropriately (`.resizeAspect` vs `.resizeAspectFill`)
-- [ ] `isReadyForDisplay` observed before showing the player view
-- [ ] Error handling for network-streamed content (HLS failures, timeouts)
+- [ ] PiP was tried with real, supported video media
+- [ ] The PiP restore delegate method exists and calls `completionHandler(true)`
+- [ ] Custom PiP checks device support and `isPictureInPicturePossible`
+- [ ] Custom PiP starts only from an explicit user action
+- [ ] SwiftUI creates the `AVPlayer` in `.task`
+- [ ] Inline players set `canStartPictureInPictureAutomaticallyFromInline`
+- [ ] `requiresLinearPlayback` is `true` only while a mandatory ad or legal notice plays
+- [ ] tvOS-only skipping APIs are absent from iOS code
+- [ ] External playback is not switched off where AirPlay is expected
+- [ ] Subtitle selection was tested with media that has real text tracks
+- [ ] `videoGravity` suits the content
+- [ ] `isReadyForDisplay` gates when the player appears
+- [ ] Streaming errors (HLS failures, timeouts) are handled
 
 ## References
 
-- Advanced patterns (custom player UI, interstitials, background playback, error handling): [references/avkit-patterns.md](references/avkit-patterns.md)
-- [AVKit framework](https://sosumi.ai/documentation/avkit)
-- [AVPlayerViewController](https://sosumi.ai/documentation/avkit/avplayerviewcontroller)
-- [VideoPlayer (SwiftUI)](https://sosumi.ai/documentation/avkit/videoplayer)
-- [AVPictureInPictureController](https://sosumi.ai/documentation/avkit/avpictureinpicturecontroller)
-- [AVRoutePickerView](https://sosumi.ai/documentation/avkit/avroutepickerview)
-- [AVPlaybackSpeed](https://sosumi.ai/documentation/avkit/avplaybackspeed)
-- [Configuring your app for media playback](https://sosumi.ai/documentation/avfoundation/configuring-your-app-for-media-playback)
-- [Adopting Picture in Picture in a Standard Player](https://sosumi.ai/documentation/avkit/adopting-picture-in-picture-in-a-standard-player)
-- [Playing video content in a standard user interface](https://sosumi.ai/documentation/avkit/playing-video-content-in-a-standard-user-interface)
+- [AVKit patterns](references/avkit-patterns.md) - custom AVPlayerLayer player with PiP, sample-buffer PiP, interstitials, background playback, errors, playback observation, frame analysis, HDR, SwiftUI player model, representable wrapper
+- [AVKit](https://developer.apple.com/documentation/avkit)
+- [AVPlayerViewController](https://developer.apple.com/documentation/avkit/avplayerviewcontroller)
+- [VideoPlayer](https://developer.apple.com/documentation/avkit/videoplayer)
+- [AVPictureInPictureController](https://developer.apple.com/documentation/avkit/avpictureinpicturecontroller)
+- [AVRoutePickerView](https://developer.apple.com/documentation/avkit/avroutepickerview)
+- [AVPlaybackSpeed](https://developer.apple.com/documentation/avkit/avplaybackspeed)
+- [Apple guide: media playback configuration](https://developer.apple.com/documentation/avfoundation/configuring-your-app-for-media-playback)
+- [Apple guide: PiP in the standard player](https://developer.apple.com/documentation/avkit/adopting-picture-in-picture-in-a-standard-player)
+- [Apple guide: video in the standard interface](https://developer.apple.com/documentation/avkit/playing-video-content-in-a-standard-user-interface)