@mmerterden/multi-agent-pipeline 20.7.0 → 20.8.1

package/pipeline/skills/shared/external/photos-camera-media/references/av-playback.md

@@ -1,46 +1,42 @@
-# AV Playback
-
-Patterns for media playback with AVPlayer, streaming HLS content, audio
-session configuration, background audio, Now Playing integration, remote
-command handling, and Picture-in-Picture.
+# Audio and video playback
 
 ## Contents
 
-- [AVPlayer and AVPlayerViewController Setup](#avplayer-and-avplayerviewcontroller-setup)
-- [AVPlayerItem and AVAsset Loading](#avplayeritem-and-avasset-loading)
-- [Playback Controls](#playback-controls)
-- [Observing Player State and Time](#observing-player-state-and-time)
-- [Streaming HLS Content](#streaming-hls-content)
-- [AVAudioSession Configuration](#avaudiosession-configuration)
-- [Background Audio Setup](#background-audio-setup)
-- [Now Playing Info Center](#now-playing-info-center)
-- [MPRemoteCommandCenter](#mpremotecommandcenter)
-- [Picture-in-Picture](#picture-in-picture)
+- [Players and where they render](#players-and-where-they-render)
+- [Assets and items](#assets-and-items)
+- [Transport controls](#transport-controls)
+- [Watching state and time](#watching-state-and-time)
+- [HLS streaming](#hls-streaming)
+- [The audio session](#the-audio-session)
+- [Background audio](#background-audio)
+- [Now Playing](#now-playing)
+- [Remote commands](#remote-commands)
+- [Picture in Picture](#picture-in-picture)
+- [Documentation](#documentation)
 
-## AVPlayer and AVPlayerViewController Setup
+## Players and where they render
 
-`AVPlayer` manages playback of a single media asset. Use
-`AVPlayerViewController` (AVKit) for the system-standard playback UI with
-transport controls, or `AVPlayerLayer` for a custom player interface.
+`AVPlayer` drives playback of one asset at a time. Pick the surface by how
+much UI you want to own:
 
-Docs: [AVPlayer](https://sosumi.ai/documentation/avfoundation/avplayer),
-[AVPlayerViewController](https://sosumi.ai/documentation/avkit/avplayerviewcontroller)
+- `AVPlayerViewController` (AVKit) brings the system transport controls.
+- `AVPlayerLayer` draws frames only; you build the controls.
 
-### AVPlayerViewController in SwiftUI
+SwiftUI:
 
 ```swift
-import SwiftUI
 import AVKit
 
-struct VideoPlayerView: View {
-    let url: URL
+struct TrailerView: View {
+    let trailer: URL
     @State private var player: AVPlayer?
 
     var body: some View {
         VideoPlayer(player: player)
             .onAppear {
-                player = AVPlayer(url: url)
-                player?.play()
+                let fresh = AVPlayer(url: trailer)
+                player = fresh
+                fresh.play()
             }
             .onDisappear {
                 player?.pause()
@@ -50,652 +46,410 @@ struct VideoPlayerView: View {
 }
 ```
 
-### AVPlayerViewController in UIKit
+UIKit:
 
 ```swift
-import UIKit
-import AVKit
-
-final class VideoViewController: UIViewController {
-    private var player: AVPlayer?
-
-    func presentVideo(url: URL) {
-        player = AVPlayer(url: url)
-        let controller = AVPlayerViewController()
-        controller.player = player
-        present(controller, animated: true) {
-            self.player?.play()
-        }
-    }
+@MainActor
+func presentTrailer(_ trailer: URL, from host: UIViewController) {
+    let screen = AVPlayerViewController()
+    screen.player = AVPlayer(url: trailer)
+    host.present(screen, animated: true) { screen.player?.play() }
 }
 ```
 
-### Custom Player with AVPlayerLayer
-
-For full control over the player UI, embed an `AVPlayerLayer`:
+Custom surface:
 
 ```swift
-import AVFoundation
-import UIKit
-
-final class PlayerView: UIView {
-    override class var layerClass: AnyClass { AVPlayerLayer.self }
-
-    var playerLayer: AVPlayerLayer { layer as! AVPlayerLayer }
+final class FilmView: UIView {
+    override static var layerClass: AnyClass { AVPlayerLayer.self }
+    private var film: AVPlayerLayer { unsafeDowncast(layer, to: AVPlayerLayer.self) }
 
     var player: AVPlayer? {
-        get { playerLayer.player }
-        set { playerLayer.player = newValue }
-    }
-
-    func configure() {
-        playerLayer.videoGravity = .resizeAspect
+        get { film.player }
+        set {
+            film.player = newValue
+            film.videoGravity = .resizeAspect
+        }
     }
 }
 ```
 
-## AVPlayerItem and AVAsset Loading
-
-`AVAsset` represents the static media (duration, tracks, metadata).
-`AVPlayerItem` adds the dynamic state (current time, buffering status) needed
-for playback.
+## Assets and items
 
-Docs: [AVPlayerItem](https://sosumi.ai/documentation/avfoundation/avplayeritem),
-[AVAsset](https://sosumi.ai/documentation/avfoundation/avasset)
+An `AVAsset` is the media itself: duration, tracks, metadata. An `AVPlayerItem`
+wraps it with the moving parts of playback such as current time and buffer
+state.
 
 ```swift
-import AVFoundation
-
-// Local file
-let localURL = Bundle.main.url(forResource: "intro", withExtension: "mp4")!
-let localItem = AVPlayerItem(url: localURL)
-
-// Remote file
-let remoteURL = URL(string: "https://example.com/video.mp4")!
-let remoteItem = AVPlayerItem(url: remoteURL)
+let quick = AVPlayerItem(url: bundledOrRemoteURL)
 
-// From an existing AVAsset (for more control)
-let asset = AVURLAsset(url: remoteURL, options: [
-    AVURLAssetPreferPreciseDurationAndTimingKey: true
-])
+func preparedItem(for source: URL) async throws -> AVPlayerItem? {
+    let asset = AVURLAsset(url: source, options: [AVURLAssetPreferPreciseDurationAndTimingKey: true])
+    let (length, tracks, playable) = try await asset.load(.duration, .tracks, .isPlayable)
+    guard playable, !tracks.isEmpty, length.isNumeric else { return nil }
+    return AVPlayerItem(asset: asset)
+}
 
-// Load properties asynchronously before playback (iOS 15+)
-let duration = try await asset.load(.duration)
-let tracks = try await asset.load(.tracks)
-let isPlayable = try await asset.load(.isPlayable)
+let deck = AVPlayer(playerItem: quick)
+deck.replaceCurrentItem(with: AVPlayerItem(url: nextEpisodeURL))
 
-let item = AVPlayerItem(asset: asset)
-let player = AVPlayer(playerItem: item)
+let playlist = AVQueuePlayer(items: episodeURLs.map { AVPlayerItem(url: $0) })
 ```
 
-### Replacing the Current Item
-
-Reuse a single `AVPlayer` and swap items:
-
-```swift
-let nextItem = AVPlayerItem(url: nextVideoURL)
-player.replaceCurrentItem(with: nextItem)
-player.play()
-```
+- `AVPlayerItem(url:)` accepts both bundle files and remote URLs.
+- Load asset properties asynchronously with `load(_:)` (iOS 15+) before you
+  depend on them.
+- Keep one player alive and swap media with `replaceCurrentItem(with:)`.
+- `AVQueuePlayer` plays a list and moves to the next item by itself.
 
-### Queue Playback with AVQueuePlayer
+## Transport controls
 
 ```swift
-let items = videoURLs.map { AVPlayerItem(url: $0) }
-let queuePlayer = AVQueuePlayer(items: items)
-queuePlayer.play()
-// Automatically advances to the next item
-```
+deck.play()
+deck.pause()
+deck.rate = 1.5
 
-## Playback Controls
+await deck.seek(to: CMTime(seconds: 42, preferredTimescale: 600))
+await deck.seek(to: CMTime(seconds: 42, preferredTimescale: 600), toleranceBefore: .zero, toleranceAfter: .zero)
 
-```swift
-// Play
-player.play()
-
-// Pause
-player.pause()
-
-// Set playback rate (1.0 = normal, 2.0 = 2x, 0.5 = half speed)
-player.rate = 1.5
-
-// Seek to a specific time
-let targetTime = CMTime(seconds: 30, preferredTimescale: 600)
-await player.seek(to: targetTime)
-
-// Seek with tolerance (for precise seeking, e.g., scrubbing)
-await player.seek(
-    to: targetTime,
-    toleranceBefore: .zero,
-    toleranceAfter: .zero
-)
-
-// Seek to a percentage of duration
-func seekToPercentage(_ percentage: Double) async {
-    guard let duration = player.currentItem?.duration,
-          duration.isNumeric else { return }
-    let targetSeconds = duration.seconds * percentage
-    let target = CMTime(seconds: targetSeconds, preferredTimescale: 600)
-    await player.seek(to: target)
+func jump(_ player: AVPlayer, toFraction fraction: Double) async {
+    guard let total = player.currentItem?.duration, total.isNumeric else { return }
+    await player.seek(to: CMTime(seconds: total.seconds * fraction, preferredTimescale: 600))
 }
 ```
 
-## Observing Player State and Time
-
-### Periodic Time Observer
+`rate` 1.0 is normal speed, 2.0 double, 0.5 half. The zero-tolerance seek is
+exact and is what a scrubber wants; the plain seek is cheaper.
 
-Use `addPeriodicTimeObserver` to update UI elements like a progress bar:
+## Watching state and time
 
 ```swift
-import AVFoundation
-
-@Observable
-@MainActor
-final class PlayerManager {
-    let player = AVPlayer()
-    var currentTime: Double = 0
-    var duration: Double = 0
-    var isPlaying = false
-
-    private var timeObserver: Any?
-
-    func startObserving() {
-        // Fire every 0.5 seconds on the main queue
-        let interval = CMTime(seconds: 0.5, preferredTimescale: 600)
-        timeObserver = player.addPeriodicTimeObserver(
-            forInterval: interval,
-            queue: .main
-        ) { [weak self] time in
-            guard let self else { return }
-            self.currentTime = time.seconds
-            self.duration = self.player.currentItem?.duration.seconds ?? 0
-            self.isPlaying = self.player.timeControlStatus == .playing
-        }
-    }
+import Combine
 
-    func stopObserving() {
-        if let observer = timeObserver {
-            player.removeTimeObserver(observer)
-            timeObserver = nil
+@Observable @MainActor
+final class PlaybackMonitor {
+    private(set) var elapsed = 0.0
+    private(set) var total = 0.0
+    private(set) var isPlaying = false
+    private(set) var failure: Error?
+    private(set) var stallReason: AVPlayer.WaitingReason?
+    @ObservationIgnored private var ticker: Any?
+    @ObservationIgnored private var bag: Set<AnyCancellable> = []
+    @ObservationIgnored private let player: AVPlayer
+
+    init(player: AVPlayer) {
+        self.player = player
+        ticker = player.addPeriodicTimeObserver(forInterval: CMTime(value: 1, timescale: 2),
+                                                queue: .main) { [weak self] now in
+            MainActor.assumeIsolated {
+                guard let self else { return }
+                self.elapsed = now.seconds
+                self.total = player.currentItem?.duration.seconds ?? 0
+                self.isPlaying = player.timeControlStatus == .playing
+            }
         }
+        player.publisher(for: \.status)
+            .receive(on: DispatchQueue.main)
+            .sink { [weak self] status in
+                if status == .failed { self?.failure = player.error }
+            }
+            .store(in: &bag)
+        player.publisher(for: \.timeControlStatus)
+            .receive(on: DispatchQueue.main)
+            .sink { [weak self] mode in
+                self?.stallReason = mode == .waitingToPlayAtSpecifiedRate ? player.reasonForWaitingToPlay : nil
+            }
+            .store(in: &bag)
+        NotificationCenter.default.publisher(for: .AVPlayerItemDidPlayToEndTime, object: player.currentItem)
+            .receive(on: DispatchQueue.main)
+            .sink { _ in player.seek(to: .zero) }
+            .store(in: &bag)
     }
 
-    deinit {
-        if let observer = timeObserver {
-            player.removeTimeObserver(observer)
-        }
+    func stop() {
+        if let ticker { player.removeTimeObserver(ticker) }
+        ticker = nil
     }
-}
-```
-
-### Observing Player Status with KVO
-
-Check player and item readiness before playing:
-
-```swift
-import AVFoundation
-import Combine
 
-// Using Combine
-var cancellables = Set<AnyCancellable>()
-
-player.publisher(for: \.status)
-    .sink { status in
-        switch status {
-        case .readyToPlay:
-            print("Ready to play")
-        case .failed:
-            print("Failed: \(player.error?.localizedDescription ?? "")")
-        case .unknown:
-            print("Status unknown")
-        @unknown default:
-            break
-        }
-    }
-    .store(in: &cancellables)
-
-// Observe buffering state
-player.publisher(for: \.timeControlStatus)
-    .sink { status in
-        switch status {
-        case .playing: print("Playing")
-        case .paused: print("Paused")
-        case .waitingToPlayAtSpecifiedRate:
-            print("Buffering: \(player.reasonForWaitingToPlay?.rawValue ?? "")")
-        @unknown default: break
-        }
+    isolated deinit {
+        if let ticker { player.removeTimeObserver(ticker) }
     }
-    .store(in: &cancellables)
-```
-
-### Detecting Playback End
-
-```swift
-NotificationCenter.default.addObserver(
-    forName: .AVPlayerItemDidPlayToEndTime,
-    object: player.currentItem,
-    queue: .main
-) { _ in
-    // Playback finished -- loop, show replay button, or advance
-    player.seek(to: .zero)  // Loop
 }
 ```
 
-## Streaming HLS Content
-
-HTTP Live Streaming (HLS) works directly with `AVPlayer`. Pass the `.m3u8`
-URL and AVFoundation handles adaptive bitrate selection, buffering, and
-failover.
-
-```swift
-let hlsURL = URL(string: "https://example.com/stream/master.m3u8")!
-let player = AVPlayer(url: hlsURL)
-player.play()
-
-// AVPlayer automatically selects the best variant based on:
-// - Network bandwidth
-// - Device capabilities
-// - Display resolution
-```
-
-### Preferred Bitrate and Resolution
+- Inside `MainActor.assumeIsolated` the properties need an explicit `self.`:
+  the implicit-self shorthand after `guard let self` does not reach a nested
+  closure.
+- The periodic observer (every 0.5 s here) feeds progress UI. Remove its token
+  with `removeTimeObserver(_:)` on stop and on teardown.
+- `status` moves to `.readyToPlay` or `.failed` (read `player.error`); it starts
+  as `.unknown`.
+- `timeControlStatus` is `.playing`, `.paused` or
+  `.waitingToPlayAtSpecifiedRate`, the buffering state, with the cause in
+  `reasonForWaitingToPlay`.
+- `.AVPlayerItemDidPlayToEndTime` on the current item marks the end; seek to
+  `.zero` to loop.
+- `AVPlayer` is main-actor bound in the current SDK, so hop to the main queue
+  before touching it from publishers.
+
+## HLS streaming
+
+Give `AVPlayer` an `.m3u8` URL and AVFoundation handles adaptive bitrate,
+buffering and failover. It picks the variant from bandwidth, device capability
+and display resolution. You can cap it:
 
 ```swift
-let item = AVPlayerItem(url: hlsURL)
-
-// Limit maximum resolution (e.g., for cellular)
-item.preferredMaximumResolution = CGSize(width: 1280, height: 720)
-
-// Limit peak bitrate (bits per second)
-item.preferredPeakBitRate = 2_000_000  // 2 Mbps
-
-// For forward buffering duration
-item.preferredForwardBufferDuration = 5  // seconds; 0 = system default
+let live = AVPlayerItem(url: streamURL)
+live.preferredMaximumResolution = CGSize(width: 1280, height: 720)
+live.preferredPeakBitRate = 2_000_000
+live.preferredForwardBufferDuration = 5
 ```
 
-## AVAudioSession Configuration
-
-Configure `AVAudioSession` to tell the system how your app intends to use
-audio. This affects audio routing, mixing behavior, and background playback.
+`preferredPeakBitRate` is in bits per second (2 Mbps above). A forward buffer of
+0 leaves the choice to the system.
 
-Docs: [AVAudioSession](https://sosumi.ai/documentation/avfaudio/avaudiosession),
-[AVAudioSession.Category](https://sosumi.ai/documentation/avfaudio/avaudiosession/category-swift.struct)
+## The audio session
 
-### Categories and Modes
+`AVAudioSession` states what the app does with sound, which decides routing,
+mixing with other apps and background playback.
 
-| Category | Behavior | Common Use |
+| Category | Behaviour | Typical use |
 |---|---|---|
-| `.playback` | Audio plays even with silent switch on; can play in background | Music, podcasts, video |
-| `.playAndRecord` | Simultaneous input and output | Voice/video calls, recording with monitoring |
-| `.ambient` | Mixes with other audio; silenced by switch | Game sound effects, casual audio |
-| `.soloAmbient` | Default; silences other audio; silenced by switch | Default app behavior |
+| `.playback` | keeps playing with the silent switch on, can continue in background | music, podcasts, video |
+| `.playAndRecord` | input and output at once | calls, recording while monitoring |
+| `.ambient` | mixes with other audio, muted by the silent switch | game effects, incidental sound |
+| `.soloAmbient` | the default: silences other audio, muted by the silent switch | |
 
 ```swift
 import AVFAudio
 
-func configureAudioSession(forPlayback: Bool = true) throws {
-    let session = AVAudioSession.sharedInstance()
-
-    if forPlayback {
-        // Media playback: audio continues with silent switch, supports background
-        try session.setCategory(
-            .playback,
-            mode: .default,
-            options: []
-        )
-    } else {
-        // Mix with other apps (e.g., game sounds over user's music)
-        try session.setCategory(
-            .ambient,
-            mode: .default,
-            options: [.mixWithOthers]
-        )
-    }
-
-    try session.setActive(true)
+func enableMixedEffects() throws {
+    let audio = AVAudioSession.sharedInstance()
+    try audio.setCategory(.ambient, options: .mixWithOthers)
+    try audio.setActive(true)
 }
 
-// For video calls
-try AVAudioSession.sharedInstance().setCategory(
-    .playAndRecord,
-    mode: .videoChat,
-    options: [.defaultToSpeaker, .allowBluetooth]
-)
-```
-
-### Handling Audio Interruptions
-
-```swift
-NotificationCenter.default.addObserver(
-    forName: AVAudioSession.interruptionNotification,
-    object: AVAudioSession.sharedInstance(),
-    queue: .main
-) { notification in
-    guard let info = notification.userInfo,
-          let typeValue = info[AVAudioSessionInterruptionTypeKey] as? UInt,
-          let type = AVAudioSession.InterruptionType(rawValue: typeValue) else {
-        return
-    }
-
-    switch type {
-    case .began:
-        // Pause playback -- system has interrupted audio
-        player.pause()
-    case .ended:
-        let options = info[AVAudioSessionInterruptionOptionKey] as? UInt ?? 0
-        if AVAudioSession.InterruptionOptions(rawValue: options).contains(.shouldResume) {
-            player.play()
-        }
-    @unknown default:
-        break
-    }
+func enableVideoCall() throws {
+    let audio = AVAudioSession.sharedInstance()
+    try audio.setCategory(.playAndRecord, mode: .videoChat, options: [.allowBluetoothHFP, .defaultToSpeaker])
+    try audio.setActive(true)
 }
 ```
 
-### Handling Route Changes
+`.allowBluetooth` is deprecated in the iOS 26 SDK; `.allowBluetoothHFP` is its
+replacement.
+
+Interruptions and route changes:
 
 ```swift
-NotificationCenter.default.addObserver(
-    forName: AVAudioSession.routeChangeNotification,
-    object: AVAudioSession.sharedInstance(),
-    queue: .main
-) { notification in
-    guard let info = notification.userInfo,
-          let reasonValue = info[AVAudioSessionRouteChangeReasonKey] as? UInt,
-          let reason = AVAudioSession.RouteChangeReason(rawValue: reasonValue) else {
-        return
+func observeAudioEvents(pause: @escaping @Sendable () -> Void, resume: @escaping @Sendable () -> Void) {
+    let center = NotificationCenter.default
+    center.addObserver(forName: AVAudioSession.interruptionNotification, object: nil, queue: .main) { note in
+        guard let raw = note.userInfo?[AVAudioSessionInterruptionTypeKey] as? UInt,
+              let kind = AVAudioSession.InterruptionType(rawValue: raw) else { return }
+        switch kind {
+        case .began:
+            pause()
+        case .ended:
+            let flags = note.userInfo?[AVAudioSessionInterruptionOptionKey] as? UInt ?? 0
+            if AVAudioSession.InterruptionOptions(rawValue: flags).contains(.shouldResume) { resume() }
+        @unknown default:
+            break
+        }
     }
-
-    if reason == .oldDeviceUnavailable {
-        // Headphones unplugged -- pause playback (Apple HIG requirement)
-        player.pause()
+    center.addObserver(forName: AVAudioSession.routeChangeNotification, object: nil, queue: .main) { note in
+        guard let raw = note.userInfo?[AVAudioSessionRouteChangeReasonKey] as? UInt,
+              AVAudioSession.RouteChangeReason(rawValue: raw) == .oldDeviceUnavailable else { return }
+        pause()
     }
 }
 ```
 
-## Background Audio Setup
-
-To play audio when the app is in the background, two things are required:
-
-1. Enable the `audio` background mode in your app's capabilities.
-2. Configure `AVAudioSession` with the `.playback` category.
-
-### Info.plist Configuration
-
-```xml
-<key>UIBackgroundModes</key>
-<array>
-    <string>audio</string>
-</array>
-```
-
-Or enable "Audio, AirPlay, and Picture in Picture" in Xcode's Signing &
-Capabilities tab.
-
-### Activating Background Audio
+Pause when an interruption begins; resume at its end only if the options say
+`.shouldResume`. When headphones are unplugged (`.oldDeviceUnavailable`),
+pause: the Human Interface Guidelines expect it.
 
-```swift
-import AVFAudio
+## Background audio
 
-func enableBackgroundAudio() throws {
-    let session = AVAudioSession.sharedInstance()
-    try session.setCategory(.playback, mode: .default)
-    try session.setActive(true)
-}
-```
+Two things are needed together: the `audio` background mode and the
+`.playback` category.
 
-**Rules:**
+- Info.plist: `UIBackgroundModes` containing `audio`, or the Xcode capability
+  "Audio, AirPlay, and Picture in Picture".
 - Call `setCategory` before `setActive`.
-- The `.playback` category is required; `.ambient` and `.soloAmbient` do not
-  support background audio.
-- Deactivate the session when playback ends to let other apps use audio:
+- `.ambient` and `.soloAmbient` stop in the background; only `.playback` keeps
+  going.
+- When finished, give audio back to other apps:
 
 ```swift
-func deactivateAudioSession() {
-    try? AVAudioSession.sharedInstance().setActive(
-        false,
-        options: .notifyOthersOnDeactivation
-    )
-}
+try AVAudioSession.sharedInstance().setActive(false, options: .notifyOthersOnDeactivation)
 ```
 
-## Now Playing Info Center
-
-Update `MPNowPlayingInfoCenter` so the system displays track information on
-the lock screen, Control Center, and connected accessories (CarPlay, AirPods).
+## Now Playing
 
-Docs: [MPNowPlayingInfoCenter](https://sosumi.ai/documentation/mediaplayer/mpnowplayinginfocenter)
+`MPNowPlayingInfoCenter` fills the Lock Screen, Control Center and accessories
+such as CarPlay and AirPods.
 
 ```swift
 import MediaPlayer
 
-func updateNowPlayingInfo(
-    title: String,
-    artist: String,
-    albumTitle: String? = nil,
-    duration: TimeInterval,
-    currentTime: TimeInterval,
-    artwork: UIImage? = nil
-) {
-    var info: [String: Any] = [
+func publishNowPlaying(title: String, artist: String, album: String, length: Double, cover: UIImage) {
+    MPNowPlayingInfoCenter.default().nowPlayingInfo = [
         MPMediaItemPropertyTitle: title,
         MPMediaItemPropertyArtist: artist,
-        MPMediaItemPropertyPlaybackDuration: duration,
-        MPNowPlayingInfoPropertyElapsedPlaybackTime: currentTime,
+        MPMediaItemPropertyAlbumTitle: album,
+        MPMediaItemPropertyPlaybackDuration: length,
+        MPNowPlayingInfoPropertyElapsedPlaybackTime: 0.0,
         MPNowPlayingInfoPropertyPlaybackRate: 1.0,
-        MPNowPlayingInfoPropertyMediaType: MPNowPlayingInfoMediaType.audio.rawValue
+        MPNowPlayingInfoPropertyMediaType: MPNowPlayingInfoMediaType.audio.rawValue,
+        MPMediaItemPropertyArtwork: MPMediaItemArtwork(boundsSize: cover.size) { _ in cover },
     ]
-
-    if let albumTitle {
-        info[MPMediaItemPropertyAlbumTitle] = albumTitle
-    }
-
-    if let artwork {
-        info[MPMediaItemPropertyArtwork] = MPMediaItemArtwork(
-            boundsSize: artwork.size
-        ) { _ in artwork }
-    }
-
-    MPNowPlayingInfoCenter.default().nowPlayingInfo = info
 }
 
-// Update elapsed time during playback
-func updateElapsedTime(_ seconds: TimeInterval, rate: Float = 1.0) {
+func refreshProgress(elapsed: Double, rate: Double) {
     var info = MPNowPlayingInfoCenter.default().nowPlayingInfo ?? [:]
-    info[MPNowPlayingInfoPropertyElapsedPlaybackTime] = seconds
+    info[MPNowPlayingInfoPropertyElapsedPlaybackTime] = elapsed
     info[MPNowPlayingInfoPropertyPlaybackRate] = rate
     MPNowPlayingInfoCenter.default().nowPlayingInfo = info
 }
 ```
 
-## MPRemoteCommandCenter
+While playing, update elapsed time and rate by copying the current dictionary,
+changing the two values and assigning it back.
 
-Register handlers for lock screen, Control Center, and accessory controls
-(play, pause, skip, seek). Without these, the system controls won't work.
+## Remote commands
 
-Docs: [MPRemoteCommandCenter](https://sosumi.ai/documentation/mediaplayer/mpremotecommandcenter)
+Lock Screen, Control Center and headphone buttons do nothing until the app
+registers handlers.
 
 ```swift
-import MediaPlayer
-
-func setupRemoteCommands(player: AVPlayer) {
-    let commandCenter = MPRemoteCommandCenter.shared()
-
-    // Play
-    commandCenter.playCommand.isEnabled = true
-    commandCenter.playCommand.addTarget { _ in
-        player.play()
-        return .success
-    }
-
-    // Pause
-    commandCenter.pauseCommand.isEnabled = true
-    commandCenter.pauseCommand.addTarget { _ in
-        player.pause()
-        return .success
-    }
-
-    // Toggle play/pause (headphone button, etc.)
-    commandCenter.togglePlayPauseCommand.isEnabled = true
-    commandCenter.togglePlayPauseCommand.addTarget { _ in
-        if player.timeControlStatus == .playing {
-            player.pause()
-        } else {
-            player.play()
-        }
+@MainActor
+func wireRemote(to player: AVPlayer) {
+    let remote = MPRemoteCommandCenter.shared()
+    let failed = MPRemoteCommandHandlerStatus.commandFailed
+
+    remote.playCommand.isEnabled = true
+    remote.playCommand.addTarget { _ in player.play(); return MPRemoteCommandHandlerStatus.success }
+    remote.pauseCommand.isEnabled = true
+    remote.pauseCommand.addTarget { _ in player.pause(); return MPRemoteCommandHandlerStatus.success }
+    remote.togglePlayPauseCommand.isEnabled = true
+    remote.togglePlayPauseCommand.addTarget { _ in
+        player.timeControlStatus == .playing ? player.pause() : player.play()
         return .success
     }
 
-    // Skip forward (e.g., 15 seconds)
-    commandCenter.skipForwardCommand.isEnabled = true
-    commandCenter.skipForwardCommand.preferredIntervals = [15]
-    commandCenter.skipForwardCommand.addTarget { event in
-        guard let skipEvent = event as? MPSkipIntervalCommandEvent else {
-            return .commandFailed
-        }
-        let currentTime = player.currentTime().seconds
-        let target = CMTime(
-            seconds: currentTime + skipEvent.interval,
-            preferredTimescale: 600
-        )
-        player.seek(to: target)
+    remote.skipForwardCommand.preferredIntervals = [15]
+    remote.skipForwardCommand.addTarget { event in
+        guard let skip = event as? MPSkipIntervalCommandEvent else { return failed }
+        let target = player.currentTime().seconds + skip.interval
+        player.seek(to: CMTime(seconds: target, preferredTimescale: 600))
         return .success
     }
-
-    // Skip backward (e.g., 15 seconds)
-    commandCenter.skipBackwardCommand.isEnabled = true
-    commandCenter.skipBackwardCommand.preferredIntervals = [15]
-    commandCenter.skipBackwardCommand.addTarget { event in
-        guard let skipEvent = event as? MPSkipIntervalCommandEvent else {
-            return .commandFailed
-        }
-        let currentTime = player.currentTime().seconds
-        let target = CMTime(
-            seconds: max(0, currentTime - skipEvent.interval),
-            preferredTimescale: 600
-        )
-        player.seek(to: target)
+    remote.skipBackwardCommand.preferredIntervals = [15]
+    remote.skipBackwardCommand.addTarget { event in
+        guard let skip = event as? MPSkipIntervalCommandEvent else { return failed }
+        let target = max(0, player.currentTime().seconds - skip.interval)
+        player.seek(to: CMTime(seconds: target, preferredTimescale: 600))
         return .success
     }
 
-    // Scrubbing (seek bar on lock screen)
-    commandCenter.changePlaybackPositionCommand.isEnabled = true
-    commandCenter.changePlaybackPositionCommand.addTarget { event in
-        guard let positionEvent = event as? MPChangePlaybackPositionCommandEvent else {
-            return .commandFailed
-        }
-        let target = CMTime(
-            seconds: positionEvent.positionTime,
-            preferredTimescale: 600
-        )
-        player.seek(to: target)
+    remote.changePlaybackPositionCommand.addTarget { event in
+        guard let scrub = event as? MPChangePlaybackPositionCommandEvent else { return failed }
+        player.seek(to: CMTime(seconds: scrub.positionTime, preferredTimescale: 600))
         return .success
     }
 
-    // Disable unsupported commands to remove them from UI
-    commandCenter.nextTrackCommand.isEnabled = false
-    commandCenter.previousTrackCommand.isEnabled = false
+    remote.nextTrackCommand.isEnabled = false
+    remote.previousTrackCommand.isEnabled = false
 }
-```
 
-### Cleanup
-
-```swift
-func teardownRemoteCommands() {
-    let commandCenter = MPRemoteCommandCenter.shared()
-    commandCenter.playCommand.removeTarget(nil)
-    commandCenter.pauseCommand.removeTarget(nil)
-    commandCenter.togglePlayPauseCommand.removeTarget(nil)
-    commandCenter.skipForwardCommand.removeTarget(nil)
-    commandCenter.skipBackwardCommand.removeTarget(nil)
-    commandCenter.changePlaybackPositionCommand.removeTarget(nil)
+func unwireRemote() {
+    let remote = MPRemoteCommandCenter.shared()
+    for command in [remote.playCommand, remote.pauseCommand, remote.togglePlayPauseCommand,
+                    remote.skipForwardCommand, remote.skipBackwardCommand,
+                    remote.changePlaybackPositionCommand] {
+        command.removeTarget(nil)
+    }
 }
 ```
 
-## Picture-in-Picture
-
-`AVPictureInPictureController` enables floating video playback that continues
-when the user navigates away. Requires the `audio` background mode.
+`togglePlayPauseCommand` is the headphone button. Disabling a command you do
+not support (next and previous track here) hides it from the system UI. On
+teardown, `removeTarget(nil)` on every command you registered.
 
-Docs: [AVPictureInPictureController](https://sosumi.ai/documentation/avkit/avpictureinpicturecontroller),
-[Adopting Picture in Picture in a Custom Player](https://sosumi.ai/documentation/avkit/adopting-picture-in-picture-in-a-custom-player)
+## Picture in Picture
 
-### With AVPlayerViewController (Automatic)
+`AVPictureInPictureController` keeps video floating while the person uses other
+apps. It depends on the `audio` background mode.
 
-`AVPlayerViewController` supports PiP automatically when the background audio
-capability is enabled. No extra code needed.
+`AVPlayerViewController` handles PiP by itself once that capability is on;
+`allowsPictureInPicturePlayback` is `true` by default. A custom player wires it
+up:
 
 ```swift
-let controller = AVPlayerViewController()
-controller.player = player
-controller.allowsPictureInPicturePlayback = true  // true by default
-```
-
-### With a Custom Player
-
-```swift
-import AVKit
-
-@Observable
 @MainActor
-final class PiPManager: NSObject, AVPictureInPictureControllerDelegate {
-    private var pipController: AVPictureInPictureController?
-    var isPiPActive = false
-    var isPiPPossible = false
-
-    func setup(playerLayer: AVPlayerLayer) {
-        guard AVPictureInPictureController.isPictureInPictureSupported() else {
-            return
-        }
-
-        pipController = AVPictureInPictureController(playerLayer: playerLayer)
-        pipController?.delegate = self
-
-        // Auto-start PiP when app goes to background
-        pipController?.canStartPictureInPictureAutomaticallyFromInline = true
+final class FloatingVideo: NSObject, @preconcurrency AVPictureInPictureControllerDelegate {
+    private var pip: AVPictureInPictureController?
+    private(set) var isFloating = false
+    var onRestore: (() -> Void)?
+
+    func attach(to film: AVPlayerLayer) {
+        guard AVPictureInPictureController.isPictureInPictureSupported() else { return }
+        let controller = AVPictureInPictureController(playerLayer: film)
+        controller?.delegate = self
+        controller?.canStartPictureInPictureAutomaticallyFromInline = true
+        pip = controller
     }
 
-    func togglePiP() {
-        guard let pipController else { return }
-        if pipController.isPictureInPictureActive {
-            pipController.stopPictureInPicture()
-        } else {
-            pipController.startPictureInPicture()
-        }
+    func toggle() {
+        guard let pip else { return }
+        pip.isPictureInPictureActive ? pip.stopPictureInPicture() : pip.startPictureInPicture()
     }
 
-    // MARK: - AVPictureInPictureControllerDelegate
-
-    nonisolated func pictureInPictureControllerWillStartPictureInPicture(
-        _ controller: AVPictureInPictureController
-    ) {
-        Task { @MainActor in isPiPActive = true }
+    nonisolated func pictureInPictureControllerWillStartPictureInPicture(_ floating: AVPictureInPictureController) {
+        Task { @MainActor in isFloating = true }
     }
 
-    nonisolated func pictureInPictureControllerDidStopPictureInPicture(
-        _ controller: AVPictureInPictureController
-    ) {
-        Task { @MainActor in isPiPActive = false }
+    nonisolated func pictureInPictureControllerDidStopPictureInPicture(_ floating: AVPictureInPictureController) {
+        Task { @MainActor in isFloating = false }
     }
 
-    nonisolated func pictureInPictureController(
+    func pictureInPictureController(
         _ controller: AVPictureInPictureController,
-        restoreUserInterfaceForPictureInPictureStopWithCompletionHandler
-        completionHandler: @escaping (Bool) -> Void
+        restoreUserInterfaceForPictureInPictureStopWithCompletionHandler completionHandler: @escaping (Bool) -> Void
     ) {
-        // Restore your player UI here, then call the handler
-        Task { @MainActor in
-            // Navigate back to the player view
-            completionHandler(true)
-        }
+        onRestore?()
+        completionHandler(true)
     }
 }
 ```
 
-### PiP Requirements Checklist
-
-- [ ] `UIBackgroundModes` includes `audio` in Info.plist
-- [ ] `AVAudioSession` category set to `.playback`
-- [ ] Check `AVPictureInPictureController.isPictureInPictureSupported()` before setup
-- [ ] Implement `restoreUserInterfaceForPictureInPictureStop` delegate method
-- [ ] Call completion handler in the restore delegate method (failure to call causes hangs)
+`canStartPictureInPictureAutomaticallyFromInline` starts PiP on its own when
+the app moves to the background. The restore callback must bring the player UI
+back (or navigate to it) and then call the completion handler.
+AVKit delivers these callbacks on the main thread. The restore method stays
+main-actor isolated under the `@preconcurrency` conformance (Swift checks the
+thread at run time) instead of hopping through a `Task`: the completion handler
+is not `Sendable`, and Swift 6 rejects sending it into a task.
+
+### PiP checklist
+
+- [ ] `UIBackgroundModes` contains `audio`
+- [ ] The audio session category is `.playback`
+- [ ] `isPictureInPictureSupported()` is checked before setup
+- [ ] The restore delegate method is implemented
+- [ ] Its completion handler is always called; skipping it leaves the system
+      waiting
+
+## Documentation
+
+- [AVPlayer](https://developer.apple.com/documentation/avfoundation/avplayer)
+- [AVPlayerViewController](https://developer.apple.com/documentation/avkit/avplayerviewcontroller)
+- [AVPlayerItem](https://developer.apple.com/documentation/avfoundation/avplayeritem)
+- [AVAsset](https://developer.apple.com/documentation/avfoundation/avasset)
+- [AVAudioSession](https://developer.apple.com/documentation/avfaudio/avaudiosession)
+- [AVAudioSession.Category](https://developer.apple.com/documentation/avfaudio/avaudiosession/category)
+- [MPNowPlayingInfoCenter](https://developer.apple.com/documentation/mediaplayer/mpnowplayinginfocenter)
+- [MPRemoteCommandCenter](https://developer.apple.com/documentation/mediaplayer/mpremotecommandcenter)
+- [AVPictureInPictureController](https://developer.apple.com/documentation/avkit/avpictureinpicturecontroller)
+- [Custom player PiP article](https://developer.apple.com/documentation/avkit/adopting-picture-in-picture-in-a-custom-player)