@mmerterden/multi-agent-pipeline 20.7.0 → 20.8.0

package/pipeline/skills/shared/external/avkit/references/avkit-patterns.md

@@ -1,668 +1,550 @@
-# AVKit Patterns
+# AVKit patterns
 
-Advanced patterns for AVKit media playback beyond the main skill coverage.
+Advanced playback recipes for iOS 26 and Swift 6.3.
 
 ## Contents
 
-- [Custom Player UI with AVPlayerLayer](#custom-player-ui-with-avplayerlayer)
-- [Interstitial Content](#interstitial-content)
-- [Background Playback](#background-playback)
-- [Error Handling](#error-handling)
-- [Observing Playback State](#observing-playback-state)
-- [Video Frame Analysis](#video-frame-analysis)
-- [HDR Content](#hdr-content)
-- [SwiftUI Player Manager](#swiftui-player-manager)
-- [AVPlayerViewController in UIViewControllerRepresentable](#avplayerviewcontroller-in-uiviewcontrollerrepresentable)
+- [Custom player with AVPlayerLayer](#custom-player-with-avplayerlayer)
+- [Interstitials](#interstitials)
+- [Background playback](#background-playback)
+- [Errors](#errors)
+- [Observing playback](#observing-playback)
+- [Video frame analysis](#video-frame-analysis)
+- [HDR](#hdr)
+- [SwiftUI player model](#swiftui-player-model)
+- [Wrapping AVPlayerViewController for SwiftUI](#wrapping-avplayerviewcontroller-for-swiftui)
 
-## Custom Player UI with AVPlayerLayer
+## Custom player with AVPlayerLayer
 
-When `AVPlayerViewController` does not meet your design requirements, build a
-custom player UI using `AVPlayerLayer` directly. You lose system transport
-controls but gain full control over the interface.
+Drawing video through `AVPlayerLayer` means giving up the system transport
+controls in exchange for complete control over the UI.
 
 ```swift
 import AVFoundation
 import UIKit
 
-final class CustomPlayerView: UIView {
-    override class var layerClass: AnyClass { AVPlayerLayer.self }
+@MainActor
+final class FilmSurface: UIView {
+    override static var layerClass: AnyClass { AVPlayerLayer.self }
 
-    var playerLayer: AVPlayerLayer { layer as! AVPlayerLayer }
+    var filmLayer: AVPlayerLayer {
+        layer as! AVPlayerLayer
+    }
 
     var player: AVPlayer? {
-        get { playerLayer.player }
-        set { playerLayer.player = newValue }
+        get { filmLayer.player }
+        set { filmLayer.player = newValue }
     }
 
-    override init(frame: CGRect) {
-        super.init(frame: frame)
-        playerLayer.videoGravity = .resizeAspect
+    override init(frame rect: CGRect) {
+        super.init(frame: rect)
+        filmLayer.videoGravity = .resizeAspect
     }
 
-    required init?(coder: NSCoder) {
-        super.init(coder: coder)
-        playerLayer.videoGravity = .resizeAspect
+    required init?(coder decoder: NSCoder) {
+        super.init(coder: decoder)
+        filmLayer.videoGravity = .resizeAspect
     }
 }
 ```
 
-### Adding PiP to a Custom Player
+The force cast is safe because `layerClass` guarantees the layer type.
 
-Use `AVPictureInPictureController` with the custom player layer:
+### Adding PiP to it
 
 ```swift
+import AVFoundation
 import AVKit
+import UIKit
 
-final class CustomPlayerController: UIViewController, AVPictureInPictureControllerDelegate {
-    private let playerView = CustomPlayerView()
-    private var pipController: AVPictureInPictureController?
+@MainActor
+final class CustomCinemaController: UIViewController, @preconcurrency AVPictureInPictureControllerDelegate {
+    private let surface = FilmSurface()
     private let player = AVPlayer()
+    private var pip: AVPictureInPictureController?
+    private let overlayControls = UIStackView()
 
-    override func viewDidLoad() {
-        super.viewDidLoad()
-        view.addSubview(playerView)
-        playerView.player = player
+    override func loadView() {
+        view = surface
+    }
 
+    func load(_ url: URL) {
+        surface.player = player
         if AVPictureInPictureController.isPictureInPictureSupported() {
-            pipController = AVPictureInPictureController(playerLayer: playerView.playerLayer)
-            pipController?.delegate = self
-            pipController?.canStartPictureInPictureAutomaticallyFromInline = true
+            let controller = AVPictureInPictureController(playerLayer: surface.filmLayer)
+            controller?.delegate = self
+            controller?.canStartPictureInPictureAutomaticallyFromInline = true
+            pip = controller
         }
-    }
-
-    func play(url: URL) {
-        player.replaceCurrentItem(with: AVPlayerItem(url: url))
+        let episode = AVPlayerItem(url: url)
+        player.replaceCurrentItem(with: episode)
         player.play()
     }
 
-    @IBAction func userTappedPictureInPictureButton(_ sender: UIButton) {
-        guard pipController?.isPictureInPicturePossible == true else { return }
-        pipController?.startPictureInPicture()
+    @objc func pipButtonTapped() {
+        guard let pip, pip.isPictureInPicturePossible else { return }
+        pip.startPictureInPicture()
     }
 
-    // MARK: - AVPictureInPictureControllerDelegate
-
-    func pictureInPictureControllerWillStartPictureInPicture(
-        _ pictureInPictureController: AVPictureInPictureController
-    ) {
-        // Prepare UI for PiP (e.g., hide custom controls)
+    func pictureInPictureControllerWillStartPictureInPicture(_ controller: AVPictureInPictureController) {
+        overlayControls.isHidden = true
     }
 
-    func pictureInPictureControllerDidStopPictureInPicture(
-        _ pictureInPictureController: AVPictureInPictureController
-    ) {
-        // Restore custom controls
+    func pictureInPictureControllerDidStopPictureInPicture(_ controller: AVPictureInPictureController) {
+        overlayControls.isHidden = false
     }
 
-    func pictureInPictureController(
-        _ pictureInPictureController: AVPictureInPictureController,
-        restoreUserInterfaceForPictureInPictureStopWithCompletionHandler completionHandler: @escaping (Bool) -> Void
-    ) {
-        // Re-present the player view controller
-        completionHandler(true)
+    func pictureInPictureController(_ controller: AVPictureInPictureController,
+                                    restoreUserInterfaceForPictureInPictureStopWithCompletionHandler finish: @escaping (Bool) -> Void) {
+        finish(true)
     }
 }
 ```
 
-### PiP with Sample Buffers
+- Create the PiP controller only when the device supports PiP.
+- Set its delegate and the automatic-inline flag, then load the item and play.
+- The button action re-checks `isPictureInPicturePossible` before starting.
+- Hide custom controls when PiP starts, show them again when it stops, and
+  always call `completionHandler(true)` in the restore callback.
 
-For apps rendering video frames manually (e.g., from a custom pipeline), use
-the sample buffer content source:
+### PiP from sample buffers
+
+When the app renders frames itself into an `AVSampleBufferDisplayLayer`, build
+the controller from a content source:
 
 ```swift
+import AVFoundation
 import AVKit
+import CoreMedia
 
-func setupSampleBufferPiP(
-    displayLayer: AVSampleBufferDisplayLayer,
-    delegate: AVPictureInPictureSampleBufferPlaybackDelegate
-) -> AVPictureInPictureController? {
-    guard AVPictureInPictureController.isPictureInPictureSupported() else { return nil }
-
-    let contentSource = AVPictureInPictureController.ContentSource(
-        sampleBufferDisplayLayer: displayLayer,
-        playbackDelegate: delegate
-    )
-    let controller = AVPictureInPictureController(contentSource: contentSource)
-    return controller
-}
-```
-
-Only show a custom PiP start affordance after device support is known. When the
-user taps that affordance, check the controller's `isPictureInPicturePossible`
-because support can still be false for the current layer, item, media format,
-or playback state. Start custom PiP only in response to user interaction.
-
-The playback delegate must report timing and play/pause state:
+@MainActor
+final class RemoteDesktopPiP: NSObject, @preconcurrency AVPictureInPictureSampleBufferPlaybackDelegate {
+    let frameLayer = AVSampleBufferDisplayLayer()
+    private(set) var pip: AVPictureInPictureController?
+    private var paused = false
 
-```swift
-final class SampleBufferPlaybackHandler: NSObject, AVPictureInPictureSampleBufferPlaybackDelegate {
-    var isPlaying = true
-    var currentTime: CMTime = .zero
-    var duration: CMTime = CMTime(seconds: 300, preferredTimescale: 600)
+    func prepare() {
+        if !AVPictureInPictureController.isPictureInPictureSupported() { return }
+        let source = AVPictureInPictureController.ContentSource(sampleBufferDisplayLayer: frameLayer, playbackDelegate: self)
+        pip = AVPictureInPictureController(contentSource: source)
+    }
 
-    func pictureInPictureController(
-        _ pictureInPictureController: AVPictureInPictureController,
-        setPlaying playing: Bool
-    ) {
-        isPlaying = playing
+    func userTappedPiP() {
+        guard let pip, pip.isPictureInPicturePossible else { return }
+        pip.startPictureInPicture()
     }
 
-    func pictureInPictureControllerTimeRangeForPlayback(
-        _ pictureInPictureController: AVPictureInPictureController
-    ) -> CMTimeRange {
-        CMTimeRange(start: .zero, duration: duration)
+    func pictureInPictureController(_ controller: AVPictureInPictureController, setPlaying playing: Bool) {
+        paused = !playing
     }
 
-    func pictureInPictureControllerIsPlaybackPaused(
-        _ pictureInPictureController: AVPictureInPictureController
-    ) -> Bool {
-        !isPlaying
+    func pictureInPictureControllerTimeRangeForPlayback(_ controller: AVPictureInPictureController) -> CMTimeRange {
+        CMTimeRange(start: .negativeInfinity, duration: .positiveInfinity)
     }
 
-    func pictureInPictureController(
-        _ pictureInPictureController: AVPictureInPictureController,
-        didTransitionToRenderSize newRenderSize: CMVideoDimensions
-    ) {
-        // Adjust rendering resolution for PiP window size
+    func pictureInPictureControllerIsPlaybackPaused(_ controller: AVPictureInPictureController) -> Bool {
+        paused
     }
 
-    func pictureInPictureController(
-        _ pictureInPictureController: AVPictureInPictureController,
-        skipByInterval skipInterval: CMTime,
-        completion: @escaping () -> Void
-    ) {
-        currentTime = CMTimeAdd(currentTime, skipInterval)
-        completion()
+    func pictureInPictureController(_ controller: AVPictureInPictureController,
+                                    didTransitionToRenderSize newRenderSize: CMVideoDimensions) {}
+
+    func pictureInPictureController(_ controller: AVPictureInPictureController,
+                                    skipByInterval skipInterval: CMTime,
+                                    completion completionHandler: @escaping () -> Void) {
+        completionHandler()
     }
 
-    func pictureInPictureControllerShouldProhibitBackgroundAudioPlayback(
-        _ pictureInPictureController: AVPictureInPictureController
-    ) -> Bool {
+    func pictureInPictureControllerShouldProhibitBackgroundAudioPlayback(_ controller: AVPictureInPictureController) -> Bool {
         false
     }
 }
 ```
 
-## Interstitial Content
+- Offer a PiP button only once support is confirmed.
+- On tap, check `isPictureInPicturePossible` again; the layer, item, format or
+  playback state can still rule PiP out. Start only from the user's tap.
+- The playback delegate must answer the system's questions about timing and
+  play state: `setPlaying`, the playable time range (an infinite range here, for
+  live content), whether playback is paused, render-size changes, skip requests
+  (call the completion), and whether background audio should be blocked.
 
-Use interstitials for ads, legal notices, and other timeline ranges with
-special playback rules. `AVPlayerViewController` can mark these ranges in the
-timeline and call delegate methods when interstitial playback begins and ends.
+## Interstitials
 
-### Stream-Defined Interstitial Ranges
+Interstitials cover ads, legal notices and any stretch of the timeline with
+special rules. `AVPlayerViewController` marks them on the scrubber and tells its
+delegate when one starts and ends.
 
 ```swift
+import AVFoundation
 import AVKit
 
-func inspectInterstitials(for playerItem: AVPlayerItem) {
-    for interstitial in playerItem.interstitialTimeRanges {
-        let range = interstitial.timeRange
-        print("Interstitial starts at \(range.start.seconds)s")
-    }
+@MainActor
+func adBreaks(in item: AVPlayerItem) -> [CMTimeRange] {
+    item.interstitialTimeRanges.map(\.timeRange)
 }
-```
-
-On iOS, valid scheduling sources are either stream-defined interstitials or
-app-created schedules through `AVPlayerInterstitialEventController`. For
-stream-defined breaks, the manifest or source media owns the schedule, and
-AVFoundation exposes it through `playerItem.interstitialTimeRanges` for
-inspection and delegate coordination. Do not assign to
-`playerItem.interstitialTimeRanges` directly as the scheduling recipe.
-
-### App-Scheduled Interstitials
-
-For app-scheduled interstitial content, use `AVPlayerInterstitialEventController`
-from AVFoundation. Creating a controller schedule causes playback to ignore
-interstitial events present in the source media, so use it only when the app
-owns the schedule.
-
-```swift
-import AVFoundation
-
-func setupInterstitialEvents(primaryPlayer: AVPlayer) {
-    guard let primaryItem = primaryPlayer.currentItem else { return }
-
-    let controller = AVPlayerInterstitialEventController(primaryPlayer: primaryPlayer)
-
-    let adAsset = AVURLAsset(url: URL(string: "https://example.com/ad.m3u8")!)
-    let adItem = AVPlayerItem(asset: adAsset)
 
-    let event = AVPlayerInterstitialEvent(
-        primaryItem: primaryItem,
-        time: CMTime(seconds: 60, preferredTimescale: 600)
+@MainActor
+func scheduleMidroll(on player: AVPlayer, adURL: URL, at seconds: Double) -> AVPlayerInterstitialEventController? {
+    guard let main = player.currentItem else { return nil }
+    let controller = AVPlayerInterstitialEventController(primaryPlayer: player)
+    let midroll = AVPlayerInterstitialEvent(
+        primaryItem: main,
+        time: CMTime(seconds: seconds, preferredTimescale: 600)
     )
-    event.templateItems = [adItem]
-    event.restrictions = [.requiresPlaybackAtPreferredRateForAdvancement]
-
-    controller.events = [event]
+    midroll.templateItems = [AVPlayerItem(asset: AVURLAsset(url: adURL))]
+    midroll.restrictions = [.requiresPlaybackAtPreferredRateForAdvancement]
+    controller.events = [midroll]
+    return controller
 }
-```
-
-### Delegate Callbacks for Interstitials
 
-```swift
-func playerViewController(
-    _ playerViewController: AVPlayerViewController,
-    willPresent interstitial: AVInterstitialTimeRange
-) {
-    // About to play interstitial content  -  disable skip controls
-    playerViewController.requiresLinearPlayback = true
-}
+@MainActor
+final class AdGate: NSObject, @preconcurrency AVPlayerViewControllerDelegate {
+    func playerViewController(_ viewer: AVPlayerViewController, willPresent adBreak: AVInterstitialTimeRange) {
+        viewer.requiresLinearPlayback = true
+    }
 
-func playerViewController(
-    _ playerViewController: AVPlayerViewController,
-    didPresent interstitial: AVInterstitialTimeRange
-) {
-    // Interstitial finished  -  re-enable seeking
-    playerViewController.requiresLinearPlayback = false
+    func playerViewController(_ viewer: AVPlayerViewController, didPresent adBreak: AVInterstitialTimeRange) {
+        viewer.requiresLinearPlayback = false
+    }
 }
 ```
 
-## Background Playback
-
-### Info.plist Configuration
+- Read stream-defined breaks by iterating `interstitialTimeRanges` and taking
+  each `timeRange`.
+- On iOS there are two valid sources: interstitials defined in the stream, or
+  an `AVPlayerInterstitialEventController` schedule. Assigning
+  `interstitialTimeRanges` is not a scheduling mechanism.
+- Once `AVPlayerInterstitialEventController(primaryPlayer:)` sets a schedule,
+  playback ignores interstitial events embedded in the source media. Use it only
+  when the app owns the ad schedule.
+- Lock seeking in `willPresent` and unlock it in `didPresent`.
 
-Add the `audio` background mode:
-
-```xml
-<key>UIBackgroundModes</key>
-<array>
-    <string>audio</string>
-</array>
-```
+## Background playback
 
-### Runtime Behavior
+- Info.plist: `UIBackgroundModes` array containing `audio`.
+- Set the `.playback` category, activate when playback starts, and hold the
+  `AVPlayer` strongly for as long as audio should continue.
+- iOS normally pauses video when its scene moves to the background unless the
+  video goes into PiP. Use PiP for video that keeps playing, and the background
+  audio mode for sound that should keep going once the app is no longer in front.
 
-Set the audio session category to `.playback`, activate it when playback begins,
-and keep a strong reference to the `AVPlayer` for as long as playback should
-continue. iOS generally pauses video when a scene backgrounds unless playback
-moves to PiP. Use PiP for background video continuity; use background audio mode
-for audio that should continue after the user leaves the app.
+## Errors
 
-## Error Handling
+```swift
+import AVFoundation
 
-### Observing Player Item Status
+enum PlaybackProblem {
+    case offline, timedOut, media(Error), unknown
+}
 
-```swift
-func observePlayerItem(_ item: AVPlayerItem) {
-    let observation = item.observe(\.status) { item, _ in
-        switch item.status {
-        case .readyToPlay:
-            // Safe to begin playback
-            break
-        case .failed:
-            if let error = item.error as? NSError {
-                handlePlaybackError(error)
+@MainActor
+func watchStatus(of item: AVPlayerItem, report: @escaping @MainActor (PlaybackProblem?) -> Void) -> NSKeyValueObservation {
+    item.observe(\.status, options: [.new]) { observed, _ in
+        MainActor.assumeIsolated {
+            switch observed.status {
+            case .readyToPlay:
+                report(nil)
+            case .failed:
+                report(classify(observed.error))
+            case .unknown:
+                return
+            @unknown default:
+                report(.unknown)
             }
-        case .unknown:
-            break
-        @unknown default:
-            break
         }
     }
 }
 
-func handlePlaybackError(_ error: NSError) {
-    switch error.domain {
-    case NSURLErrorDomain:
-        // Network-related errors
-        if error.code == NSURLErrorNotConnectedToInternet {
-            // Show offline message
-        } else if error.code == NSURLErrorTimedOut {
-            // Offer retry
-        }
-    case AVFoundationErrorDomain:
-        // AVFoundation-specific errors
-        break
-    default:
-        break
+func classify(_ error: Error?) -> PlaybackProblem {
+    guard let error = error as NSError? else { return .unknown }
+    switch (error.domain, error.code) {
+    case (NSURLErrorDomain, NSURLErrorNotConnectedToInternet): return .offline
+    case (NSURLErrorDomain, NSURLErrorTimedOut): return .timedOut
+    case (AVFoundationErrorDomain, _): return .media(error)
+    default: return .media(error)
     }
 }
-```
 
-### Observing Player Time Control Status
-
-```swift
-func observePlayer(_ player: AVPlayer) {
-    let observation = player.observe(\.timeControlStatus) { player, _ in
-        switch player.timeControlStatus {
-        case .paused:
-            break
-        case .playing:
-            break
-        case .waitingToPlayAtSpecifiedRate:
-            if let reason = player.reasonForWaitingToPlay {
-                switch reason {
-                case .toMinimizeStalls:
-                    // Buffering  -  show spinner
-                    break
-                case .evaluatingBufferingRate:
-                    break
-                case .noItemToPlay:
-                    break
-                default:
-                    break
-                }
+@MainActor
+func watchStalls(of player: AVPlayer, spinner: @escaping @MainActor (Bool) -> Void) -> NSKeyValueObservation {
+    player.observe(\.timeControlStatus, options: [.new]) { observed, _ in
+        MainActor.assumeIsolated {
+            switch observed.timeControlStatus {
+            case .waitingToPlayAtSpecifiedRate:
+                spinner(observed.reasonForWaitingToPlay == .toMinimizeStalls)
+            case .playing, .paused:
+                spinner(false)
+            @unknown default:
+                spinner(false)
             }
-        @unknown default:
-            break
         }
     }
 }
 ```
 
-### Handling AVKitError
+- `AVPlayerItem.status` moves from `.unknown` to `.readyToPlay` or `.failed`;
+  on failure read `item.error`.
+- Split network errors (`NSURLErrorDomain`: show an offline message for
+  `NSURLErrorNotConnectedToInternet`, offer a retry for `NSURLErrorTimedOut`)
+  from media errors in `AVFoundationErrorDomain`.
+- `AVPlayer.timeControlStatus` is `.paused`, `.playing` or
+  `.waitingToPlayAtSpecifiedRate`. While waiting, `reasonForWaitingToPlay` says
+  why: `.toMinimizeStalls` (show a buffering indicator),
+  `.evaluatingBufferingRate` or `.noItemToPlay`.
 
-```swift
-import AVKit
+`AVKitError` codes:
 
-func handleAVKitError(_ error: Error) {
-    guard let avkitError = error as? AVKitError else { return }
-
-    switch avkitError.code {
-    case .pictureInPictureStartFailed:
-        // Check audio session/background mode, support, current possibility,
-        // and whether the player layer or content source is active.
-        break
-    case .contentRatingUnknown:
-        // Content rating could not be determined
-        break
-    case .contentDisallowedByPasscode:
-        // Parental controls restrict this content
-        break
-    case .contentDisallowedByProfile:
-        // MDM profile restricts this content
-        break
-    case .unknown:
-        break
-    @unknown default:
-        break
-    }
-}
-```
+| Code | Meaning |
+|---|---|
+| `.pictureInPictureStartFailed` | PiP could not start; verify the playback category, the `audio` background mode, device support, `isPictureInPicturePossible`, and that the layer or content source feeding PiP is still active |
+| `.contentRatingUnknown` | the content's rating could not be determined |
+| `.contentDisallowedByPasscode` | blocked by parental restrictions |
+| `.contentDisallowedByProfile` | blocked by a device management profile |
+| `.unknown` | unspecified failure |
 
-## Observing Playback State
-
-### Periodic Time Observer
+## Observing playback
 
 ```swift
-func addPeriodicObserver(to player: AVPlayer) -> Any {
-    let interval = CMTime(seconds: 0.5, preferredTimescale: 600)
-    return player.addPeriodicTimeObserver(forInterval: interval, queue: .main) { time in
-        let seconds = CMTimeGetSeconds(time)
-        // Update progress UI
-    }
-}
-
-// Remove when done
-// player.removeTimeObserver(observer)
-```
-
-### Boundary Time Observer
-
-Trigger actions at specific points in the timeline:
+import AVFoundation
 
-```swift
-func addBoundaryObserver(to player: AVPlayer, at times: [CMTime]) -> Any {
-    let timeValues = times.map { NSValue(time: $0) }
-    return player.addBoundaryTimeObserver(forTimes: timeValues, queue: .main) {
-        // Reached a boundary time
+@MainActor
+final class ChapterClock {
+    private let player: AVPlayer
+    private var ticker: Any?
+    private var markers: Any?
+    private var endObserver: NSObjectProtocol?
+
+    init(player: AVPlayer) {
+        self.player = player
+    }
+
+    func start(chapters: [CMTime], onTick: @escaping @Sendable (CMTime) -> Void, onChapter: @escaping @Sendable () -> Void) {
+        let halfSecond = CMTime(value: 1, timescale: 2)
+        ticker = player.addPeriodicTimeObserver(forInterval: halfSecond,
+                                                queue: .main, using: onTick)
+        markers = player.addBoundaryTimeObserver(forTimes: chapters.map { NSValue(time: $0) },
+                                                 queue: .main, using: onChapter)
+        let center = NotificationCenter.default
+        endObserver = center.addObserver(forName: .AVPlayerItemDidPlayToEndTime, object: player.currentItem,
+                                         queue: .main) { _ in onChapter() }
+    }
+
+    func stop() {
+        if let ticker { player.removeTimeObserver(ticker) }
+        if let markers { player.removeTimeObserver(markers) }
+        if let endObserver { NotificationCenter.default.removeObserver(endObserver) }
+        ticker = nil
+        markers = nil
+        endObserver = nil
     }
 }
 ```
 
-### Observing Playback End
-
-```swift
-func observePlaybackEnd(for item: AVPlayerItem) {
-    NotificationCenter.default.addObserver(
-        forName: .AVPlayerItemDidPlayToEndTime,
-        object: item,
-        queue: .main
-    ) { _ in
-        // Playback finished  -  show replay button or load next item
-    }
-}
-```
+- `addPeriodicTimeObserver(forInterval:queue:using:)` returns a token; pass it
+  to `removeTimeObserver(_:)` when done.
+- `addBoundaryTimeObserver(forTimes:queue:using:)` fires at the listed times,
+  wrapped with `NSValue(time:)`.
+- The end of an item is announced with `.AVPlayerItemDidPlayToEndTime`, scoped
+  to that item.
 
-## Video Frame Analysis
+## Video frame analysis
 
-`AVPlayerViewController` supports automatic analysis of paused video frames
-for text recognition, visual search, and subject lifting.
+`allowsVideoFrameAnalysis` (default `true`, iOS 16+) lets the user interact
+with a paused frame: select text, look things up, lift a subject. Narrow it with
+`videoFrameAnalysisTypes` (iOS 17+), whose options include `.text`,
+`.visualSearch`, `.subject` and `.machineReadableCode`, plus `.default`.
 
 ```swift
-let playerVC = AVPlayerViewController()
-
-// Enable frame analysis (default is true)
-playerVC.allowsVideoFrameAnalysis = true
+import AVKit
 
-// Configure which analysis types to perform
-playerVC.videoFrameAnalysisTypes = [.text, .visualSearch, .subject, .machineReadableCode]
+@MainActor
+func onlyTextAndCodes(_ viewer: AVPlayerViewController) {
+    viewer.allowsVideoFrameAnalysis = true
+    viewer.videoFrameAnalysisTypes = [.text, .machineReadableCode]
+}
 ```
 
-## HDR Content
+## HDR
 
-Control how HDR video content renders:
+`AVPlayerViewController.preferredDisplayDynamicRange` (iOS 26+) picks how HDR
+content is shown:
 
-```swift
-// Let the system decide the best rendering
-playerVC.preferredDisplayDynamicRange = .automatic
+| Value | Behavior |
+|---|---|
+| `.automatic` | the system decides (default) |
+| `.standard` | force SDR |
+| `.high` | full HDR |
+| `.constrainedHigh` | limited HDR, useful when HDR sits next to SDR content |
 
-// Force SDR rendering
-playerVC.preferredDisplayDynamicRange = .standard
-
-// Full HDR
-playerVC.preferredDisplayDynamicRange = .high
+```swift
+import AVKit
 
-// Constrained HDR (tone-mapped HDR)
-playerVC.preferredDisplayDynamicRange = .constrainedHigh
+@MainActor
+func calmHDR(_ viewer: AVPlayerViewController) {
+    viewer.preferredDisplayDynamicRange = .constrainedHigh
+}
 ```
 
-## SwiftUI Player Manager
-
-An `@Observable` manager for coordinating playback state across a SwiftUI app:
+## SwiftUI player model
 
 ```swift
-import AVKit
 import AVFoundation
+import AVKit
+import Observation
+import SwiftUI
 
 @Observable
 @MainActor
-final class VideoPlayerManager {
+final class EpisodePlayer {
     private(set) var player: AVPlayer?
+    private(set) var position: Double = 0
     private(set) var isPlaying = false
-    private(set) var currentTime: TimeInterval = 0
-    private(set) var duration: TimeInterval = 0
     private(set) var isBuffering = false
-    private(set) var error: Error?
-
-    private var timeObserver: Any?
-    private var statusObservation: NSKeyValueObservation?
-    private var timeControlObservation: NSKeyValueObservation?
-
-    func loadMedia(url: URL) {
-        cleanup()
-
-        let item = AVPlayerItem(url: url)
-        let newPlayer = AVPlayer(playerItem: item)
-        player = newPlayer
-
-        observeStatus(of: item)
-        observeTimeControl(of: newPlayer)
-        addPeriodicTimeObserver(to: newPlayer)
-    }
-
-    func play() {
-        player?.play()
+    private(set) var length: Double = 0
+    private(set) var failure: String?
+
+    @ObservationIgnored private var tick: Any?
+    @ObservationIgnored private var observations: [NSKeyValueObservation] = []
+
+    func load(_ url: URL) {
+        tearDown()
+        let item = AVPlayerItem(asset: AVURLAsset(url: url))
+        let fresh = AVPlayer(playerItem: item)
+        player = fresh
+
+        observations.append(item.observe(\.status) { [weak self] observed, _ in
+            let status = observed.status
+            let seconds = CMTimeGetSeconds(observed.duration)
+            let message = observed.error?.localizedDescription
+            Task { @MainActor [weak self] in
+                guard let model = self else { return }
+                if status == .readyToPlay { model.length = seconds.isFinite ? seconds : 0 }
+                if status == .failed { model.failure = message }
+            }
+        })
+        observations.append(fresh.observe(\.timeControlStatus) { [weak self] observed, _ in
+            let state = observed.timeControlStatus
+            Task { @MainActor in
+                self?.isPlaying = state == .playing
+                self?.isBuffering = state == .waitingToPlayAtSpecifiedRate
+            }
+        })
+        let every = CMTime(value: 1, timescale: 2)
+        tick = fresh.addPeriodicTimeObserver(forInterval: every, queue: .main) { [weak self] now in
+            let seconds = now.seconds
+            Task { @MainActor in self?.position = seconds }
+        }
     }
 
-    func pause() {
-        player?.pause()
+    func toggle() {
+        guard let player else { return }
+        isPlaying ? player.pause() : player.play()
     }
 
-    func seek(to time: TimeInterval) {
-        let cmTime = CMTime(seconds: time, preferredTimescale: 600)
-        player?.seek(to: cmTime, toleranceBefore: .zero, toleranceAfter: .zero)
+    func jump(to seconds: Double) {
+        player?.seek(to: CMTime(seconds: seconds, preferredTimescale: 600), toleranceBefore: .zero, toleranceAfter: .zero)
     }
 
-    func cleanup() {
-        if let observer = timeObserver, let player {
-            player.removeTimeObserver(observer)
-        }
-        timeObserver = nil
-        statusObservation?.invalidate()
-        timeControlObservation?.invalidate()
+    func tearDown() {
+        if let tick, let player { player.removeTimeObserver(tick) }
+        tick = nil
+        observations.forEach { $0.invalidate() }
+        observations.removeAll()
         player = nil
-        error = nil
         isPlaying = false
-        currentTime = 0
-        duration = 0
+        isBuffering = false
+        position = 0
+        length = 0
+        failure = nil
     }
 
-    private func observeStatus(of item: AVPlayerItem) {
-        statusObservation = item.observe(\.status) { [weak self] item, _ in
-            Task { @MainActor in
-                guard let self else { return }
-                switch item.status {
-                case .readyToPlay:
-                    self.duration = CMTimeGetSeconds(item.duration)
-                case .failed:
-                    self.error = item.error
-                case .unknown:
-                    break
-                @unknown default:
-                    break
-                }
-            }
-        }
-    }
-
-    private func observeTimeControl(of player: AVPlayer) {
-        timeControlObservation = player.observe(\.timeControlStatus) { [weak self] player, _ in
-            Task { @MainActor in
-                guard let self else { return }
-                self.isPlaying = player.timeControlStatus == .playing
-                self.isBuffering = player.timeControlStatus == .waitingToPlayAtSpecifiedRate
-            }
-        }
-    }
-
-    private func addPeriodicTimeObserver(to player: AVPlayer) {
-        let interval = CMTime(seconds: 0.5, preferredTimescale: 600)
-        timeObserver = player.addPeriodicTimeObserver(forInterval: interval, queue: .main) { [weak self] time in
-            Task { @MainActor in
-                self?.currentTime = CMTimeGetSeconds(time)
-            }
-        }
-    }
-
-    deinit {
-        if let observer = timeObserver, let player {
-            player.removeTimeObserver(observer)
-        }
+    isolated deinit {
+        if let tick, let player { player.removeTimeObserver(tick) }
     }
 }
-```
-
-### Using the Manager in SwiftUI
 
-```swift
-import SwiftUI
-import AVKit
-
-struct VideoScreen: View {
-    @State private var manager = VideoPlayerManager()
+struct EpisodeScreen: View {
+    let episodeURL: URL
+    @State private var model = EpisodePlayer()
 
     var body: some View {
-        VStack {
-            if let player = manager.player {
-                VideoPlayer(player: player)
-                    .frame(height: 300)
-
-                HStack {
-                    Button(manager.isPlaying ? "Pause" : "Play") {
-                        manager.isPlaying ? manager.pause() : manager.play()
-                    }
-
-                    Text("\(Int(manager.currentTime))s / \(Int(manager.duration))s")
-                }
+        VStack(spacing: 12) {
+            if let current = model.player {
+                VideoPlayer(player: current)
+                    .aspectRatio(16 / 9, contentMode: .fit)
             }
-
-            if manager.isBuffering {
-                ProgressView("Buffering...")
+            HStack {
+                Button(model.isPlaying ? "Pause" : "Play") { model.toggle() }
+                Text("\(Int(model.position))s / \(Int(model.length))s").monospacedDigit()
+                if model.isBuffering { ProgressView() }
             }
-
-            if let error = manager.error {
-                Text("Error: \(error.localizedDescription)")
-                    .foregroundStyle(.red)
+            if let failure = model.failure {
+                Text(failure).foregroundStyle(.red)
             }
         }
-        .task {
-            manager.loadMedia(url: URL(string: "https://example.com/video.m3u8")!)
-        }
+        .task { model.load(episodeURL) }
     }
 }
 ```
 
-## AVPlayerViewController in UIViewControllerRepresentable
+- `load(_:)` clears previous state, creates the item and player, and installs
+  the status observation, the `timeControlStatus` observation and a periodic
+  time observer.
+- Seeking uses zero tolerance on both sides for frame-accurate jumps, with a
+  timescale of 600.
+- `tearDown()` removes the time observer, invalidates each
+  `NSKeyValueObservation` and resets the published state; the isolated
+  `deinit` removes the time observer as well.
+- Observer closures capture `self` weakly and hop to the main actor with
+  `Task { @MainActor in ... }`. Duration is read with `CMTimeGetSeconds` once
+  the item is ready; buffering is `.waitingToPlayAtSpecifiedRate`.
 
-Full-featured wrapper exposing delegate callbacks, PiP, and playback speed to
-SwiftUI. Prefer this over `VideoPlayer` when you need fine-grained control.
+## Wrapping AVPlayerViewController for SwiftUI
+
+When the app needs the delegate, PiP settings or speed options, a representable
+around `AVPlayerViewController` gives more control than `VideoPlayer`.
 
 ```swift
-import SwiftUI
 import AVKit
+import SwiftUI
 
-struct SystemPlayerView: UIViewControllerRepresentable {
+struct FullPlayer: UIViewControllerRepresentable {
     let player: AVPlayer
-    var allowsPiP: Bool = true
-    var autoStartPiPFromInline: Bool = false
-    var speeds: [AVPlaybackSpeed] = AVPlaybackSpeed.systemDefaultSpeeds
+    var speeds = AVPlaybackSpeed.systemDefaultSpeeds
+    var allowsPiP = true
 
-    func makeUIViewController(context: Context) -> AVPlayerViewController {
-        let controller = AVPlayerViewController()
-        controller.player = player
-        controller.allowsPictureInPicturePlayback = allowsPiP
-        controller.canStartPictureInPictureAutomaticallyFromInline = autoStartPiPFromInline
-        controller.speeds = speeds
-        controller.delegate = context.coordinator
-        return controller
-    }
+    func makeCoordinator() -> Coordinator { Coordinator() }
 
-    func updateUIViewController(_ controller: AVPlayerViewController, context: Context) {
-        controller.player = player
+    func makeUIViewController(context ctx: Context) -> AVPlayerViewController {
+        let viewer = AVPlayerViewController()
+        viewer.player = player
+        viewer.allowsPictureInPicturePlayback = allowsPiP
+        viewer.canStartPictureInPictureAutomaticallyFromInline = allowsPiP
+        viewer.speeds = speeds
+        viewer.delegate = ctx.coordinator
+        return viewer
     }
 
-    func makeCoordinator() -> Coordinator { Coordinator() }
+    func updateUIViewController(_ viewer: AVPlayerViewController, context: Context) {
+        viewer.player = player
+    }
 
-    final class Coordinator: NSObject, AVPlayerViewControllerDelegate {
-        func playerViewController(
-            _ playerViewController: AVPlayerViewController,
-            willBeginFullScreenPresentationWithAnimationCoordinator coordinator: any UIViewControllerTransitionCoordinator
-        ) {
-            // Handle full-screen entry
-        }
+    @MainActor
+    final class Coordinator: NSObject, @preconcurrency AVPlayerViewControllerDelegate {
+        func playerViewController(_ viewer: AVPlayerViewController,
+                                  willBeginFullScreenPresentationWithAnimationCoordinator transition: any UIViewControllerTransitionCoordinator) {}
 
-        func playerViewController(
-            _ playerViewController: AVPlayerViewController,
-            willEndFullScreenPresentationWithAnimationCoordinator coordinator: any UIViewControllerTransitionCoordinator
-        ) {
-            // Handle full-screen exit
-        }
+        func playerViewController(_ viewer: AVPlayerViewController,
+                                  willEndFullScreenPresentationWithAnimationCoordinator transition: any UIViewControllerTransitionCoordinator) {}
 
-        func playerViewController(
-            _ playerViewController: AVPlayerViewController,
-            restoreUserInterfaceForPictureInPictureStopWithCompletionHandler completionHandler: @escaping (Bool) -> Void
-        ) {
-            completionHandler(true)
+        func playerViewController(_ viewer: AVPlayerViewController,
+                                  restoreUserInterfaceForPictureInPictureStopWithCompletionHandler done: @escaping (Bool) -> Void) {
+            done(true)
         }
 
-        func playerViewController(
-            _ playerViewController: AVPlayerViewController,
-            failedToStartPictureInPictureWithError error: any Error
-        ) {
-            print("PiP failed: \(error)")
-        }
+        func playerViewController(_ viewer: AVPlayerViewController,
+                                  failedToStartPictureInPictureWithError reason: any Error) {}
     }
 }
 ```