react-native-queue-player 1.0.0

package/ios/RemoteCommands.swift

@@ -0,0 +1,229 @@
+import Foundation
+import MediaPlayer
+
+/// Owns the `MPRemoteCommandCenter.shared()` handler registrations
+/// that drive lock-screen / control-center / CarPlay / external-
+/// keyboard transport. Each handler dispatches into the owner's
+/// `onCommand` closure, where `TrackPlayer` stamps
+/// `pendingStateChangeReason = .system` and routes through the
+/// existing public transport methods.
+///
+/// Threading: every public method MUST be called on the main thread.
+/// Handlers registered with `addTarget` fire on main per Apple's docs.
+final class RemoteCommands {
+
+  enum Command {
+    case play
+    case pause
+    case togglePlayPause
+    case stop
+    case nextTrack
+    case previousTrack
+    case skipForward(seconds: Double)
+    case skipBackward(seconds: Double)
+    case changePlaybackPosition(seconds: Double)
+  }
+
+  /// Set by the owner during `configure()`; cleared during `destroy()`.
+  /// Invoked synchronously on main from the handler. Owner is
+  /// responsible for stamping the state-change reason BEFORE routing
+  /// into transport calls.
+  var onCommand: ((Command) -> Void)?
+
+  /// Drive `MPRemoteCommandCenter` `isEnabled` for the skip commands.
+  /// Greys out the lock-screen / CarPlay buttons that would no-op
+  /// (e.g. previous at queue head with `repeatMode: 'off'`). No-op
+  /// when not installed — the lib must not write to the shared
+  /// command center after `uninstall()` has released ownership.
+  func setSkipCapability(canSkipNext: Bool, canSkipPrevious: Bool) {
+    // Only greys out the next/previous-TRACK buttons. In `.interval` mode the
+    // lock-screen shows skip-forward/back, which always work (seek within the
+    // current track), so queue-boundary capability doesn't apply.
+    guard installed, skipMode == .track else { return }
+    let center = MPRemoteCommandCenter.shared()
+    center.nextTrackCommand.isEnabled = canSkipNext
+    center.previousTrackCommand.isEnabled = canSkipPrevious
+  }
+
+  /// Choose track-skip vs interval-skip for the lock-screen / control-center
+  /// skip slots, and set the jump intervals (seconds). The two modes are
+  /// mutually exclusive: `.track` enables next/previous-track, `.interval`
+  /// enables skip-forward/back by the configured seconds. Re-applies live so a
+  /// consumer can toggle at runtime. The lib only owns the skip-interval
+  /// commands while in `.interval` mode.
+  func setRemoteControls(mode: RemoteSkipMode, forwardInterval: Double, backwardInterval: Double) {
+    self.skipMode = mode
+    self.forwardInterval = forwardInterval
+    self.backwardInterval = backwardInterval
+    guard installed else { return }
+    applySkipMode()
+  }
+
+  /// Reconcile the shared command center with `skipMode` + intervals. Called
+  /// from `install()` and `setRemoteControls`.
+  private func applySkipMode() {
+    let center = MPRemoteCommandCenter.shared()
+    switch skipMode {
+    case .interval:
+      center.skipForwardCommand.preferredIntervals = [NSNumber(value: forwardInterval)]
+      center.skipBackwardCommand.preferredIntervals = [NSNumber(value: backwardInterval)]
+      if skipForwardTarget == nil {
+        skipForwardTarget = center.skipForwardCommand.addTarget { [weak self] event in
+          guard let self = self,
+                let event = event as? MPSkipIntervalCommandEvent else { return .commandFailed }
+          self.dispatch(.skipForward(seconds: event.interval))
+          return .success
+        }
+      }
+      if skipBackwardTarget == nil {
+        skipBackwardTarget = center.skipBackwardCommand.addTarget { [weak self] event in
+          guard let self = self,
+                let event = event as? MPSkipIntervalCommandEvent else { return .commandFailed }
+          self.dispatch(.skipBackward(seconds: event.interval))
+          return .success
+        }
+      }
+      center.skipForwardCommand.isEnabled = true
+      center.skipBackwardCommand.isEnabled = true
+      center.nextTrackCommand.isEnabled = false
+      center.previousTrackCommand.isEnabled = false
+    case .track:
+      // Release the skip-interval commands (only if we owned them) and restore
+      // next/previous-track. Actual grey-out follows via `setSkipCapability`.
+      releaseSkipCommands(center)
+      center.nextTrackCommand.isEnabled = true
+      center.previousTrackCommand.isEnabled = true
+    }
+  }
+
+  /// Remove our skip-interval targets and disable those commands — but only the
+  /// ones we registered, so a co-resident audio framework's handlers are left
+  /// untouched (politeness matches the next/prev-only default).
+  private func releaseSkipCommands(_ center: MPRemoteCommandCenter) {
+    if let t = skipForwardTarget {
+      center.skipForwardCommand.removeTarget(t)
+      center.skipForwardCommand.isEnabled = false
+      skipForwardTarget = nil
+    }
+    if let t = skipBackwardTarget {
+      center.skipBackwardCommand.removeTarget(t)
+      center.skipBackwardCommand.isEnabled = false
+      skipBackwardTarget = nil
+    }
+  }
+
+  /// Register handlers + enable the supported commands. Idempotent.
+  func install() {
+    guard !installed else { return }
+    installed = true
+    let center = MPRemoteCommandCenter.shared()
+
+    playTarget = center.playCommand.addTarget { [weak self] _ in
+      guard let self = self else { return .commandFailed }
+      self.dispatch(.play)
+      return .success
+    }
+    pauseTarget = center.pauseCommand.addTarget { [weak self] _ in
+      guard let self = self else { return .commandFailed }
+      self.dispatch(.pause)
+      return .success
+    }
+    togglePlayPauseTarget = center.togglePlayPauseCommand.addTarget { [weak self] _ in
+      guard let self = self else { return .commandFailed }
+      self.dispatch(.togglePlayPause)
+      return .success
+    }
+    stopTarget = center.stopCommand.addTarget { [weak self] _ in
+      guard let self = self else { return .commandFailed }
+      self.dispatch(.stop)
+      return .success
+    }
+    nextTrackTarget = center.nextTrackCommand.addTarget { [weak self] _ in
+      guard let self = self else { return .commandFailed }
+      self.dispatch(.nextTrack)
+      return .success
+    }
+    previousTrackTarget = center.previousTrackCommand.addTarget { [weak self] _ in
+      guard let self = self else { return .commandFailed }
+      self.dispatch(.previousTrack)
+      return .success
+    }
+    changePlaybackPositionTarget =
+      center.changePlaybackPositionCommand.addTarget { [weak self] event in
+        guard let self = self else { return .commandFailed }
+        guard let event = event as? MPChangePlaybackPositionCommandEvent else {
+          return .commandFailed
+        }
+        self.dispatch(.changePlaybackPosition(seconds: event.positionTime))
+        return .success
+      }
+
+    center.playCommand.isEnabled = true
+    center.pauseCommand.isEnabled = true
+    center.togglePlayPauseCommand.isEnabled = true
+    center.stopCommand.isEnabled = true
+    center.changePlaybackPositionCommand.isEnabled = true
+
+    // Reconcile the skip slots to the current mode. `.track` (default) enables
+    // next/previous-track and leaves skipForward/skipBackward untouched;
+    // `.interval` owns + enables skipForward/skipBackward and disables next/prev.
+    applySkipMode()
+  }
+
+  /// Tear down handler registrations + disable the commands the lib
+  /// owns. Idempotent. Never touches commands the lib didn't enable
+  /// in `install()`.
+  func uninstall() {
+    guard installed else { return }
+    installed = false
+    let center = MPRemoteCommandCenter.shared()
+
+    if let t = playTarget { center.playCommand.removeTarget(t) }
+    if let t = pauseTarget { center.pauseCommand.removeTarget(t) }
+    if let t = togglePlayPauseTarget { center.togglePlayPauseCommand.removeTarget(t) }
+    if let t = stopTarget { center.stopCommand.removeTarget(t) }
+    if let t = nextTrackTarget { center.nextTrackCommand.removeTarget(t) }
+    if let t = previousTrackTarget { center.previousTrackCommand.removeTarget(t) }
+    if let t = changePlaybackPositionTarget {
+      center.changePlaybackPositionCommand.removeTarget(t)
+    }
+    releaseSkipCommands(center)
+    playTarget = nil
+    pauseTarget = nil
+    togglePlayPauseTarget = nil
+    stopTarget = nil
+    nextTrackTarget = nil
+    previousTrackTarget = nil
+    changePlaybackPositionTarget = nil
+
+    center.playCommand.isEnabled = false
+    center.pauseCommand.isEnabled = false
+    center.togglePlayPauseCommand.isEnabled = false
+    center.stopCommand.isEnabled = false
+    center.nextTrackCommand.isEnabled = false
+    center.previousTrackCommand.isEnabled = false
+    center.changePlaybackPositionCommand.isEnabled = false
+  }
+
+  private func dispatch(_ command: Command) {
+    assert(Thread.isMainThread,
+           "RemoteCommands.dispatch must run on the main thread — " +
+           "MPRemoteCommandCenter handlers are documented as main-queue.")
+    onCommand?(command)
+  }
+
+  private var installed = false
+  private var playTarget: Any?
+  private var pauseTarget: Any?
+  private var togglePlayPauseTarget: Any?
+  private var stopTarget: Any?
+  private var nextTrackTarget: Any?
+  private var previousTrackTarget: Any?
+  private var changePlaybackPositionTarget: Any?
+  private var skipForwardTarget: Any?
+  private var skipBackwardTarget: Any?
+
+  private var skipMode: RemoteSkipMode = .track
+  private var forwardInterval: Double = 15
+  private var backwardInterval: Double = 15
+}

