react-native-queue-player 1.1.2 → 2.0.0

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])