react-native-queue-player 1.0.0

package/ios/GaplessEngine.swift

@@ -0,0 +1,385 @@
+import AVFoundation
+import Foundation
+
+/// Single-`AVQueuePlayer` engine — native gapless via AVFoundation
+/// item chaining + the audio session route.
+///
+/// Owns the underlying `AVQueuePlayer` and exposes it as a typed
+/// property for service-level wiring (`AVAudioSession` activation,
+/// `MPNowPlayingInfoCenter` integration, `MPRemoteCommandCenter`
+/// installation) which `TrackPlayer` performs at configure time.
+/// The engine itself is a thin wrapper that forwards every
+/// `PlaybackEngine` method onto the underlying player and exposes
+/// the player's state as protocol properties.
+///
+/// `TrackPlayer` installs its observer wiring on `engine.player`
+/// directly — `installGaplessObservers` and `installEventObservers`
+/// continue to attach KVO + NotificationCenter handlers to the
+/// underlying player. The engine's `delegate` slot is reserved for
+/// the routing surface that fans Media3-flavored `PlaybackEngineDelegate`
+/// 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.
+final class GaplessEngine: PlaybackEngine {
+
+  /// Underlying AVQueuePlayer. Internal to the lib so service-level
+  /// wiring (audio session, NowPlaying, RemoteCommands, KVO) can
+  /// continue to access the player directly during the multi-step
+  /// extraction. Pure engine-aware consumers must use the abstract
+  /// `PlaybackEngine` surface.
+  let player: AVQueuePlayer
+
+  weak var delegate: PlaybackEngineDelegate?
+
+  private var mixProvider: AudioMixProvider?
+  private var released = false
+
+  init() {
+    let p = AVQueuePlayer()
+    p.automaticallyWaitsToMinimizeStalling = true
+    p.actionAtItemEnd = .advance
+    self.player = p
+  }
+
+  // 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
+    // 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.
+    player.removeAllItems()
+    mixProvider = nil
+    // Detach the delegate so any in-flight event still on the run
+    // loop doesn't reach a TrackPlayer that has just released its
+    // engine.
+    delegate = nil
+  }
+
+  // MARK: - Queue mutation
+
+  /// Drain the queue and re-install the slice of [items] from
+  /// [startIndex] onward. Captures + restores the player rate
+  /// around the rebuild so a `playing → setItems → still-playing`
+  /// sequence survives `removeAllItems()` + the re-insert loop.
+  /// Apple's docs do not formally guarantee rate preservation on
+  /// `removeAllItems()`; capture + restore is defense in depth.
+  ///
+  /// Order: when [startPositionSeconds] > 0 the rate restore is
+  /// queued inside the seek completion handler so the seek lands
+  /// before playback resumes — otherwise a brief tick from
+  /// position 0 leaks before the seek catches up.
+  func setItems(
+    _ items: [AVPlayerItem],
+    startIndex: Int,
+    startPositionSeconds: TimeInterval
+  ) {
+    let savedRate = player.rate
+    player.removeAllItems()
+    guard !items.isEmpty,
+          startIndex >= 0,
+          startIndex < items.count else {
+      // 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
+      // shape.
+      return
+    }
+    let slice = Array(items[startIndex ..< items.count])
+    var cursor: AVPlayerItem? = nil
+    for item in slice {
+      if player.canInsert(item, after: cursor) {
+        // Per-item audioMix install before enqueue. AVPlayerItem
+        // honours `audioMix` only at item-enqueue time (Apple
+        // contract: changes after the item starts rendering are
+        // silently dropped — the property updates but the new
+        // `MTAudioProcessingTap`'s init/prepare/process callbacks
+        // never fire). Setting before `player.insert(...)` ensures
+        // every full-queue rebuild (skipToPrevious / skipToIndex /
+        // setQueue) lands a tap-bearing mix on the new currentItem.
+        // For streaming items whose `tracks` key has not yet
+        // loaded, the provider returns nil and the mix is applied
+        // by `engineActiveItemFormatChanged → refreshActiveItemMixes`
+        // once tracks publish.
+        item.audioMix = mixProvider?.audioMix(for: item)
+        applyPitchAlgorithm(to: item)
+        player.insert(item, after: cursor)
+        cursor = item
+      }
+    }
+    let restoreRate: () -> Void = { [weak self] in
+      guard let player = self?.player, player.rate != savedRate else { return }
+      player.rate = savedRate
+    }
+    if startPositionSeconds > 0, let head = player.currentItem {
+      head.seek(
+        to: CMTime(seconds: startPositionSeconds, preferredTimescale: 600),
+        completionHandler: { _ in restoreRate() }
+      )
+    } else {
+      restoreRate()
+    }
+  }
+
+  /// Surgical insert into the live `AVQueuePlayer`. Iterates
+  /// [items] calling `canInsert` + `insert(_:after:)`; returns
+  /// `false` on the first `canInsert` rejection so the caller
+  /// can fall back to a full rebuild via `setItems`.
+  @discardableResult
+  func insertItems(
+    _ items: [AVPlayerItem],
+    after: AVPlayerItem?
+  ) -> Bool {
+    var cursor: AVPlayerItem? = after
+    for item in items {
+      if player.canInsert(item, after: cursor) {
+        // Per-item audioMix install before enqueue — see `setItems`
+        // for the rationale.
+        item.audioMix = mixProvider?.audioMix(for: item)
+        applyPitchAlgorithm(to: item)
+        player.insert(item, after: cursor)
+        cursor = item
+      } else {
+        return false
+      }
+    }
+    return true
+  }
+
+  /// Remove [item] from the live queue. Removing the current item
+  /// causes `AVQueuePlayer` to auto-advance to the next queued
+  /// item — caller is responsible for keeping its lib-side
+  /// `currentTrackIndex` aligned.
+  func remove(_ item: AVPlayerItem) {
+    player.remove(item)
+  }
+
+  /// Drain the queue. After this call `currentMediaItem == nil`.
+  func removeAllItems() {
+    player.removeAllItems()
+  }
+
+  /// Mirror of `AVQueuePlayer.canInsert`. `nil` [after] checks
+  /// whether the item can be inserted at the head.
+  func canInsert(_ item: AVPlayerItem, after: AVPlayerItem?) -> Bool {
+    player.canInsert(item, after: after)
+  }
+
+  // MARK: - Transport
+
+  /// Persisted playback speed so `play()` resumes at the user's rate.
+  /// `AVPlayer.play()` resets rate to 1.0 (defaultRate), so a
+  /// set-speed → pause → resume would otherwise drop back to 1.0×.
+  private var userSpeed: Float = 1.0
+
+  /// Persisted pitch-correction mode. Stamped on each item as
+  /// `audioTimePitchAlgorithm` (per-item; AVQueuePlayer has no
+  /// player-level equivalent) at enqueue and re-applied on mode /
+  /// speed change. The resolved algorithm depends on `userSpeed`
+  /// (the intended rate), not `player.rate` (0 while paused).
+  private var pitchCorrectionMode: PitchCorrectionMode = .voice
+
+  func play() { player.rate = userSpeed }
+  func pause() { player.pause() }
+
+  func stop() {
+    player.pause()
+    if let item = player.currentItem {
+      item.seek(to: .zero, completionHandler: nil)
+    }
+  }
+
+  /// Seek to [index] / [position]. AVQueuePlayer is forward-only —
+  /// the engine walks the head forward by `advanceToNextItem` until
+  /// the target is the current item. Backward seek (target index
+  /// before `currentMediaItemIndex`) is the caller's
+  /// responsibility: the canonical queue model lives on
+  /// `TrackPlayer`, which rebuilds the AVQueuePlayer queue via
+  /// `setItems` before invoking seek for backward navigation. The
+  /// engine pauses around the multi-step walk to suppress the
+  /// transient audio that each `advanceToNextItem` would otherwise
+  /// produce on the new head.
+  func seek(toIndex index: Int, position: TimeInterval) {
+    let queueItems = player.items()
+    guard index >= 0, index < queueItems.count else { return }
+    let target = queueItems[index]
+    if player.currentItem === target {
+      target.seek(to: CMTime(seconds: position, preferredTimescale: 600), completionHandler: nil)
+      return
+    }
+    // Multi-step forward walk: pause first to suppress the
+    // intermediate audio, then advance, then restore the rate.
+    let savedRate = player.rate
+    if savedRate > 0 { player.pause() }
+    var safety = queueItems.count
+    while let head = player.currentItem, head !== target, safety > 0 {
+      player.advanceToNextItem()
+      safety -= 1
+    }
+    if let now = player.currentItem, now === target {
+      now.seek(to: CMTime(seconds: position, preferredTimescale: 600), completionHandler: nil)
+    }
+    if savedRate > 0 { player.rate = savedRate }
+  }
+
+  func skipToNext() {
+    player.advanceToNextItem()
+  }
+
+  func skipToPrevious() {
+    // AVQueuePlayer is forward-only; seeking the current item to 0
+    // is the closest approximation. TrackPlayer's queue model owns
+    // the bidirectional skip semantics by rebuilding the queue
+    // when needed.
+    player.currentItem?.seek(to: .zero, completionHandler: nil)
+  }
+
+  // MARK: - Config
+
+  func setVolume(_ volume: Float) {
+    player.volume = volume
+  }
+
+  func setPlaybackSpeed(_ speed: Float) {
+    userSpeed = speed
+    player.rate = speed
+    // The resolved algorithm depends on whether speed is unity, so a
+    // change that crosses 1.0 re-stamps the queue (idempotent — only
+    // the items whose effective algorithm changed are touched).
+    reapplyPitchAlgorithm()
+  }
+
+  func seedPlaybackSpeed(_ speed: Float) {
+    // Persist only; `play()` applies it. Does not touch `player.rate`,
+    // so it won't start a paused engine.
+    userSpeed = speed
+    reapplyPitchAlgorithm()
+  }
+
+  func setRepeatMode(_: RepeatMode) {
+    // AVQueuePlayer doesn't have a native repeat mode equivalent
+    // to ExoPlayer; TrackPlayer's QueueSkipArithmetic handles the
+    // repeat semantics by rebuilding the queue at the appropriate
+    // moment. No work to do at the engine layer.
+  }
+
+  func setPitchCorrectionMode(_ mode: PitchCorrectionMode) {
+    pitchCorrectionMode = mode
+    reapplyPitchAlgorithm()
+  }
+
+  /// Stamp the resolved algorithm on `item`. Idempotent: a no-op when
+  /// the item already carries it, so re-applying on a rendering item
+  /// doesn't churn the audio graph.
+  private func applyPitchAlgorithm(to item: AVPlayerItem) {
+    let algo = PitchAlgorithm.resolve(mode: pitchCorrectionMode, speed: userSpeed)
+    if item.audioTimePitchAlgorithm != algo {
+      item.audioTimePitchAlgorithm = algo
+    }
+  }
+
+  private func reapplyPitchAlgorithm() {
+    for item in player.items() { applyPitchAlgorithm(to: item) }
+  }
+
+  // MARK: - State
+
+  var currentMediaItemIndex: Int {
+    let queueItems = player.items()
+    if queueItems.isEmpty { return -1 }
+    if let current = player.currentItem,
+       let idx = queueItems.firstIndex(of: current) {
+      return idx
+    }
+    // Queue is non-empty but currentItem is nil — paused at the
+    // edge of the queue. Return the last queued index so callers
+    // see "still on the last track" rather than the empty-queue
+    // sentinel.
+    return queueItems.count - 1
+  }
+
+  var currentPositionSeconds: TimeInterval {
+    let t = player.currentTime()
+    return t.isNumeric ? CMTimeGetSeconds(t) : 0
+  }
+
+  var currentDurationSeconds: TimeInterval {
+    guard let d = player.currentItem?.duration, d.isNumeric else { return 0 }
+    return CMTimeGetSeconds(d)
+  }
+
+  var bufferedPositionSeconds: TimeInterval {
+    guard let ranges = player.currentItem?.loadedTimeRanges,
+          let last = ranges.last?.timeRangeValue else { return 0 }
+    return CMTimeGetSeconds(last.start + last.duration)
+  }
+
+  var isPlaying: Bool {
+    player.timeControlStatus == .playing
+  }
+
+  var timeControlStatus: AVPlayer.TimeControlStatus {
+    player.timeControlStatus
+  }
+
+  var currentMediaItem: AVPlayerItem? {
+    player.currentItem
+  }
+
+  var allMediaItems: [AVPlayerItem] {
+    player.items()
+  }
+
+  // MARK: - Effect chain
+
+  func setAudioMixProvider(_ provider: AudioMixProvider?) {
+    mixProvider = provider
+    refreshAllItemMixes()
+  }
+
+  func refreshAllItemMixes() {
+    // Catch-up walk: only fill items that were inserted with
+    // `audioMix == nil` (typically streaming items whose `tracks`
+    // key hadn't loaded at insert time, so `audioMix(for:)` returned
+    // nil). Items that already carry a tap are left alone —
+    // re-assigning would allocate a fresh `MTAudioProcessingTap` +
+    // `EQProcessor` cascade that AVPlayer silently drops once the
+    // item has begun rendering, leaking the prepared resources to
+    // ARC until the property is reassigned again. The intended
+    // mid-play tap handoff is "subscribers join the already-running
+    // tap via `AudioTapProvider.deliverAudioFrame` fan-out", not "tear
+    // down + reinstall the tap on every refresh".
+    let provider = mixProvider
+    for item in player.items() {
+      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")
+  }
+}