package/ios/ReplayGainData.swift

@@ -0,0 +1,58 @@
+import Foundation
+
+/// Pure-Swift mirror of the Nitrogen-generated `ReplayGainMode`.
+/// Keeps the selector + processor off the Swift↔C++ interop graph
+/// so they compile as a clean Swift module. The Hybrid layer in
+/// `TrackPlayer.swift` maps `ReplayGainMode` ↔ this enum at the
+/// API boundary.
+enum ReplayGainSelectorMode: Equatable {
+  case off
+  case track
+  case album
+}
+
+/// Parsed ReplayGain tag values for a single track. All four fields
+/// are independent — a track may carry only track tags, only album
+/// tags, or both. The Opus container guard returns nil from
+/// `ReplayGainExtractor.extract(...)` rather than producing a
+/// ReplayGainData with one nil pair.
+///
+/// Strict mode (`.album` requires album tag, `.track` requires
+/// track tag) means there is no fallback — see `selectGain(mode:)`.
+struct ReplayGainData: Equatable {
+  /// `REPLAYGAIN_TRACK_GAIN` parsed value in dB. `nil` when the tag
+  /// was absent or rejected by the parser. `Double` to match the
+  /// JS-surface `number | null` type; convert to `Float` at the
+  /// audio-stage boundary (vDSP / DSP processors operate on Float).
+  let trackGainDb: Double?
+  /// `REPLAYGAIN_TRACK_PEAK` parsed linear value. `nil` when absent
+  /// or rejected (see encoder-default detection — peak `1.000000`
+  /// or `< 0.001` is treated as no-peak).
+  let trackPeak: Double?
+  /// `REPLAYGAIN_ALBUM_GAIN` parsed value in dB. `nil` when absent.
+  let albumGainDb: Double?
+  /// `REPLAYGAIN_ALBUM_PEAK` parsed linear value. `nil` when absent.
+  let albumPeak: Double?
+
+  /// Strict mode-aware selector. See NOTES.md §25.
+  ///
+  /// - `.off`: returns `(nil, nil)` (no-op).
+  /// - `.track`: returns `(trackGainDb, trackPeak)` — both may be nil.
+  /// - `.album`: returns `(albumGainDb, albumPeak)` — both may be nil.
+  ///   No fallback to track gain when album is absent.
+  ///
+  /// Caller computes `linearGain = pow(10, gainDb! / 20)` and clip-
+  /// caps via peak when both are non-nil. When `gainDb` is nil the
+  /// caller treats RG as inactive for this track (linearGain = 1.0,
+  /// `replayGainActive = false`).
+  func selectGain(mode: ReplayGainSelectorMode) -> (gainDb: Double?, peak: Double?) {
+    switch mode {
+    case .off:
+      return (nil, nil)
+    case .track:
+      return (trackGainDb, trackPeak)
+    case .album:
+      return (albumGainDb, albumPeak)
+    }
+  }
+}

