react-native-queue-player 1.2.0 → 2.0.0

package/ios/EQTap.swift

@@ -21,7 +21,7 @@ import MediaToolbox
 /// (e.g. ReplayGain pre-gain in front of the EQ cascade) may take
 /// short-held NSLock critical sections to read freshly-published
 /// coefficients; the project accepts that cost in exchange for
-/// cross-class consistency with the rest of the audio plumbing
+/// cross-class consistency with the rest of the audio path
 /// (`AudioTapProvider.gainsSnapshot`, `Visualizer.subsLock`).
 ///
 /// AVFoundation delivers samples as deinterleaved float32: each
@@ -53,12 +53,17 @@ final class EQTap {
   ) -> Void
 
   /// Optional render-thread prepare hook. Fired once per tap from
-  /// `MTAudioProcessingTapPrepareCallback` with the tap's
-  /// `maxFrames` budget so DSP closures can size scratch buffers
-  /// before the first process callback lands. Allocation here is
-  /// safe because prepare runs synchronously on tap setup, ahead
-  /// of the render-thread process loop.
-  typealias PrepareFn = (_ maxFrames: Int) -> Void
+  /// `MTAudioProcessingTapPrepareCallback` with the tap's `maxFrames`
+  /// budget and the format the tap will actually deliver, so DSP closures
+  /// can size scratch buffers and configure themselves before the first
+  /// process callback lands. Allocation here is safe because prepare runs
+  /// synchronously on tap setup, ahead of the render-thread process loop.
+  ///
+  /// The format is the tap's own processing format, which is what the DSP
+  /// sees — not the encoded source format the asset's track advertises.
+  typealias PrepareFn = (
+    _ maxFrames: Int, _ format: AudioStreamBasicDescription
+  ) -> Void
 
   /// Default pass-through process body. Copies input → output.
   static let passThrough: ProcessFn = { input, output, numberFrames, channels, _, _ in
@@ -87,11 +92,9 @@ final class EQTap {
     let asset = item.asset
     if isHLS(asset) { return nil }
 
-    var keyError: NSError?
-    let status = asset.statusOfValue(forKey: "tracks", error: &keyError)
-    guard status == .loaded else { return nil }
+    guard case .loaded(let tracks) = asset.status(of: .tracks) else { return nil }
 
-    guard let track = asset.tracks(withMediaType: .audio).first else {
+    guard let track = tracks.first(where: { $0.mediaType == .audio }) else {
       return nil
     }
 
@@ -186,14 +189,14 @@ private let tapFinalize: MTAudioProcessingTapFinalizeCallback = { tap in
 
 private let tapPrepare: MTAudioProcessingTapPrepareCallback = {
   tap, maxFrames, processingFormat in
-  // Forward the tap's per-render-batch frame budget to the holder's
-  // prepare hook so DSP closures size scratch buffers here, not on
-  // the process callback. The default pass-through closure has no
-  // prepare hook installed, so this is a no-op for non-DSP taps.
-  _ = processingFormat
+  // Forward the tap's per-render-batch frame budget and processing format
+  // to the holder's prepare hook so DSP closures size scratch buffers and
+  // configure their cascade here, not on the process callback. The default
+  // pass-through closure has no prepare hook installed, so this is a no-op
+  // for non-DSP taps.
   let storage = MTAudioProcessingTapGetStorage(tap)
   let holder = Unmanaged<ProcessHolder>.fromOpaque(storage).takeUnretainedValue()
-  holder.prepare?(maxFrames)
+  holder.prepare?(maxFrames, processingFormat.pointee)
 }
 
 private let tapUnprepare: MTAudioProcessingTapUnprepareCallback = { tap in

package/ios/Equalizer.swift

@@ -23,6 +23,7 @@ import NitroModules
 /// because the JS side already knows it just dropped the singleton.
 final class Equalizer: HybridEqualizerSpec {
 
+  private static let currentLock = NSLock()
   /// The most recently constructed Equalizer instance. The iOS
   /// playback engine reaches for this at attach time so it can
   /// wire the shared `AudioTapProvider` to the active player without
@@ -37,7 +38,6 @@ final class Equalizer: HybridEqualizerSpec {
   /// Hybrid when the JS-side `getEqualizer()` singleton drops),
   /// so the strong static doesn't cause a leak — JS reload zeroes
   /// it via the second-construction teardown path below.
-  private static let currentLock = NSLock()
   private static var _current: Equalizer?
   static var current: Equalizer? {
     get {

package/ios/FLACStreamInfo.swift

@@ -0,0 +1,65 @@
+import Foundation
+
+/// FLAC STREAMINFO header values relevant to bitrate computation.
+/// Reading these + the file's byte size gives an accurate average
+/// encoded bitrate without involving AVFoundation.
+///
+/// The only source of a **local** FLAC bitrate:
+/// `estimatedDataRate` reports 0 for FLAC and Core Audio's
+/// `AudioFileStream` probe does not model FLAC's variable-frame
+/// container, so `NowPlayingFormatExtractor.readLocalFLACBitrate`
+/// derives duration from STREAMINFO and divides the file size by it.
+struct FLACStreamInfo {
+  let sampleRate: Int      // Hz, 1..655350
+  let channelCount: Int    // 1..8
+  let bitsPerSample: Int   // 4..32
+  let totalSamples: Int64  // 0 = unknown
+
+  /// Parse a FLAC STREAMINFO block from a `fLaC`-prefixed buffer.
+  /// STREAMINFO is type 0 and is required by the FLAC spec to be the
+  /// FIRST metadata block. Returns nil when the buffer doesn't start
+  /// with the FLAC magic or the block layout is malformed.
+  ///
+  /// STREAMINFO body layout (34 bytes after the 4-byte block header):
+  /// - 16 bits: minBlockSize (samples)
+  /// - 16 bits: maxBlockSize
+  /// - 24 bits: minFrameSize (bytes)
+  /// - 24 bits: maxFrameSize
+  /// - 20 bits: sampleRate
+  /// -  3 bits: channels - 1
+  /// -  5 bits: bitsPerSample - 1
+  /// - 36 bits: totalSamples
+  /// - 128 bits: MD5
+  static func parse(_ data: Data) -> FLACStreamInfo? {
+    guard data.count >= 4 + 4 + 34 else { return nil }
+    guard data[0] == 0x66, data[1] == 0x4c,
+          data[2] == 0x61, data[3] == 0x43 else { return nil }
+    let blockType = data[4] & 0x7f
+    guard blockType == 0 else { return nil }
+    let blockSize = Int(data[5]) << 16 | Int(data[6]) << 8 | Int(data[7])
+    guard blockSize >= 34, data.count >= 8 + blockSize else { return nil }
+    // STREAMINFO body starts at offset 8.
+    // Bits 64..83 (offset 10, 11, 12 in the body — i.e. data offsets
+    // 18, 19, 20): sampleRate (20 bits, big-endian).
+    let b18 = UInt64(data[18])
+    let b19 = UInt64(data[19])
+    let b20 = UInt64(data[20])
+    let sampleRate = Int((b18 << 12) | (b19 << 4) | (b20 >> 4))
+    let channels = Int((data[20] >> 1) & 0x07) + 1
+    let bitsPerSample = Int(((data[20] & 0x01) << 4) | (data[21] >> 4)) + 1
+    // totalSamples — 36 bits starting at byte 21 bit 4.
+    let t21 = Int64(data[21] & 0x0f)
+    let t22 = Int64(data[22])
+    let t23 = Int64(data[23])
+    let t24 = Int64(data[24])
+    let t25 = Int64(data[25])
+    let totalSamples =
+      (t21 << 32) | (t22 << 24) | (t23 << 16) | (t24 << 8) | t25
+    return FLACStreamInfo(
+      sampleRate: sampleRate,
+      channelCount: channels,
+      bitsPerSample: bitsPerSample,
+      totalSamples: totalSamples
+    )
+  }
+}

package/ios/GaplessEngine.swift

@@ -20,9 +20,14 @@ import Foundation
 /// callbacks; on the iOS side the equivalent fan-out continues to
 /// run through `TrackPlayer`'s direct observer code.
 ///
-/// Threading: methods run on the main thread by convention.
-/// `AVQueuePlayer` itself is documented as main-thread-only for
-/// every mutator + most state queries.
+/// Threading: `TrackPlayer` calls every method on its `playerQueue`,
+/// the one serial queue that owns the player. This engine never fires
+/// its `delegate`; its events reach `TrackPlayer` through the KVO and
+/// NotificationCenter observers `TrackPlayer` installs on `player`
+/// (`installGaplessObservers` / `installEventObservers`), each of which
+/// hops onto `playerQueue` before touching state. Main-only frameworks
+/// (`MPNowPlayingInfoCenter`, CarPlay) are reached by `TrackPlayer`
+/// hopping to main with the payload already computed.
 final class GaplessEngine: PlaybackEngine {
 
   /// Underlying AVQueuePlayer. Internal to the lib so service-level
@@ -36,6 +41,13 @@ final class GaplessEngine: PlaybackEngine {
 
   private var mixProvider: AudioMixProvider?
   private var released = false
+  /// Whether the transport wants playback, independent of what the player is
+  /// doing. `AVQueuePlayer` does not drop its rate when it runs out of items,
+  /// so a drained player is indistinguishable from a playing one by rate
+  /// alone — and a rebuild that reads the rate would start the next queue
+  /// installed on it. Set by `play()`, cleared by `pause()`, `stop()`,
+  /// `release()` and every path that drains the queue.
+  private var wantsPlayback = false
 
   init() {
     let p = AVQueuePlayer()
@@ -46,29 +58,15 @@ final class GaplessEngine: PlaybackEngine {
 
   // MARK: - Lifecycle
 
-  func prepare(
-    items: [AVPlayerItem],
-    startIndex: Int,
-    startPositionSeconds: TimeInterval
-  ) async {
-    // Queue construction lives on `TrackPlayer.fullRebuildPlayerQueue`
-    // (see queue-mutation comment on `PlaybackEngine.swift`). The
-    // engine's `prepare` is reserved for when a future engine impl
-    // (e.g. a `CrossfadeEngine` standby preroll) needs an async
-    // hook; for the gapless engine the queue arrives via direct
-    // `engine.player.insert(...)` calls and `prepare` is a no-op.
-    _ = items
-    _ = startIndex
-    _ = startPositionSeconds
-  }
-
   func release() {
     if released { return }
     released = true
+    wantsPlayback = false
     // Releasing the queue empties the AVQueuePlayer's items; the
     // player itself is held by the strong `let player` until the
     // engine is deallocated, which TrackPlayer triggers when it
     // drops its engine reference.
+    AVQueueBuilder.cancelLoading(dropping: player.items())
     player.removeAllItems()
     mixProvider = nil
     // Detach the delegate so any in-flight event still on the run
@@ -95,11 +93,19 @@ final class GaplessEngine: PlaybackEngine {
     startIndex: Int,
     startPositionSeconds: TimeInterval
   ) {
-    let savedRate = player.rate
+    let shouldResume = wantsPlayback
+    // The outgoing items are discarded here; anything the incoming set reuses
+    // keeps its loads, since a cancelled asset never becomes playable.
+    AVQueueBuilder.cancelLoading(dropping: player.items(), keeping: items)
     player.removeAllItems()
     guard !items.isEmpty,
           startIndex >= 0,
           startIndex < items.count else {
+      // Nothing seated, so nothing is being played. Removing the items does
+      // not stop the player, and a leg left running would start whatever is
+      // installed next on contact.
+      wantsPlayback = false
+      player.pause()
       // Empty queue, out-of-range startIndex, or startIndex past
       // end: leave drained. Matches `TrackPlayer.fullRebuildPlayerQueue`
       // where bad index also drains via the same removeAllItems-then-guard
@@ -129,8 +135,8 @@ final class GaplessEngine: PlaybackEngine {
       }
     }
     let restoreRate: () -> Void = { [weak self] in
-      guard let player = self?.player, player.rate != savedRate else { return }
-      player.rate = savedRate
+      guard let self, shouldResume, self.player.rate != self.userSpeed else { return }
+      self.player.rate = self.userSpeed
     }
     if startPositionSeconds > 0, let head = player.currentItem {
       head.seek(
@@ -177,6 +183,12 @@ final class GaplessEngine: PlaybackEngine {
 
   /// Drain the queue. After this call `currentMediaItem == nil`.
   func removeAllItems() {
+    // Emptying the queue is not the same as stopping: `AVQueuePlayer` keeps
+    // its rate across `removeAllItems`, so without this the next item seated
+    // on the player would start on contact.
+    wantsPlayback = false
+    player.pause()
+    AVQueueBuilder.cancelLoading(dropping: player.items())
     player.removeAllItems()
   }
 
@@ -200,10 +212,18 @@ final class GaplessEngine: PlaybackEngine {
   /// (the intended rate), not `player.rate` (0 while paused).
   private var pitchCorrectionMode: PitchCorrectionMode = .voice
 
-  func play() { player.rate = userSpeed }
-  func pause() { player.pause() }
+  func play() {
+    wantsPlayback = true
+    player.rate = userSpeed
+  }
+
+  func pause() {
+    wantsPlayback = false
+    player.pause()
+  }
 
   func stop() {
+    wantsPlayback = false
     player.pause()
     if let item = player.currentItem {
       item.seek(to: .zero, completionHandler: nil)
@@ -353,6 +373,14 @@ final class GaplessEngine: PlaybackEngine {
     player.currentItem
   }
 
+  /// This engine has one leg and no fade to schedule.
+  var isFadePendingOrActive: Bool { false }
+
+  /// One leg, so whatever is current is the whole of what is attached.
+  var attachedQueueItemIds: [String] {
+    player.currentItem?.queueItemId.map { [$0] } ?? []
+  }
+
   var allMediaItems: [AVPlayerItem] {
     player.items()
   }
@@ -381,11 +409,10 @@ final class GaplessEngine: PlaybackEngine {
       if item.audioMix != nil { continue }
       item.audioMix = provider?.audioMix(for: item)
     }
-  }
-
-  // MARK: - Handoff
-
-  func handoff(to nextEngine: PlaybackEngine, atTrackBoundary: Bool) async {
-    preconditionFailure("PlaybackEngine.handoff is not implemented for the single-engine configuration")
+    // `audioMix(for:)` announces each item it is given as the active asset,
+    // so a walk leaves the last item refreshed standing as active. Re-assert
+    // the one that is playing, or consumers read the wrong asset — the
+    // visualizer's HLS check is answered from it.
+    provider?.noteActiveAsset(player.currentItem?.asset)
   }
 }

package/ios/InputGuards.swift

@@ -27,10 +27,7 @@ import Foundation
 /// project-empirical working pattern; both shapes are valid SPI
 /// per the Swift language spec, but the per-method form is what
 /// the rest of the codebase uses (see `AVQueueBuilder`,
-/// `QueueMutationArithmetic`). The `TransportStateTranslator`
-/// deferral note in `plan/backlog.md` documents a separate
-/// SPI-related compiler oddity that does NOT manifest with this
-/// shape.
+/// `QueueMutationArithmetic`).
 public enum InputGuards {
 
   /// Validate a `Double` that JS sends as a queue index. Returns
@@ -49,6 +46,18 @@ public enum InputGuards {
     return Int(value)
   }
 
+  /// Convert a `Double` insert position to the `Int` the queue arithmetic
+  /// clamps. `nil` for non-finite values (dropped: append). A finite value
+  /// past what `Int` holds is clamped to `count`, since every position past
+  /// the end means "append" anyway; `Int(value)` on such a value traps.
+  @_spi(QueuePlayerTests)
+  public static func insertPosition(_ value: Double?, count: Int) -> Int? {
+    guard let value, value.isFinite else { return nil }
+    if value < 0 { return 0 }
+    if value >= Double(count) { return count }
+    return Int(value)
+  }
+
   /// Validate a `Double` seek position (seconds). Returns `nil` for
   /// non-finite values; otherwise returns the value unchanged. The
   /// caller is responsible for clamping negative values to 0 and
@@ -58,6 +67,27 @@ public enum InputGuards {
   @_spi(QueuePlayerTests)
   public static func sanitisedSeekPosition(_ value: Double) -> Double? {
     guard value.isFinite else { return nil }
-    return value
+    // Finiteness alone is not enough: a finite 1e300 traps the same way
+    // `.infinity` does once it is scaled to milliseconds and converted to
+    // `Int64`. The bound is far past any real media duration, so clamping to
+    // it never changes a seek a consumer could observe.
+    return max(-maxSeekSeconds, min(maxSeekSeconds, value))
+  }
+
+  private static let maxSeekSeconds: Double = 1e12
+
+  /// Validate a `Double` lookahead count. Returns a non-negative `Int`,
+  /// clamped in `Double` space so an enormous or infinite consumer value
+  /// cannot trap the conversion. The prefetcher bounds its own window by the
+  /// queue length, so the upper clamp loses nothing observable.
+  ///
+  /// `.infinity` clamps to the bound rather than falling back to zero — it
+  /// asks for as much lookahead as possible, and answering "none" would invert
+  /// the request. Only `NaN`, which asks for nothing intelligible, reads as
+  /// zero; comparison against it is always false, so it cannot be clamped.
+  @_spi(QueuePlayerTests)
+  public static func validLookaheadCount(_ value: Double) -> Int {
+    guard !value.isNaN else { return 0 }
+    return Int(max(0, min(value, 10_000)))
   }
 }