package/ios/InputGuards.swift

@@ -0,0 +1,63 @@
+import Foundation
+
+/// Pure-Swift input-validation helpers for the JS↔native boundary.
+///
+/// JS numbers cross into Swift as `Double`. Two failure modes need
+/// guarding before the value reaches AVFoundation / `Int(_:)` /
+/// `CMTime`:
+///
+/// 1. **Non-finite inputs** (`NaN`, `±Infinity`, `signalingNaN`).
+///    `Int(.nan)` and `Int(.infinity)` are undefined behaviour in
+///    Swift (trap in `-O0`, garbage in `-O`); `CMTime(seconds:
+///    .nan, …)` resolves to `CMTime.invalid` which AVPlayer
+///    documents as a no-op since iOS 7 but the contract is fragile.
+/// 2. **Out-of-range inputs.** Negative track indices, fractional
+///    indices, or indices past `tracks.count` are silent no-ops at
+///    the public API surface (matches the documented contract +
+///    Android parity).
+///
+/// Helpers live here as pure functions so they can be exercised by
+/// XCTest without instantiating a `TrackPlayer` (which depends on
+/// AVQueuePlayer + AVAudioSession + Nitrogen-generated types).
+///
+/// Gated behind `@_spi(QueuePlayerTests)` so the helpers stay off
+/// the library's consumer-facing public surface — same SPI scope
+/// used by `AVQueueBuilder.makeItemRaw`. The `@_spi` annotation
+/// goes on each function (not the enum) to match the
+/// 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.
+public enum InputGuards {
+
+  /// Validate a `Double` that JS sends as a queue index. Returns
+  /// `nil` for non-finite, negative, or out-of-range values; the
+  /// returned `Int` (when non-nil) is bounded by `count` and
+  /// guaranteed to be in `0..<count`. Fractional values silently
+  /// floor — matches Android `(value * 1.0).toLong()` semantic and
+  /// the documented "out-of-range is a silent no-op" contract.
+  ///
+  /// Validating in `Double` space before the `Int` conversion
+  /// matters because `Int(.nan)` / `Int(.infinity)` are UB; once
+  /// the bounds checks pass, `Int(value)` is safe.
+  @_spi(QueuePlayerTests)
+  public static func validQueueIndex(_ value: Double, count: Int) -> Int? {
+    guard value.isFinite, value >= 0, value < Double(count) else { return nil }
+    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
+  /// values past the duration to the duration — that logic depends
+  /// on the live `currentItem.duration` and is not in scope for a
+  /// pure-Swift helper.
+  @_spi(QueuePlayerTests)
+  public static func sanitisedSeekPosition(_ value: Double) -> Double? {
+    guard value.isFinite else { return nil }
+    return value
+  }
+}

package/ios/InterruptionEventMapping.swift

@@ -0,0 +1,51 @@
+import Foundation
+
+/// Maps `AudioSession.InterruptionKind` to the lib-standardized
+/// `nativeDomain` string + a stable human-readable message used by
+/// `TrackPlayer.wireAudioSession()` when firing the corresponding
+/// non-fatal `PlaybackError` through `errorListeners`.
+///
+/// Pure function; no instance state. Mirrors `PlaybackErrorMapping`.
+///
+/// Three `nativeDomain` strings — all share the
+/// `AUDIO_SESSION_INTERRUPTION_` prefix so JS consumers can branch
+/// on `nativeDomain.startsWith(...)` and treat any
+/// audio-session-interruption variant as a single category when they
+/// don't care about the resume-hint sub-state. `.endedShouldNotResume`
+/// maps to the bare `..._ENDED` (no `_SHOULD_NOT_RESUME` suffix) so
+/// consumers that ignore the resume-hint variant default to the
+/// "stop" semantics.
+enum InterruptionEventMapping {
+
+  /// Shared prefix for the three interruption `nativeDomain` strings.
+  static let nativeDomainPrefix = "AUDIO_SESSION_INTERRUPTION_"
+
+  /// `nativeDomain` for the supplied interruption kind.
+  static func nativeDomain(for kind: AudioSession.InterruptionKind) -> String {
+    switch kind {
+    case .began:
+      return nativeDomainPrefix + "BEGAN"
+    case .endedShouldResume:
+      return nativeDomainPrefix + "ENDED_SHOULD_RESUME"
+    case .endedShouldNotResume:
+      return nativeDomainPrefix + "ENDED"
+    }
+  }
+
+  /// Human-readable message for the supplied interruption kind.
+  /// Same string is fired as both `message` and `nativeMessage` on
+  /// the resulting `PlaybackError` — there's no lib-mapped vs native
+  /// distinction at this layer (session-scope event, not track-
+  /// scope error).
+  static func message(for kind: AudioSession.InterruptionKind) -> String {
+    switch kind {
+    case .began:
+      return "Audio session interruption began"
+    case .endedShouldResume:
+      return "Audio session interruption ended; system suggests resume"
+    case .endedShouldNotResume:
+      return "Audio session interruption ended"
+    }
+  }
+
+}

package/ios/ListenerRegistry.swift

@@ -0,0 +1,73 @@
+import Foundation
+
+/// Thread-safe registry of event-listener callbacks, keyed by stable
+/// numeric IDs so individual subscribers can dispose without
+/// disturbing the others.
+///
+/// Each native event (state change, track change, progress, error,
+/// queue end, cache status) gets its own registry. `onXxx(callback)`
+/// registers, returns a closure that calls `remove(id)`.
+final class ListenerRegistry<T> {
+  private struct Entry {
+    let id: Int64
+    let callback: T
+  }
+
+  private let queue = DispatchQueue(label: "com.margelo.nitro.queueplayer.listenerRegistry")
+  private var entries: [Entry] = []
+  private var nextId: Int64 = 0
+
+  /// Register a callback and return its stable ID for later removal.
+  @discardableResult
+  func add(_ callback: T) -> Int64 {
+    var id: Int64 = 0
+    queue.sync {
+      nextId &+= 1
+      id = nextId
+      entries.append(Entry(id: id, callback: callback))
+    }
+    return id
+  }
+
+  /// Remove the callback with the given ID. Returns true if found.
+  @discardableResult
+  func remove(id: Int64) -> Bool {
+    var found = false
+    queue.sync {
+      if let idx = entries.firstIndex(where: { $0.id == id }) {
+        entries.remove(at: idx)
+        found = true
+      }
+    }
+    return found
+  }
+
+  /// Remove all registered callbacks.
+  func clear() {
+    queue.sync { entries.removeAll() }
+  }
+
+  /// Invoke `action` for every registered callback. Iteration is over
+  /// a snapshot taken under the queue lock, so listeners adding/
+  /// removing during a fire round don't corrupt the iteration.
+  func forEach(_ action: (T) -> Void) {
+    let snap = queue.sync { entries.map(\.callback) }
+    snap.forEach(action)
+  }
+
+  /// True when no callbacks are registered. Handy for skipping
+  /// per-tick work (e.g. progress observer body) when nothing's
+  /// listening.
+  var isEmpty: Bool {
+    queue.sync { entries.isEmpty }
+  }
+
+  /// True when the given id is still registered. Used by deferred
+  /// auto-fire paths (e.g. `onSkipCapabilityChange`) to skip the
+  /// callback when the subscriber disposed between registration
+  /// and the deferred fire — avoids calling into an unmounted React
+  /// component's `setSnapshot`.
+  func contains(id: Int64) -> Bool {
+    queue.sync { entries.contains(where: { $0.id == id }) }
+  }
+}