package/ios/ReplayGainExtractor.swift

@@ -0,0 +1,82 @@
+import Foundation
+
+/// Read the four ReplayGain tags from a media URL via direct byte
+/// parsing (`MetadataReader`) and parse the raw string values into
+/// `ReplayGainData`.
+///
+/// Tag-format coverage matches `MetadataReader`:
+/// - MP3 ID3v2.2 / 2.3 / 2.4 TXXX (user-defined text) frames
+/// - FLAC Vorbis comments
+/// - MP4 / M4A iTunes-style freeform `----` atoms
+/// - Opus containers return `nil` (decoder-applied gain would
+///   double-correct under tag-applied RG)
+///
+/// Parser tolerance follows NOTES.md §25 — `" dB"` suffix optional,
+/// `+/-` prefix optional, U+2212 minus sign normalised, period
+/// decimal, whitespace tolerant, NaN/Inf rejected. Description
+/// match is case-insensitive.
+enum ReplayGainExtractor {
+
+  // Tag descriptions matched (case-insensitive).
+  static let trackGainKey = "REPLAYGAIN_TRACK_GAIN"
+  static let trackPeakKey = "REPLAYGAIN_TRACK_PEAK"
+  static let albumGainKey = "REPLAYGAIN_ALBUM_GAIN"
+  static let albumPeakKey = "REPLAYGAIN_ALBUM_PEAK"
+
+  /// Read the four ReplayGain tags from `url`. Returns `nil` if no
+  /// RG tag was found or the source can't be read. Sub-100 ms for
+  /// local files; ~50-300 ms for `http(s)://` (network-dependent).
+  static func extract(from url: URL) async -> ReplayGainData? {
+    return await MetadataReader.readReplayGainTags(url: url)
+  }
+
+  // MARK: - Gain parsing
+
+  /// Parse a `REPLAYGAIN_*_GAIN` string (e.g. `"-6.54 dB"`,
+  /// `"+3.21"`, `"−1.0 dB"` with U+2212 minus) into a Double dB.
+  /// Returns `nil` for unparseable / NaN / Inf inputs.
+  static func parseGainDb(_ rawInput: String) -> Double? {
+    var trimmed = rawInput.trimmingCharacters(in: .whitespacesAndNewlines)
+    guard !trimmed.isEmpty else { return nil }
+
+    // Normalise U+2212 MINUS SIGN (\u{2212}) → ASCII '-'.
+    trimmed = trimmed.replacingOccurrences(of: "\u{2212}", with: "-")
+
+    // Strip case-insensitive trailing "dB" + any whitespace separator.
+    let lower = trimmed.lowercased()
+    if lower.hasSuffix("db") {
+      let endIdx = trimmed.index(trimmed.endIndex, offsetBy: -2)
+      trimmed = String(trimmed[..<endIdx]).trimmingCharacters(in: .whitespacesAndNewlines)
+    }
+    guard !trimmed.isEmpty else { return nil }
+
+    // Collapse extra-internal whitespace per NOTES.md §25 — some
+    // taggers emit `"- 6.54"` (sign-digit) or `"-6 .54"` (digit-
+    // decimal). `Double` rejects both; collapsing makes them parse.
+    trimmed = trimmed.unicodeScalars
+      .filter { !CharacterSet.whitespaces.contains($0) }
+      .map { String($0) }
+      .joined()
+
+    // Reject comma decimals (RG2 spec — period only).
+    if trimmed.contains(",") { return nil }
+
+    guard let value = Double(trimmed) else { return nil }
+    if !value.isFinite { return nil }
+    return value
+  }
+
+  /// Parse a `REPLAYGAIN_*_PEAK` string (linear, period decimal).
+  /// Returns `nil` for unparseable / NaN / Inf / out-of-range
+  /// values, or for the encoder-default sentinels (peak `< 0.001`
+  /// or peak exactly `1.0`, both signal the analyser didn't run).
+  static func parsePeak(_ rawInput: String) -> Double? {
+    let trimmed = rawInput.trimmingCharacters(in: .whitespacesAndNewlines)
+    guard let value = Double(trimmed) else { return nil }
+    if !value.isFinite { return nil }
+    if value > 2.0 { return nil }
+    if value < 0.001 { return nil }
+    if value == 1.0 { return nil }
+    return value
+  }
+}

