react-native-queue-player 1.2.0 → 2.0.1

package/ios/AVQueueBuilder.swift

@@ -12,11 +12,11 @@ import AVFoundation
 /// Constructs AVPlayerItem instances from TrackItem descriptors,
 /// applying the PlayerConfig's custom HTTP headers + user agent.
 ///
-/// Headers are the load-bearing feature for Subsonic-behind-reverse-
-/// proxy deployments — every remote fetch (asset read, lookahead-
-/// cache download, artwork fetch) has to carry the consumer app's
-/// auth. `AVURLAssetHTTPHeaderFieldsKey` on the AVURLAsset options
-/// dictionary does this on iOS.
+/// Headers carry the consumer app's auth on every remote fetch —
+/// asset read, lookahead-cache download, artwork fetch. An unrouted
+/// asset gets them through `AVURLAssetHTTPHeaderFieldsKey` on its
+/// options dictionary; a routed one is built with no asset options,
+/// and the read-through server sends them on its origin leg instead.
 ///
 /// User-Agent handling: AVURLAsset has no dedicated UA option. The
 /// standard workaround is to include `User-Agent: <ua>` inside the
@@ -28,19 +28,20 @@ public enum AVQueueBuilder {
 
   /// Build AVPlayerItems for every track in `tracks`, applying config
   /// headers + UA on remote URLs. Returns an empty array for an empty
-  /// input. Never throws — invalid URLs silently produce a nil asset
-  /// which AVQueuePlayer surfaces as a playback error at runtime.
+  /// input. Never throws — a track whose URL does not parse is dropped
+  /// from the result (`makeItem` returns nil), so the engine never sees
+  /// it.
   ///
-  /// When `cache` is non-nil + a track is fully cached, the
-  /// AVPlayerItem is built from the local file URL instead of the
-  /// remote one. Bytes never hit the network on playback. Partial
-  /// caches fall through to the remote URL — `cache.cachedURL`
-  /// returns nil for entries that haven't fully downloaded.
+  /// With a non-nil `server`, every routable remote track (`isRoutable`)
+  /// is built on the read-through server's local URL, and the server
+  /// decides per request whether bytes come from the lookahead cache or
+  /// the origin. `file://` tracks, `.m3u8` manifests, and every track when
+  /// `server` is nil bind `track.url` directly — see `makeItem`.
   static func buildPlayerItems(
     tracks: [TrackItem],
     queueItemIds: [String],
     config: PlayerConfig,
-    cache: LookaheadCache? = nil
+    server: ReadThroughServer? = nil
   ) -> [AVPlayerItem] {
     // Parallel-array invariant: a violation is a programming error
     // we own (QueueState uphold-able at construction). `precondition`
@@ -51,41 +52,43 @@ public enum AVQueueBuilder {
       "AVQueueBuilder.buildPlayerItems requires queueItemIds parallel to tracks (1:1)"
     )
     return zip(tracks, queueItemIds).compactMap { track, id in
-      makeItem(for: track, queueItemId: id, config: config, cache: cache)
+      makeItem(for: track, queueItemId: id, config: config, server: server)
     }
   }
 
-  /// Best-effort warm-up of a freshly-built item's asset BEFORE it is
-  /// inserted into a live `AVQueuePlayer`. When the insert lands in the
-  /// immediate-next slot of a playing queue, `AVQueuePlayer` prerolls the
-  /// new item on the shared decode/render pipeline while the current item
-  /// is still rendering; faulting the asset's `tracks` / `duration` /
-  /// `playable` keys in synchronously at that moment briefly disturbs the
-  /// currently-playing item. Loading them here first makes that preroll
-  /// cheap.
+  /// Cancel outstanding key loads on the assets of items being discarded.
   ///
-  /// Best-effort: the load races a [timeout] deadline and the caller
-  /// proceeds as soon as either wins. `AVAsset`'s async loader honours
-  /// task cancellation, so `cancelAll` caps a slow / unreachable remote
-  /// asset at [timeout] and the item is inserted unwarmed rather than
-  /// deferring the enqueue. Load errors are ignored for the same reason.
-  @MainActor
-  static func preloadAssetForInsert(_ item: AVPlayerItem, timeout: TimeInterval = 2.0) async {
-    let asset = item.asset
-    await withTaskGroup(of: Void.self) { group in
-      group.addTask { @MainActor in
-        _ = try? await asset.load(.tracks, .duration, .isPlayable)
-      }
-      group.addTask {
-        try? await Task.sleep(nanoseconds: UInt64(timeout * 1_000_000_000))
-      }
-      _ = await group.next()
-      group.cancelAll()
+  /// `AVURLAsset.dealloc` cancels them implicitly and **blocks the deallocating
+  /// thread while it does** — a dispatch-group wait on the asset inspector,
+  /// measured at tens of seconds for a queue of 200 with loads in flight.
+  /// Cancelling first makes that wait a no-op. That thread is
+  /// `playerQueue`, so the block stalls every queue operation behind it.
+  ///
+  /// Only assets that are genuinely being dropped may be cancelled: a
+  /// cancelled asset can never become playable, so an item rebuilt on a reused
+  /// asset would stall silently. `keeping` is the set that survives, compared
+  /// by identity.
+  static func cancelLoading(dropping outgoing: [AVPlayerItem], keeping: [AVPlayerItem] = []) {
+    for item in itemsBeingDropped(outgoing: outgoing, keeping: keeping) {
+      item.asset.cancelLoading()
     }
   }
 
-  /// Single-item builder. Used by addToQueue. Honours the cache
-  /// lookup when a cache instance is supplied.
+  /// The items in `outgoing` that no entry of `keeping` reuses. Identity, not
+  /// equality: two items can wrap the same asset, and it is the asset's
+  /// survival that decides whether cancelling it is safe.
+  @_spi(QueuePlayerTests)
+  public static func itemsBeingDropped(
+    outgoing: [AVPlayerItem], keeping: [AVPlayerItem]
+  ) -> [AVPlayerItem] {
+    guard !keeping.isEmpty else { return outgoing }
+    let survivingAssets = keeping.map { ObjectIdentifier($0.asset) }
+    let surviving = Set(survivingAssets)
+    return outgoing.filter { !surviving.contains(ObjectIdentifier($0.asset)) }
+  }
+
+  /// Single-item builder behind `buildPlayerItems`. Routes a routable
+  /// remote track through `server` when one is supplied.
   ///
   /// `queueItemId` is the lib-generated identity for this AVPlayerItem
   /// instance — set on the constructed item via the
@@ -95,53 +98,68 @@ public enum AVQueueBuilder {
   /// position; the value passed here is the corresponding entry.
   /// Never derived from any consumer-supplied TrackItem field —
   /// only `track.url` is required + reliable on consumer data.
+  ///
+  /// The consumer's ReplayGain claim over [track] is resolved and
+  /// validated here, once, and stamped on the item alongside those two.
+  /// The item is the only thing the audio path holds, and this is the
+  /// one place that has both it and the `TrackItem` it came from.
   static func makeItem(
     for track: TrackItem,
     queueItemId: String,
     config: PlayerConfig,
-    cache: LookaheadCache? = nil
+    server: ReadThroughServer? = nil
   ) -> AVPlayerItem? {
-    if let cachedURL = cache?.cachedURL(forUrl: track.url) {
-      // Local file URL — no headers needed. `cachedURL` is a pure
-      // read; LRU bookkeeping is opt-in via `touch` so a read-heavy
-      // playback path doesn't trigger a plist write per resolution.
-      cache?.touch(url: track.url)
-      // `automaticallyLoadedAssetKeys` pre-loads the listed keys
-      // asynchronously while the AVPlayerItem itself becomes
-      // addressable — Apple's documented iOS 16+ preferred
-      // construction pattern, shaving first-frame latency vs a
-      // bare `AVPlayerItem(asset:)` that loads keys lazily on first
-      // access.
-      //
-      // `"tracks"` is included here (file:// branch only — the
-      // HTTP path in `makeItemRaw` keeps the original two-key set
-      // so HLS / streaming items don't pay the variant-playlist +
-      // segment-header round-trip at insert time). The local
-      // tracks-key load is free; once it's loaded, the engine's
-      // per-item `audioMix(for:)` install (called BEFORE
-      // `player.insert`) gets a tap-bearing mix synchronously,
-      // which is the only window AVPlayer honours per Apple's
-      // contract (`audioMix` changes after the item starts
-      // rendering are silently dropped).
-      let asset = AVURLAsset(url: cachedURL)
-      let item = AVPlayerItem(
+    // Remote tracks bind the read-through server's URL, which is stable for
+    // the session and never re-pointed. Whether the bytes come from the cache
+    // or the origin is the server's decision, made per request — the only
+    // moment it can be answered, because the cache fills long after the queue
+    // is built. Headers move to the origin leg with it.
+    //
+    // HLS is excluded: proxying a playlist would re-base its relative segment
+    // paths against the local URL. No server means no routing, which is what a
+    // consumer running without the lookahead cache gets.
+    let routed: URL? = Self.isRoutable(track.url) ? server.flatMap { srv in
+      URL(string: track.url).flatMap { srv.localURL(for: $0, sourceURL: track.url) }
+    } : nil
+
+    let item: AVPlayerItem?
+    if let routed {
+      let asset = AVURLAsset(url: routed)
+      let built = AVPlayerItem(
         asset: asset,
-        automaticallyLoadedAssetKeys: ["playable", "duration", "tracks"]
+        automaticallyLoadedAssetKeys: ["playable", "duration"]
       )
-      pinForwardBufferDuration(on: item)
-      item.queueItemId = queueItemId
-      item.sourceURL = track.url
-      return item
+      pinForwardBufferDuration(on: built)
+      built.isRoutedThroughReadThroughServer = true
+      item = built
+    } else {
+      item = makeItemRaw(
+        urlString: track.url,
+        headers: config.httpHeaders,
+        userAgent: config.userAgent)
     }
-    let item = makeItemRaw(
-      urlString: track.url,
-      headers: config.httpHeaders,
-      userAgent: config.userAgent)
     item?.queueItemId = queueItemId
+    // The media's own URL, always — never the transport's. Everything that
+    // reads a container, a codec or a track identity out of a URL reads this.
     item?.sourceURL = track.url
+    item?.suppliedReplayGain = SuppliedReplayGain.from(track: track)
     return item
   }
 
+  /// Whether a URL is one the read-through server can carry.
+  ///
+  /// `http(s)` only, and not a manifest: AVFoundation resolves an HLS
+  /// playlist's relative segment paths against the URL it fetched the playlist
+  /// from, so a proxied playlist would point every segment at the local server
+  /// under a token that names none of them.
+  static func isRoutable(_ urlString: String) -> Bool {
+    guard let url = URL(string: urlString), let scheme = url.scheme?.lowercased(),
+          scheme == "http" || scheme == "https"
+    else { return false }
+    return url.pathExtension.lowercased() != "m3u8"
+  }
+
+
   /// Apple-acknowledged AVPlayer mitigation: explicitly setting
   /// `preferredForwardBufferDuration = 0.0` on every item closes a
   /// long-standing AVQueuePlayer bug where items can be dropped
@@ -198,9 +216,24 @@ public enum AVQueueBuilder {
     return item
   }
 
-  /// Plain-Swift merging core — takes primitive arguments so it stays
-  /// clear of the Swift↔C++ interop boundary.
-  /// `makeItemRaw(urlString:headers:userAgent:)` below
+  /// The consumer's headers with `userAgent` folded in, which is the request
+  /// shape every outbound leg uses: asset loads, cache prefetches, and the
+  /// read-through server's origin requests.
+  @_spi(QueuePlayerTests)
+  public static func mergedHeaders(
+    headers: [String: String]?,
+    userAgent: String?
+  ) -> [String: String] {
+    var merged: [String: String] = headers ?? [:]
+    if let ua = userAgent, !ua.isEmpty {
+      merged["User-Agent"] = ua
+    }
+    return merged
+  }
+
+  /// Plain-Swift options-dictionary builder — takes primitive arguments so
+  /// it stays clear of the Swift↔C++ interop boundary.
+  /// `makeItemRaw(urlString:headers:userAgent:)`
   /// calls this, and `makeItem(for:, config:)` unpacks its `PlayerConfig`
   /// argument into the same primitive pair and calls `makeItemRaw`.
   ///
@@ -209,18 +242,20 @@ public enum AVQueueBuilder {
   ///
   /// Key spelling: `AVURLAssetHTTPHeaderFieldsKey` is not a public
   /// Swift API. The raw Obj-C string still works at runtime. See
-  /// NOTES.md §7. We do not implement an
-  /// `AVAssetResourceLoaderDelegate` replacement — see
-  /// `plan/blocked.md`.
+  /// NOTES.md §7.
+  ///
+  /// No `AVAssetResourceLoaderDelegate` is installed, and none will be: an
+  /// asset routed through a loader takes a custom URL scheme, and Apple states
+  /// AirPlay is unsupported for one. Remote tracks reach the lookahead cache
+  /// through a local HTTP server instead, which keeps AVFoundation's own HTTP
+  /// stack — including the redirect following a loader would have to
+  /// reimplement.
   @_spi(QueuePlayerTests)
   public static func httpOptionsRaw(
     headers: [String: String]?,
     userAgent: String?
   ) -> [String: Any] {
-    var merged: [String: String] = headers ?? [:]
-    if let ua = userAgent, !ua.isEmpty {
-      merged["User-Agent"] = ua
-    }
+    let merged = mergedHeaders(headers: headers, userAgent: userAgent)
     guard !merged.isEmpty else { return [:] }
     return ["AVURLAssetHTTPHeaderFieldsKey": merged]
   }

package/ios/ArtworkLoader.swift

@@ -127,10 +127,3 @@ final class ArtworkLoader {
   private var _configHeaders: [String: String]?
   private var _configUserAgent: String?
 }
-
-private extension NSLock {
-  func withLock<T>(_ body: () throws -> T) rethrows -> T {
-    lock(); defer { unlock() }
-    return try body()
-  }
-}

package/ios/ArtworkResolver.swift

@@ -53,11 +53,10 @@ final class ArtworkResolver {
   /// only one the consumer cares about. Threading: completion fires
   /// on main.
   func resolve(url: String?, completion: @escaping (UIImage) -> Void) {
-    self.currentSeq &+= 1
-    let seq = self.currentSeq
+    let seq = bumpSeq()
 
     loader.load(uri: url) { [weak self] image in
-      guard let self = self, self.currentSeq == seq else { return }
+      guard let self = self, self.isCurrent(seq) else { return }
       completion(image ?? PlaceholderArtwork.image)
     }
   }
@@ -68,7 +67,7 @@ final class ArtworkResolver {
   /// already in transit will populate the loader's cache for a
   /// future `resolve(...)` that hits the same URL.
   func cancelInFlight() {
-    currentSeq &+= 1
+    _ = bumpSeq()
   }
 
   /// Clear the underlying loader's cache + drop the in-flight
@@ -83,5 +82,24 @@ final class ArtworkResolver {
   /// Monotonic resolve-call counter. Captured into completion closures
   /// to drop responses for superseded requests, including same-URL
   /// re-resolves that the URL-string compare cannot distinguish.
+  /// Callers bump this on the queue that owns playback while the loader
+  /// reports completions on main, so the counter is the one piece of state
+  /// crossing between them and it carries its own lock.
+  private let seqLock = NSLock()
   private var currentSeq: UInt64 = 0
+
+  /// Advance the sequence and return the new value.
+  private func bumpSeq() -> UInt64 {
+    seqLock.lock()
+    defer { seqLock.unlock() }
+    currentSeq &+= 1
+    return currentSeq
+  }
+
+  /// Whether `seq` is still the newest request.
+  private func isCurrent(_ seq: UInt64) -> Bool {
+    seqLock.lock()
+    defer { seqLock.unlock() }
+    return currentSeq == seq
+  }
 }

package/ios/AssetReplayGainReader.swift

@@ -0,0 +1,118 @@
+import AVFoundation
+import Foundation
+
+/// Reads the four ReplayGain tags off an `AVAsset`'s own metadata,
+/// replacing the byte-prefix probe. AVFoundation surfaces the same
+/// tags under three different shapes depending on container:
+///
+/// - MP3 / ID3v2 `TXXX`: the name lives in the item's `extraAttributes`
+///   info key; the item's own key is the frame id (`TXXX`).
+/// - FLAC / Vorbis comment: the name *is* the item's key.
+/// - M4A / iTunes freeform: the item's key is the reverse-DNS
+///   identifier (`com.apple.iTunes.replaygain_track_gain`).
+///
+/// `tagName(info:key:)` is the pure reduction of those three shapes to
+/// one comparable name, extracted so it is testable without building
+/// an `AVMetadataItem`.
+enum AssetReplayGainReader {
+
+  /// The four names a derived tag name has to match to be worth
+  /// loading a value for. Everything else on the asset is skipped
+  /// before its `stringValue` is touched.
+  private static let replayGainNames: Set<String> = [
+    ReplayGainExtractor.trackGainKey,
+    ReplayGainExtractor.trackPeakKey,
+    ReplayGainExtractor.albumGainKey,
+    ReplayGainExtractor.albumPeakKey,
+  ]
+
+  /// Read ReplayGain from an item AVPlayer has already prepared.
+  ///
+  /// Returns `nil` unless `item.status == .readyToPlay`. That single
+  /// condition is the whole gate: on a prepared item `load(.metadata)`
+  /// costs zero requests and zero bytes, while interrogating an
+  /// unprepared asset downloads essentially the entire file (measured:
+  /// 2.889 MB of a 2.89 MB MP3, 3.776 MB of a 3.78 MB FLAC).
+  ///
+  /// Deliberately NOT gated on `asset.statusOfValue(forKey: "metadata")`:
+  /// without `"metadata"` in `automaticallyLoadedAssetKeys` that status
+  /// reads `.unknown` even at `.readyToPlay` (measured 8/8), so such a
+  /// guard would be permanently false. The key is not set because it
+  /// buys nothing — the prepared read is already free.
+  ///
+  /// Values go through `ReplayGainExtractor.rgDataFromTags`, the same
+  /// acceptance function every other ReplayGain entry point uses, so
+  /// the dB / peak rules cannot drift per source.
+  static func read(item: AVPlayerItem) async -> ReplayGainData? {
+    guard item.status == .readyToPlay else { return nil }
+    // `AVPlayerItem.asset` is a MainActor-isolated property under strict
+    // concurrency (`AVAsset` is not Sendable); `status` is explicitly
+    // nonisolated. Hop to main for the asset read, then work against the
+    // captured reference — same shape as `NowPlayingFormatExtractor.extract`.
+    let asset: AVAsset = await MainActor.run { item.asset }
+    // Opus applies `OpusHead.output_gain` in the decoder, so applying a
+    // `REPLAYGAIN_*` tag on top of it double-corrects (NOTES.md §25).
+    //
+    // The container is read from `sourceURL`, the media's own URL. A routed
+    // track's asset URL is the read-through server's, which carries no
+    // extension — asking it would fail this guard open on every Opus track.
+    let sourceURL = await MainActor.run { item.sourceURL }
+    if let source = sourceURL, let url = URL(string: source), isOpusContainer(url: url) {
+      return nil
+    }
+
+    let metadata: [AVMetadataItem]
+    do {
+      metadata = try await asset.load(.metadata)
+    } catch {
+      return nil
+    }
+
+    var tags: [String: String] = [:]
+    for entry in metadata {
+      // `try?` flattens here — both loaders already return an optional,
+      // so a load failure and an absent value arrive as the same `nil`.
+      let attributes = try? await entry.load(.extraAttributes)
+      let info = attributes?[.info] as? String
+      guard let name = tagName(info: info, key: entry.key as? String),
+            replayGainNames.contains(name) else { continue }
+      guard let value = try? await entry.load(.stringValue) else { continue }
+      tags[name] = value
+    }
+    return ReplayGainExtractor.rgDataFromTags(tags)
+  }
+
+  /// Derive the comparable tag name from a metadata item's info key
+  /// [info] and its own key [key]: [info] when it is non-blank, else
+  /// [key]; then the segment after the last `.`; then uppercased.
+  /// Returns `nil` when neither input yields a usable name.
+  static func tagName(info: String?, key: String?) -> String? {
+    let source: String
+    if let info = info, !info.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty {
+      source = info.trimmingCharacters(in: .whitespacesAndNewlines)
+    } else if let key = key, !key.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty {
+      source = key.trimmingCharacters(in: .whitespacesAndNewlines)
+    } else {
+      return nil
+    }
+    // Reverse-DNS freeform keys carry the tag name in their last
+    // segment; ID3 info fields and Vorbis keys carry no `.` at all and
+    // pass through whole.
+    let name: String
+    if let separator = source.lastIndex(of: ".") {
+      name = String(source[source.index(after: separator)...])
+    } else {
+      name = source
+    }
+    guard !name.isEmpty else { return nil }
+    return name.uppercased()
+  }
+
+  /// True when [url] names an Opus container. Opus carries its gain in
+  /// `OpusHead.output_gain`, which the decoder applies, so a
+  /// `REPLAYGAIN_*` tag found alongside it would be applied twice.
+  static func isOpusContainer(url: URL) -> Bool {
+    let ext = url.pathExtension.lowercased()
+    return ext == "opus" || ext == "ogg"
+  }
+}

package/ios/AudioSession.swift

@@ -9,7 +9,7 @@ import AVFoundation
 /// bus, and calls `activate` + `installObservers` during its own
 /// lifecycle.
 ///
-/// Interruption semantics (matches Apple's docs + RNTP behaviour):
+/// Interruption semantics (per Apple's AVAudioSession interruption docs):
 ///
 /// - `.began`: system is telling us to pause (incoming call, Siri,
 ///   FaceTime, alarm). Callers typically call `pause()` on the
@@ -54,21 +54,37 @@ final class AudioSession {
     case newDeviceAvailable
   }
 
-  /// Fires on AVAudioSession interruption notifications. Stored
-  /// on main thread (registration happens on main); invoked on
-  /// main (NotificationCenter body dispatches before calling).
-  var onInterruption: ((InterruptionKind) -> Void)?
+  /// The three callback slots are written by the owner on its player queue
+  /// (`configure()` / `destroy()`) and read on main by the notification
+  /// observers — and `onError` on the player queue as well — so each read and
+  /// write goes through one lock.
+  private let callbackLock = NSLock()
+  private var interruptionCallback: ((InterruptionKind) -> Void)?
+  private var routeChangeCallback: ((RouteChangeKind) -> Void)?
+  private var errorCallback: ((AudioSessionError) -> Void)?
+
+  /// Fires on AVAudioSession interruption notifications, on main.
+  var onInterruption: ((InterruptionKind) -> Void)? {
+    get { callbackLock.withLock { interruptionCallback } }
+    set { callbackLock.withLock { interruptionCallback = newValue } }
+  }
 
   /// Fires on AVAudioSession route-change notifications for the
-  /// subset of reasons the caller should react to.
-  var onRouteChange: ((RouteChangeKind) -> Void)?
+  /// subset of reasons the caller should react to, on main.
+  var onRouteChange: ((RouteChangeKind) -> Void)? {
+    get { callbackLock.withLock { routeChangeCallback } }
+    set { callbackLock.withLock { routeChangeCallback = newValue } }
+  }
 
   /// Fires when an AVAudioSession lifecycle call (`setCategory`,
   /// `setActive(true)`, `setActive(false)`) throws. Failure is
   /// non-fatal at the audio-session level — playback itself hasn't
   /// started yet, so the player state machine should not transition
-  /// to `.error` on these (do not call `emitState` from this hook).
-  var onError: ((AudioSessionError) -> Void)?
+  /// to `.error` on these (do not call `emitState` from this callback).
+  var onError: ((AudioSessionError) -> Void)? {
+    get { callbackLock.withLock { errorCallback } }
+    set { callbackLock.withLock { errorCallback = newValue } }
+  }
 
   private var interruptionObserver: NSObjectProtocol?
   private var routeChangeObserver: NSObjectProtocol?
@@ -99,20 +115,50 @@ final class AudioSession {
     mode: AVAudioSession.Mode = .default,
     options: AVAudioSession.CategoryOptions = []
   ) {
-    let session = AVAudioSession.sharedInstance()
+    guard configureCategory(mode: mode, options: options) else { return }
+    activateIfNeeded()
+  }
+
+  /// Apply the playback category without claiming the session. Returns whether
+  /// it succeeded, since activating after a failed category is pointless.
+  ///
+  /// Category and activation are separable on purpose: the category is what
+  /// route sharing and the interruption observers need, while activation is
+  /// what actually takes audio away from whatever else is playing. Doing both
+  /// at configure time silenced another app's audio the moment a consumer
+  /// launched, before the user had pressed anything.
+  @discardableResult
+  func configureCategory(
+    mode: AVAudioSession.Mode = .default,
+    options: AVAudioSession.CategoryOptions = []
+  ) -> Bool {
     do {
-      try session.setCategory(.playback, mode: mode, options: options)
+      try AVAudioSession.sharedInstance().setCategory(.playback, mode: mode, options: options)
+      return true
     } catch {
       let desc = String(describing: error)
       NSLog("[AudioSession] setCategory(.playback) failed: %@", desc)
       onError?(.setCategoryFailed(message: desc, nativeCode: (error as NSError).code))
-      // Early-return: if setCategory failed, setActive is highly
-      // likely to fail too — no value in chaining a second error
-      // for the same root cause.
-      return
+      // If setCategory failed, setActive is highly likely to fail too — no
+      // value in chaining a second error for the same root cause.
+      return false
     }
+  }
+
+  /// The system took the session for an interruption. A later
+  /// `activateIfNeeded` claims it again: the session is no longer ours
+  /// whatever this object recorded before the interruption.
+  func noteInterrupted() {
+    isActive = false
+  }
+
+  /// Claim the audio session. Idempotent: repeated calls after the first are
+  /// no-ops, so every playback entry point can call it without bookkeeping.
+  func activateIfNeeded() {
+    guard !isActive else { return }
     do {
-      try session.setActive(true)
+      try AVAudioSession.sharedInstance().setActive(true)
+      isActive = true
     } catch {
       let desc = String(describing: error)
       NSLog("[AudioSession] setActive(true) failed: %@", desc)
@@ -120,11 +166,16 @@ final class AudioSession {
     }
   }
 
+  /// Whether this object has claimed the session. Cleared on deactivate so a
+  /// later play re-claims it.
+  private var isActive = false
+
   /// Deactivate the session + notify other apps they can resume.
   /// Consumers call this during `destroy` so e.g. a paused music
   /// app or podcast player can auto-resume. Same error-logging
   /// rationale as `activate`.
   func deactivate() {
+    isActive = false
     do {
       try AVAudioSession.sharedInstance().setActive(
         false, options: [.notifyOthersOnDeactivation])