react-native-audio-browser 0.2.0-next.27 → 0.2.0-next.29

package/ios/Model/NitroTypeStubs.swift

@@ -55,6 +55,23 @@
     case off
     case track
     case queue
+
+    init?(fromString string: String) {
+      switch string {
+      case "off": self = .off
+      case "track": self = .track
+      case "queue": self = .queue
+      default: return nil
+      }
+    }
+
+    var stringValue: String {
+      switch self {
+      case .off: "off"
+      case .track: "track"
+      case .queue: "queue"
+      }
+    }
   }
 
   enum CarPlaySiriListButtonPosition {
@@ -313,7 +330,7 @@
     }
   }
 
-  // MARK: - Playback Event Types (used by PlaybackCoordinator)
+  // MARK: - Playback Event Types (used by Player)
 
   /// Public to match the generated Nitro enum, which `TrackPlayerError`
   /// exposes from a public property.

package/ios/Model/PlayerUpdateOptions.swift

@@ -2,7 +2,7 @@ import Foundation
 import NitroModules
 
 /**
- * Update options for the TrackPlayer that can be changed at runtime.
+ * Update options for the player that can be changed at runtime.
  * These options control player behavior and capabilities that can be modified during playback.
  */
 class PlayerUpdateOptions {

package/ios/NowPlayingInfo/NowPlayingInfoController.swift

@@ -3,62 +3,45 @@ import Foundation
 @preconcurrency import MediaPlayer
 import os.log
 
-// MPRemoteCommandCenter is not Sendable, but we only use it on the main thread
-extension MPRemoteCommandCenter: @retroactive @unchecked Sendable {}
-
 /// Controller for managing Now Playing info.
 ///
 /// A `MPNowPlayingSession` bound to the linked AVPlayer publishes now-playing info
 /// automatically: the system derives elapsed time, playback rate, and duration from
 /// the player, so the per-second clock stays out of our code (it extrapolates the
-/// scrubber). We supply the two things automatic publishing does NOT provide:
-/// metadata (title/artist/artwork), attached to `AVPlayerItem.nowPlayingInfo` (the
-/// supported channel under automatic publishing); and the explicit `playbackState`
-/// that CarPlay / Control Center read for their play/pause button (see `setPlaybackState`).
+/// scrubber). We supply what automatic publishing does not: metadata (title/artist/
+/// artwork), attached to `AVPlayerItem.nowPlayingInfo` (the supported channel under
+/// automatic publishing). An explicit `playbackState` would be dropped: iOS ignores it
+/// without a private entitlement (ADR 0005).
 @MainActor
 class NowPlayingInfoController {
   private let logger = Logger(subsystem: "com.audiobrowser", category: "NowPlayingInfoController")
 
   private var _info: [String: Any] = [:]
 
-  /// Last play/pause state pushed to the session's center, to skip redundant writes.
-  private var _playbackState: MPNowPlayingPlaybackState?
-
   /// The session bound to the linked AVPlayer; held so it stays alive while publishing.
   private var nowPlayingSession: MPNowPlayingSession?
 
   /// The linked AVPlayer — metadata is attached to its current item.
   private weak var linkedPlayer: AVPlayer?
 
-  /// The current remote command center - the session's while linked, else the shared one.
-  private(set) var remoteCommandCenter: MPRemoteCommandCenter = .shared()
-
   required init() {}
 
-  /// Callback invoked when the remote command center changes (session created/destroyed).
-  var onRemoteCommandCenterChanged: ((MPRemoteCommandCenter) -> Void)?
-
-  /// Binds an AVPlayer to a new auto-publishing `MPNowPlayingSession`.
-  ///
-  /// - Important: This creates an `MPNowPlayingSession` with its own `remoteCommandCenter`;
-  ///   the `onRemoteCommandCenterChanged` callback is invoked with the new command center.
-  func linkPlayer(_ player: AVPlayer) {
+  /// Binds an AVPlayer to a new auto-publishing `MPNowPlayingSession`, and returns the session's
+  /// own remote command center, which remote commands must now be enabled on.
+  func linkPlayer(_ player: AVPlayer) -> MPRemoteCommandCenter {
     logger.notice("Linking AVPlayer to MPNowPlayingSession for automatic publishing")
 
     linkedPlayer = player
 
     let session = MPNowPlayingSession(players: [player])
     nowPlayingSession = session
-    _playbackState = nil // new center starts at .unknown; force the next write
-    remoteCommandCenter = session.remoteCommandCenter
 
     session.automaticallyPublishesNowPlayingInfo = true
 
     session.becomeActiveIfPossible { success in
       self.logger.notice("MPNowPlayingSession becomeActiveIfPossible: \(success)")
     }
-
-    onRemoteCommandCenterChanged?(remoteCommandCenter)
+    return session.remoteCommandCenter
   }
 
   /// Re-requests now-playing activation for the linked session.
@@ -77,17 +60,14 @@ class NowPlayingInfoController {
     }
   }
 
-  /// Unlinks the AVPlayer, tearing down the session and restoring the shared command center.
+  /// Unlinks the AVPlayer and tears down the session with its command center. Remote commands
+  /// never fall back to the shared center, whose targets belong to the host app.
   func unlinkPlayer() {
     logger.info("Unlinking AVPlayer from MPNowPlayingSession")
 
     linkedPlayer = nil
     nowPlayingSession?.automaticallyPublishesNowPlayingInfo = false
     nowPlayingSession = nil
-    _playbackState = nil
-
-    remoteCommandCenter = MPRemoteCommandCenter.shared()
-    onRemoteCommandCenterChanged?(remoteCommandCenter)
   }
 
   /// Keys the session derives from the player itself — we never set these manually,
@@ -112,22 +92,18 @@ class NowPlayingInfoController {
     }
   }
 
-  /// Sets key-values and immediately updates Now Playing.
-  /// Playback-dynamics keys (elapsed/duration/rate) are owned by the session and skipped.
-  func set(keyValues: [NowPlayingInfoKeyValue]) {
+  /// Sets now-playing fields, keyed by their `MPMediaItemProperty*` / `MPNowPlayingInfoProperty*`
+  /// names (nil removes one), and publishes when any changed. Elapsed time, duration and rate
+  /// are the session's to publish and are ignored. Returns whether anything changed.
+  @discardableResult
+  func set(_ fields: [String: Any?]) -> Bool {
     var changed = false
-    for kv in keyValues where !Self.autoPublishedKeys.contains(kv.key) && !valueUnchanged(kv.key, kv.value) {
-      _info[kv.key] = kv.value
+    for (key, value) in fields where !Self.autoPublishedKeys.contains(key) && !valueUnchanged(key, value) {
+      _info[key] = value
       changed = true
     }
     if changed { performUpdate() }
-  }
-
-  /// Sets a single key-value and immediately updates Now Playing.
-  func set(keyValue: NowPlayingInfoKeyValue) {
-    guard !Self.autoPublishedKeys.contains(keyValue.key), !valueUnchanged(keyValue.key, keyValue.value) else { return }
-    _info[keyValue.key] = keyValue.value
-    performUpdate()
+    return changed
   }
 
   /// Attaches metadata to the current item — the supported channel under automatic publishing.
@@ -155,15 +131,4 @@ class NowPlayingInfoController {
     linkedPlayer?.currentItem?.nowPlayingInfo = nil
     nowPlayingSession?.nowPlayingInfoCenter.nowPlayingInfo = nil
   }
-
-  /// Sets the play/pause state CarPlay / Control Center show for their transport
-  /// button. Automatic publishing fills the info dict (metadata/elapsed/rate) but
-  /// not the explicit `playbackState`, so the coordinator pushes the user's
-  /// play/pause intent here on intent/state changes.
-  func setPlaybackState(playing: Bool) {
-    let state: MPNowPlayingPlaybackState = playing ? .playing : .paused
-    guard state != _playbackState else { return }
-    _playbackState = state
-    nowPlayingSession?.nowPlayingInfoCenter.playbackState = state
-  }
 }

package/ios/Observer/ItemObserver.swift

@@ -0,0 +1,90 @@
+@preconcurrency import AVFoundation
+
+// Delivered on the main queue through AVPlayerItemMetadataOutputPushDelegate.
+extension AVTimedMetadataGroup: @retroactive @unchecked Sendable {}
+
+/// Observes one AVPlayerItem from creation to `invalidate()`: its status and buffer, the
+/// end-of-item and stall notifications, and its timed metadata. KVO and notifications arrive off
+/// the main thread; anything that lands after `invalidate()` is dropped, so an old item's late
+/// failure never reaches the next item's handlers.
+@MainActor
+final class ItemObserver: NSObject {
+  enum Event {
+    case likelyToKeepUp(Bool)
+    case failed(Error?)
+    case playedToEnd
+    case failedToPlayToEnd(Error?)
+    /// The buffer emptied mid-playback.
+    case stalled
+    case timedMetadata([AVTimedMetadataGroup])
+  }
+
+  private let item: AVPlayerItem
+  private let onEvent: @MainActor (Event) -> Void
+  private var observations: [NSKeyValueObservation] = []
+  private var notificationTokens: [any NSObjectProtocol] = []
+  private let metadataOutput = AVPlayerItemMetadataOutput()
+  private(set) var isActive = true
+
+  init(item: AVPlayerItem, onEvent: @escaping @MainActor (Event) -> Void) {
+    self.item = item
+    self.onEvent = onEvent
+    super.init()
+    observations = [
+      item.observe(\.isPlaybackLikelyToKeepUp, options: [.new]) { [weak self] item, _ in
+        let isLikely = item.isPlaybackLikelyToKeepUp
+        Task { @MainActor in self?.emit(.likelyToKeepUp(isLikely)) }
+      },
+      item.observe(\.status, options: [.new]) { [weak self] item, _ in
+        guard item.status == .failed else { return }
+        let error = item.error
+        Task { @MainActor in self?.emit(.failed(error)) }
+      },
+    ]
+    notificationTokens = [
+      observe(.AVPlayerItemDidPlayToEndTime) { _ in .playedToEnd },
+      observe(.AVPlayerItemFailedToPlayToEndTime) {
+        .failedToPlayToEnd($0.userInfo?[AVPlayerItemFailedToPlayToEndTimeErrorKey] as? Error)
+      },
+      observe(.AVPlayerItemPlaybackStalled) { _ in .stalled },
+    ]
+    metadataOutput.setDelegate(self, queue: .main)
+    item.add(metadataOutput)
+  }
+
+  func invalidate() {
+    guard isActive else { return }
+    isActive = false
+    observations.removeAll()
+    for token in notificationTokens {
+      NotificationCenter.default.removeObserver(token)
+    }
+    notificationTokens = []
+    item.remove(metadataOutput)
+  }
+
+  private func observe(
+    _ name: Notification.Name,
+    _ event: @escaping @Sendable (Notification) -> Event,
+  ) -> any NSObjectProtocol {
+    NotificationCenter.default.addObserver(forName: name, object: item, queue: nil) { [weak self] notification in
+      let event = event(notification)
+      Task { @MainActor in self?.emit(event) }
+    }
+  }
+
+  private func emit(_ event: Event) {
+    guard isActive else { return }
+    onEvent(event)
+  }
+}
+
+extension ItemObserver: AVPlayerItemMetadataOutputPushDelegate {
+  nonisolated func metadataOutput(
+    _: AVPlayerItemMetadataOutput,
+    didOutputTimedMetadataGroups groups: [AVTimedMetadataGroup],
+    from _: AVPlayerItemTrack?,
+  ) {
+    MainActor.assumeIsolated { emit(.timedMetadata(groups)) }
+  }
+}

package/ios/Observer/PlayerObserver.swift

@@ -0,0 +1,59 @@
+import AVFoundation
+
+/// Observes one AVPlayer from creation to `invalidate()`: its status, its time-control status,
+/// and the moment audio starts. A recreated player gets a new observer, so nothing a released
+/// player reports reaches its successor.
+@MainActor
+final class PlayerObserver {
+  enum Event {
+    case status(AVPlayer.Status)
+    case timeControlStatus(AVPlayer.TimeControlStatus)
+    /// Playback crossed the first millisecond.
+    case audioDidStart
+  }
+
+  /// A boundary time cannot be zero.
+  private static let startBoundaryTime = CMTime(value: 1, timescale: 1000)
+
+  private let player: AVPlayer
+  private let onEvent: @MainActor (Event) -> Void
+  private var observations: [NSKeyValueObservation] = []
+  private(set) var boundaryObserverToken: Any?
+  private var isActive = true
+
+  init(player: AVPlayer, onEvent: @escaping @MainActor (Event) -> Void) {
+    self.player = player
+    self.onEvent = onEvent
+    observations = [
+      player.observe(\.status, options: [.new, .initial]) { [weak self] player, _ in
+        let status = player.status
+        Task { @MainActor in self?.emit(.status(status)) }
+      },
+      player.observe(\.timeControlStatus, options: [.new]) { [weak self] player, _ in
+        let status = player.timeControlStatus
+        Task { @MainActor in self?.emit(.timeControlStatus(status)) }
+      },
+    ]
+    boundaryObserverToken = player.addBoundaryTimeObserver(
+      forTimes: [NSValue(time: Self.startBoundaryTime)], queue: nil,
+    ) { [weak self] in
+      Task { @MainActor in self?.emit(.audioDidStart) }
+    }
+  }
+
+  /// Stops all delivery, including events already hopping to the main actor. An AVPlayer
+  /// retains its time observers, so one left registered outlives the observer (#96).
+  func invalidate() {
+    isActive = false
+    observations.removeAll()
+    if let boundaryObserverToken {
+      player.removeTimeObserver(boundaryObserverToken)
+      self.boundaryObserverToken = nil
+    }
+  }
+
+  private func emit(_ event: Event) {
+    guard isActive else { return }
+    onEvent(event)
+  }
+}

package/ios/Option/SessionCategories.swift

@@ -1,123 +1,72 @@
 import AVFoundation
-import Foundation
-import MediaPlayer
 
-enum SessionCategory: String {
-  case playAndRecord, multiRoute, playback, ambient, soloAmbient
-
-  func mapConfigToAVAudioSessionCategory() -> AVAudioSession.Category {
+extension IOSCategory {
+  var avCategory: AVAudioSession.Category {
     switch self {
-    case .playAndRecord:
-      .playAndRecord
-    case .multiRoute:
-      .multiRoute
-    case .playback:
-      .playback
-    case .ambient:
-      .ambient
-    case .soloAmbient:
-      .soloAmbient
+    case .playback: .playback
+    case .playandrecord: .playAndRecord
+    case .multiroute: .multiRoute
+    case .ambient: .ambient
+    case .soloambient: .soloAmbient
+    case .record: .record
     }
   }
 }
 
-enum SessionCategoryPolicy: String {
-  case `default`, longFormAudio, longFormVideo
-
-  func toRouteSharingPolicy() -> AVAudioSession.RouteSharingPolicy {
+extension IOSCategoryMode {
+  var avMode: AVAudioSession.Mode {
     switch self {
-    case .default:
-      .default
-    case .longFormAudio:
-      .longFormAudio
-    case .longFormVideo:
-      .longFormVideo
+    case .default: .default
+    case .gamechat: .gameChat
+    case .measurement: .measurement
+    case .movieplayback: .moviePlayback
+    case .spokenaudio: .spokenAudio
+    case .videochat: .videoChat
+    case .videorecording: .videoRecording
+    case .voicechat: .voiceChat
+    case .voiceprompt: .voicePrompt
     }
   }
 }
 
-enum SessionCategoryMode: String {
-  case `default`, gameChat, measurement, moviePlayback, spokenAudio, videoChat, videoRecording,
-       voiceChat, voicePrompt
-
-  func mapConfigToAVAudioSessionCategoryMode() -> AVAudioSession.Mode {
+extension IOSCategoryPolicy {
+  var avPolicy: AVAudioSession.RouteSharingPolicy {
     switch self {
-    case .default:
-      .default
-    case .gameChat:
-      .gameChat
-    case .measurement:
-      .measurement
-    case .moviePlayback:
-      .moviePlayback
-    case .spokenAudio:
-      .spokenAudio
-    case .videoChat:
-      .videoChat
-    case .videoRecording:
-      .videoRecording
-    case .voiceChat:
-      .voiceChat
-    case .voicePrompt:
-      .voicePrompt
+    case .default: .default
+    case .longformaudio: .longFormAudio
+    case .longformvideo: .longFormVideo
     }
   }
 }
 
-enum SessionCategoryOptions: String {
-  case mixWithOthers, duckOthers, interruptSpokenAudioAndMixWithOthers, allowBluetooth,
-       allowBluetoothA2DP,
-       allowAirPlay,
-       defaultToSpeaker
-
-  func mapConfigToAVAudioSessionCategoryOptions() -> AVAudioSession.CategoryOptions? {
+extension IOSCategoryOptions {
+  var avOptions: AVAudioSession.CategoryOptions {
     switch self {
-    case .mixWithOthers:
-      .mixWithOthers
-    case .duckOthers:
-      .duckOthers
-    case .interruptSpokenAudioAndMixWithOthers:
-      .interruptSpokenAudioAndMixWithOthers
-    case .allowBluetooth:
-      .allowBluetoothHFP
-    case .allowBluetoothA2DP:
-      .allowBluetoothA2DP
-    case .allowAirPlay:
-      .allowAirPlay
-    case .defaultToSpeaker:
-      .defaultToSpeaker
+    case .mixwithothers: .mixWithOthers
+    case .duckothers: .duckOthers
+    case .interruptspokenaudioandmixwithothers: .interruptSpokenAudioAndMixWithOthers
+    case .allowbluetooth: .allowBluetoothHFP
+    case .allowbluetootha2dp: .allowBluetoothA2DP
+    case .allowairplay: .allowAirPlay
+    case .defaulttospeaker: .defaultToSpeaker
     }
   }
 }
 
 extension NativeIOSSetupOptions {
-  /// The resolved `AVAudioSession` category configuration from the iOS setup options. Each field
-  /// falls back to a playback default when it's absent or unrecognised, so a consumer's
-  /// `categoryOptions` (e.g. `allowBluetooth` / `allowAirPlay`), `mode`, and route `policy` are
-  /// actually honoured at setup instead of being dropped.
+  /// The `AVAudioSession` configuration these options ask for; an absent field takes the
+  /// playback default.
   func resolveAudioSessionConfig() -> (
     category: AVAudioSession.Category,
     mode: AVAudioSession.Mode,
     policy: AVAudioSession.RouteSharingPolicy,
     options: AVAudioSession.CategoryOptions,
   ) {
-    let category = self.category
-      .flatMap { SessionCategory(rawValue: $0.stringValue) }?
-      .mapConfigToAVAudioSessionCategory() ?? .playback
-    let mode = self.categoryMode
-      .flatMap { SessionCategoryMode(rawValue: $0.stringValue) }?
-      .mapConfigToAVAudioSessionCategoryMode() ?? .default
-    let policy = self.categoryPolicy
-      .flatMap { SessionCategoryPolicy(rawValue: $0.stringValue) }?
-      .toRouteSharingPolicy() ?? .default
-    let options = (self.categoryOptions ?? [])
-      .reduce(into: AVAudioSession.CategoryOptions()) { acc, option in
-        if let mapped = SessionCategoryOptions(rawValue: option.stringValue)?
-          .mapConfigToAVAudioSessionCategoryOptions()
-        {
-          acc.insert(mapped)
-        }
-      }
-    return (category, mode, policy, options)
+    (
+      category?.avCategory ?? .playback,
+      categoryMode?.avMode ?? .default,
+      categoryPolicy?.avPolicy ?? .default,
+      AVAudioSession.CategoryOptions((categoryOptions ?? []).map(\.avOptions)),
+    )
   }
 }

package/ios/Player/AudioSessionController.swift

@@ -0,0 +1,177 @@
+import AVFoundation
+import NitroModules
+
+/// What `AudioSessionController` tells the player about the audio session.
+@MainActor
+protocol AudioSessionPlayer: AnyObject {
+  var playWhenReady: Bool { get }
+  var willResumeAfterInterruption: Bool { get }
+  func handleInterruptionBegan()
+  func handleInterruptionEnded(shouldResume: Bool)
+  func handleRouteDisconnected()
+  func mediaServicesWereReset()
+}
+
+/// Owns the app's `AVAudioSession`: its category, activation and release, and the interruption,
+/// route-change, media-services-reset and volume observers, installed once at init.
+///
+/// The session is configured at setup but activated only when playback produces output:
+/// activating a non-mixable session interrupts other apps' audio, which must not happen at
+/// launch.
+@MainActor
+final class AudioSessionController {
+  weak var player: AudioSessionPlayer?
+
+  let outputChanged = Emitter<Output>()
+  let volumeChanged = Emitter<Double>()
+
+  /// Nil until `configure`: before setup the category is the host app's, not ours to restore.
+  private var configuration: (
+    category: AVAudioSession.Category,
+    mode: AVAudioSession.Mode,
+    policy: AVAudioSession.RouteSharingPolicy,
+    options: AVAudioSession.CategoryOptions,
+  )?
+
+  private var releaseWork: DispatchWorkItem?
+
+  /// Touched only by `init` and `deinit`.
+  private nonisolated(unsafe) var observers: [NSObjectProtocol] = []
+  private var volumeObservation: NSKeyValueObservation?
+
+  private var session: AVAudioSession {
+    .sharedInstance()
+  }
+
+  init() {
+    let center = NotificationCenter.default
+    observers = [
+      center.addObserver(forName: AVAudioSession.interruptionNotification, object: nil, queue: .main) {
+        [weak self] notification in
+        let info = notification.userInfo
+        let type = info?[AVAudioSessionInterruptionTypeKey] as? UInt
+        let reason = info?[AVAudioSessionInterruptionReasonKey] as? UInt
+        let options = info?[AVAudioSessionInterruptionOptionKey] as? UInt
+        MainActor.assumeIsolated { self?.handleInterruption(type: type, reason: reason, options: options) }
+      },
+      center.addObserver(forName: AVAudioSession.routeChangeNotification, object: nil, queue: .main) {
+        [weak self] notification in
+        let reason = notification.userInfo?[AVAudioSessionRouteChangeReasonKey] as? UInt
+        MainActor.assumeIsolated { self?.handleRouteChange(reason: reason) }
+      },
+      center.addObserver(forName: AVAudioSession.mediaServicesWereResetNotification, object: nil, queue: .main) {
+        [weak self] _ in
+        MainActor.assumeIsolated {
+          // The reset cleared the category and invalidated every player and session handle.
+          self?.applyCategory()
+          self?.player?.mediaServicesWereReset()
+        }
+      },
+    ]
+    volumeObservation = session.observe(\.outputVolume, options: [.new]) { [weak self] _, change in
+      guard let volume = change.newValue else { return }
+      Task { @MainActor in self?.volumeChanged.emit(Double(volume)) }
+    }
+  }
+
+  deinit {
+    for observer in observers {
+      NotificationCenter.default.removeObserver(observer)
+    }
+  }
+
+  /// Sets the session category from the iOS setup options, without activating it.
+  func configure(_ options: NativeIOSSetupOptions?) {
+    configuration = options?.resolveAudioSessionConfig() ?? (.playback, .default, .default, [])
+    applyCategory()
+  }
+
+  /// Activates the session for output and cancels a pending release.
+  func activate() {
+    try? session.setActive(true)
+    cancelRelease()
+  }
+
+  /// Releases the session after 3 s unless playback resumes, so other apps' audio can come back.
+  /// Debounced: iOS dislikes deactivating while audio trails off, and a quick pause → resume
+  /// should not thrash it.
+  func scheduleRelease() {
+    releaseWork?.cancel()
+    let release = DispatchWorkItem { [weak self] in
+      guard let self, player?.playWhenReady == false else { return }
+      releaseWork = nil
+      try? session.setActive(false, options: .notifyOthersOnDeactivation)
+    }
+    releaseWork = release
+    DispatchQueue.main.asyncAfter(deadline: .now() + 3, execute: release)
+  }
+
+  func cancelRelease() {
+    releaseWork?.cancel()
+    releaseWork = nil
+  }
+
+  nonisolated static var volume: Double {
+    Double(AVAudioSession.sharedInstance().outputVolume)
+  }
+
+  nonisolated static var currentOutput: Output? {
+    guard let output = AVAudioSession.sharedInstance().currentRoute.outputs.first else { return nil }
+    let (type, external): (OutputType, Bool) = switch output.portType {
+    case .builtInSpeaker: (.speaker, false)
+    case .builtInReceiver: (.receiver, false)
+    case .airPlay: (.airplay, true)
+    case .bluetoothA2DP, .bluetoothHFP, .bluetoothLE: (.bluetooth, true)
+    case .headphones: (.headphones, true)
+    case .carAudio: (.car, true)
+    case .HDMI: (.hdmi, true)
+    case .usbAudio: (.usb, true)
+    default: (.other, true)
+    }
+    return Output(type: type, name: output.portName, external: external)
+  }
+
+  // MARK: - Private
+
+  private func applyCategory() {
+    guard let configuration else { return }
+    try? session.setCategory(
+      configuration.category, mode: configuration.mode, policy: configuration.policy, options: configuration.options,
+    )
+  }
+
+  private func handleInterruption(type: UInt?, reason: UInt?, options: UInt?) {
+    guard let type = type.flatMap(AVAudioSession.InterruptionType.init(rawValue:)) else { return }
+    switch type {
+    case .began:
+      // iOS 17+ also begins one, never ended, when an output route disappears; the route
+      // change handles that.
+      if #available(iOS 17.0, *),
+         let reason,
+         AVAudioSession.InterruptionReason(rawValue: reason) == .routeDisconnected
+      {
+        return
+      }
+      player?.handleInterruptionBegan()
+    case .ended:
+      let shouldResume = options.map { AVAudioSession.InterruptionOptions(rawValue: $0).contains(.shouldResume) } ?? false
+      // Reactivate only when a resume follows: activating while staying paused would hold a
+      // non-mixable session with nothing to release it.
+      if shouldResume, player?.willResumeAfterInterruption == true {
+        try? session.setActive(true)
+      }
+      player?.handleInterruptionEnded(shouldResume: shouldResume)
+    @unknown default:
+      break
+    }
+  }
+
+  private func handleRouteChange(reason: UInt?) {
+    // The output disappeared (headphones unplugged, a speaker off): pause, as every media app
+    // does, rather than carry on from the built-in speaker.
+    if let reason, AVAudioSession.RouteChangeReason(rawValue: reason) == .oldDeviceUnavailable {
+      player?.handleRouteDisconnected()
+    }
+    if let output = Self.currentOutput { outputChanged.emit(output) }
+  }
+}