package/ios/ReplayGainProcessor.swift

@@ -0,0 +1,46 @@
+import Accelerate
+import Foundation
+
+/// Standalone audio processor that applies a linear gain to a
+/// Float32 buffer in place. No knowledge of EQ, the audio tap, or
+/// `ReplayGainData` — purely "given a Float buffer, multiply by my
+/// gain". Composition lives at the call-site (`EQTap` invokes
+/// `replayGainProcessor.process(...)` before the EQ stage).
+///
+/// Threading: `setLinearGain` may be called from any thread (typically
+/// the JS bridge / main queue). `process` runs on the audio render
+/// thread. The internal `NSLock` serialises the set + read so the
+/// render thread always observes a consistent gain value. Matches the
+/// project-wide convention (see `AudioTapProvider.gainsSnapshot`,
+/// `Visualizer.subsLock`) — short critical sections on render are
+/// accepted as the trade for cross-class consistency over a lock-free
+/// atomic. Steady state at unity gain hits an early-return after the
+/// lock-protected read.
+final class ReplayGainProcessor {
+
+  private let lock = NSLock()
+  private var linearGain: Float = 1.0
+
+  /// Update the gain. Thread-safe.
+  func setLinearGain(_ value: Float) {
+    lock.lock()
+    linearGain = value
+    lock.unlock()
+  }
+
+  /// Multiply `frames` Float32 samples in `buffer` by the current
+  /// gain in place. Steady-state cost when the gain is unity is one
+  /// short lock-protected read plus one Float compare. The
+  /// `gain == 1.0` bit-exact check is the unity-skip — both the
+  /// reset path (`setLinearGain(1.0)`) and a 0 dB tag (RG2
+  /// `pow(10, 0/20) = 1.0`) hit it; both cases mean "no correction
+  /// to apply", so the early-return is correct in both.
+  func process(buffer: UnsafeMutablePointer<Float>, frames: Int) {
+    lock.lock()
+    var gain = linearGain
+    lock.unlock()
+
+    guard gain != 1.0 else { return }
+    vDSP_vsmul(buffer, 1, &gain, buffer, 1, vDSP_Length(frames))
+  }
+}

package/ios/Siri/PendingIntentBuffer.swift

@@ -0,0 +1,100 @@
+import Foundation
+
+/// Single-slot buffer for an intent that arrived before the JS-side
+/// resolver had registered. Holds at most one request per instance;
+/// a subsequent `push` replaces any prior entry (latest-wins).
+///
+/// Entries carry a `bufferedAt` timestamp and expire after `ttl`
+/// seconds. Expired entries are dropped on the next `peek` / `drain`
+/// without producing a result, so a stale cold-launch intent never
+/// reaches a JS resolver that registers minutes later.
+///
+/// `CarPlayBridge` holds one instance for `INPlayMediaIntent`
+/// cold-start dispatches. The primitive is generic over `Request` so
+/// future SiriKit intent paths can reuse it without duplication.
+/// `push` rather than `enqueue` because the buffer is single-slot —
+/// the sibling `PendingBrowseRequests` uses set semantics, this one
+/// does not.
+///
+/// Thread-safety: all mutating operations are guarded by an
+/// `NSLock`, so the buffer is safe to share across any thread the
+/// caller chooses.
+///
+/// Clock contract: callers must supply a monotonically non-decreasing
+/// clock. Negative-skew elapsed values are clamped to zero so a
+/// backwards-moving clock can't extend an entry's effective TTL.
+public final class PendingIntentBuffer<Request: Sendable>: @unchecked Sendable {
+
+  private struct Entry {
+    let request: Request
+    let bufferedAt: Date
+  }
+
+  private let lock = NSLock()
+  private var entry: Entry?
+  private let ttl: TimeInterval
+  private let clock: @Sendable () -> Date
+
+  public init(ttl: TimeInterval = 20, clock: @escaping @Sendable () -> Date = { Date() }) {
+    self.ttl = ttl
+    self.clock = clock
+  }
+
+  /// Store `request`, replacing any prior entry. The new entry's
+  /// `bufferedAt` is read from the injected clock.
+  public func push(_ request: Request) {
+    lock.lock()
+    defer { lock.unlock() }
+    entry = Entry(request: request, bufferedAt: clock())
+  }
+
+  /// Remove and return the buffered request, or nil if empty or
+  /// expired. Drains the slot in both cases — an expired entry is
+  /// not retained for a later non-expired read.
+  public func drain() -> Request? {
+    lock.lock()
+    defer { lock.unlock() }
+    guard let current = entry else { return nil }
+    entry = nil
+    let elapsed = max(0, clock().timeIntervalSince(current.bufferedAt))
+    if elapsed > ttl { return nil }
+    return current.request
+  }
+
+  /// Inspect the buffered request without removing it. Auto-clears
+  /// an expired entry as a side effect so a stale request can't be
+  /// inspected indefinitely.
+  public func peek() -> Request? {
+    lock.lock()
+    defer { lock.unlock() }
+    guard let current = entry else { return nil }
+    let elapsed = max(0, clock().timeIntervalSince(current.bufferedAt))
+    if elapsed > ttl {
+      entry = nil
+      return nil
+    }
+    return current.request
+  }
+
+  /// Drop any buffered request without returning it. Used when a
+  /// caller wants to clear the slot unconditionally (e.g. teardown).
+  public func clear() {
+    lock.lock()
+    defer { lock.unlock() }
+    entry = nil
+  }
+
+  /// True when the slot is empty (or holds only an expired entry).
+  /// Side effect: clears an expired entry, matching `peek`.
+  public var isEmpty: Bool {
+    lock.lock()
+    defer { lock.unlock() }
+    guard let current = entry else { return true }
+    let elapsed = max(0, clock().timeIntervalSince(current.bufferedAt))
+    if elapsed > ttl {
+      entry = nil
+      return true
+    }
+    return false
+  }
+}