react-native-queue-player 1.2.0 → 2.0.0

package/ios/QueueWindowArithmetic.swift

@@ -0,0 +1,152 @@
+import Foundation
+
+/// Pure-Swift arithmetic for the bounded enqueue window.
+///
+/// Everything here is expressed in absolute queue *positions* — never engine
+/// indices, which move as `AVQueuePlayer` consumes finished items.
+///
+/// `slice` describes the installed run — a trail behind the playhead plus the
+/// forward window — and it **may wrap**: it can end at a lower absolute
+/// position than it starts. A wrapped slice is a run in play order, not an
+/// ordered set of integers, so it must not be compared with `<` / `>`, sorted,
+/// or turned into a `Range<Int>`. The floor bounds its forward part.
+///
+/// `isAtLogicalTail` and `verdict` answer what a drained engine means, in
+/// absolute positions and without wrapping — see `isAtLogicalTail` for why
+/// that asymmetry is deliberate.
+///
+/// Helpers are gated behind `@_spi(QueuePlayerTests)` so they stay off the
+/// library's consumer-facing surface, matching `QueueMutationArithmetic`.
+public enum QueueWindowArithmetic {
+
+  /// Items materialised at or after the current track, inclusive of it.
+  ///
+  /// Three is the minimum that satisfies "top up whenever at most one item
+  /// remains after the current one, and never let that reach zero": a smaller
+  /// floor lands an append in the slot `AVQueuePlayer` is about to consume.
+  /// Ten sits well clear of that minimum. The cost windowing exists to avoid is
+  /// per-item — item construction, a cache lookup, an LRU touch — and it is a
+  /// queue-length problem, not a window-length one: ten items is a fixed,
+  /// negligible cost where the unbounded build was thousands.
+  @_spi(QueuePlayerTests)
+  public static let floor: Int = 10
+
+  /// What a drained engine means for the queue as a whole.
+  @_spi(QueuePlayerTests)
+  public enum EndVerdict: Equatable {
+    /// The engine still has an active item; nothing ended.
+    case notEnded
+    /// Re-enqueue the current position. Under `.track` the queue can neither
+    /// end nor advance, so a drain is always the same position again.
+    case refillCurrent
+    /// The engine ran out mid-queue. Re-seat the queue from the next position
+    /// and resume — not a queue end.
+    case windowDrained
+    /// The logical queue ended under `.queue`; restart from position 0.
+    case wrapToStart
+    /// The logical queue ended. Fire `onQueueEnd` and settle to `.ended`.
+    case queueEnd
+  }
+
+  /// Positions the engine should hold around `currentIndex`, in install order.
+  ///
+  /// `trail` positions behind the current one, the current one, and forward to
+  /// the floor. The trail exists so a backward skip reuses an `AVURLAsset`
+  /// already built; a run that only grows forward moves the memory peak later
+  /// rather than lowering it, because nothing is ever removed.
+  ///
+  /// `wraps` is whether the queue returns to position 0 at its end, which is
+  /// what makes a repeat-queue boundary a crossfade rather than a hard cut:
+  /// the incoming item has to be materialised before the outgoing one ends.
+  ///
+  /// Returns at most `min(trail + floor, trackCount)` positions, always as one
+  /// unbroken run in play order: each position is the previous one plus one,
+  /// modulo `trackCount`. Where the run covers the whole queue the position
+  /// after the last is the first; everywhere else it is not installed yet and
+  /// belongs to top-up.
+  ///
+  /// A position appears at most once. Two materialisations of one position
+  /// would give the engine two items carrying the same `queueItemId`, and
+  /// every translation from position to engine index is a first-match — so the
+  /// second copy would be unreachable and the trail could strand the item
+  /// being heard. The forward run and the trail can only meet when the slice
+  /// already covers every position, so nothing is lost either way; the forward
+  /// run keeps the contested position because that is what leaves the result
+  /// one unbroken run.
+  ///
+  /// A queue of one wraps onto itself, so it cannot both hold a fresh incoming
+  /// item and hold each position once. It holds the one position, and a
+  /// repeat-queue boundary there is a hard cut.
+  @_spi(QueuePlayerTests)
+  public static func slice(
+    currentIndex: Int, trackCount: Int, trail: Int, wraps: Bool
+  ) -> [Int] {
+    guard trackCount > 0, currentIndex >= 0, currentIndex < trackCount else { return [] }
+    let cap = min(max(0, trail) + floor, trackCount)
+
+    // Uniqueness rests on the cap: a run of at most `trackCount` positions
+    // stepping one at a time cannot revisit one. The `held` checks below are a
+    // second mechanism, and are unreachable while the cap holds — they are
+    // what keeps a future change to the cap from silently emitting duplicates.
+    var positions: [Int] = []
+    var held = Set<Int>()
+
+    var forward = currentIndex
+    while positions.count < min(floor, trackCount) {
+      guard !held.contains(forward) else { break }
+      positions.append(forward)
+      held.insert(forward)
+      let next = forward + 1
+      if next < trackCount {
+        forward = next
+      } else if wraps {
+        forward = 0
+      } else {
+        break
+      }
+    }
+
+    var behind: [Int] = []
+    var step = 1
+    while behind.count < max(0, trail), positions.count + behind.count < cap {
+      let raw = currentIndex - step
+      let position = raw >= 0 ? raw : (wraps ? raw + trackCount : -1)
+      guard position >= 0, !held.contains(position) else { break }
+      behind.append(position)
+      held.insert(position)
+      step += 1
+    }
+
+    return behind.reversed() + positions
+  }
+
+  /// Whether the last enqueued position is also the last position in the
+  /// queue. False on an empty queue, where `-1 == -1` would otherwise read
+  /// as a tail.
+  ///
+  /// Deliberately not wrap-aware, even though `slice` wraps. `verdict` pairs
+  /// this with `.windowDrained`, whose caller advances by a **non-modular**
+  /// clamp; today that clamp is unreachable precisely because this answers
+  /// true at the last position. An answer that went modular here would make it
+  /// reachable, and the last track would re-seat onto itself instead of
+  /// wrapping. A wrapping run's completeness is a question for the top-up
+  /// path, not for the drain verdict.
+  @_spi(QueuePlayerTests)
+  public static func isAtLogicalTail(anchorPosition: Int, trackCount: Int) -> Bool {
+    guard trackCount > 0 else { return false }
+    return anchorPosition == trackCount - 1
+  }
+
+  /// Resolve what a drained engine means. `drained` is "the engine has no
+  /// active item"; `atLogicalTail` is `isAtLogicalTail` against the anchor.
+  /// Caller must hold a non-empty queue — an empty one has nothing to end.
+  @_spi(QueuePlayerTests)
+  public static func verdict(
+    drained: Bool, atLogicalTail: Bool, repeatMode: QueueSkipRepeatMode
+  ) -> EndVerdict {
+    guard drained else { return .notEnded }
+    if repeatMode == .track { return .refillCurrent }
+    guard atLogicalTail else { return .windowDrained }
+    return repeatMode == .queue ? .wrapToStart : .queueEnd
+  }
+}

package/ios/ReadThroughServer.swift

@@ -0,0 +1,283 @@
+import Foundation
+import Network
+
+/// Serves the player's remote tracks from the lookahead cache when it holds
+/// them, and from the origin when it does not.
+///
+/// The player binds one stable `http://127.0.0.1:<port>/media/<token>` per
+/// source URL and never re-points it. Whether a request is answered from disk
+/// or from the network is decided per request, which is the only moment the
+/// answer is actually knowable — the cache fills while the queue is already
+/// built, so a URL chosen at construction is always chosen too early.
+///
+/// Loopback-bound: nothing outside the device needs to reach it. That is a
+/// smaller default rather than a security boundary — another process on the
+/// same device could reach it too, and the 128-bit token is what stands in its
+/// way.
+final class ReadThroughServer: @unchecked Sendable {
+
+  /// Token → the origin it stands for. Written on the player's queue, read on
+  /// connection queues.
+  private let lock = NSLock()
+  private var origins: [String: URL] = [:]
+  private var tokensBySource: [String: String] = [:]
+  /// The consumer's `track.url` string per token: the cache is keyed on it
+  /// verbatim, and `URL.absoluteString` is a re-serialisation that can differ
+  /// from it (percent-encoding on iOS 17+).
+  private var sourceURLs: [String: String] = [:]
+  private var touched: Set<String> = []
+  private var headers: [String: String] = [:]
+
+  private let listenerLock = NSLock()
+  private var listener: NWListener?
+  private var boundPort: UInt16 = 0
+  private var connections: [ObjectIdentifier: MediaHTTPConnection] = [:]
+  private var bindWaiters: [DispatchSemaphore] = []
+
+  private let serverQueue = DispatchQueue(label: "queueplayer.readthrough.listener")
+
+  /// One session for every origin leg, so connections are pooled across the
+  /// per-request client connections AVFoundation opens.
+  private let session: URLSession
+
+  /// The default session: pooled like `URLSession.shared`, but with no
+  /// `URLCache` — the lookahead cache already keeps the bytes on disk, and
+  /// `URLCache.shared` would hold a second copy of every small range.
+  private static func makeOriginSession() -> URLSession {
+    let configuration = URLSessionConfiguration.default
+    configuration.urlCache = nil
+    configuration.requestCachePolicy = .reloadIgnoringLocalCacheData
+    return URLSession(configuration: configuration)
+  }
+
+  /// Consulted per request for the cache's complete copy of an origin. Injected
+  /// rather than referenced directly so the server owns no cache lifetime.
+  private let cachedFileForOrigin: (String) -> URL?
+
+  /// Called once per token the first time it is served from disk, so the cache
+  /// can bump LRU on a real read. Not per request: `touch` writes the index on
+  /// the same serial queue the lookup takes, and AVFoundation issues several
+  /// range requests per track.
+  private let onFirstDiskHit: (String) -> Void
+
+  init(
+    session: URLSession = ReadThroughServer.makeOriginSession(),
+    cachedFileForOrigin: @escaping (String) -> URL?,
+    onFirstDiskHit: @escaping (String) -> Void
+  ) {
+    self.session = session
+    self.cachedFileForOrigin = cachedFileForOrigin
+    self.onFirstDiskHit = onFirstDiskHit
+  }
+
+  // MARK: - Routing
+
+  /// The local URL standing for `origin`, or nil when the listener is not up.
+  ///
+  /// Stable for the life of the session: one token per source string, so a
+  /// window rebuild hands the player the URL it already has and AVFoundation
+  /// keeps reusing its own connections. Keyed on the string rather than the
+  /// parsed URL because two strings that parse alike are still two tracks with
+  /// two cache entries.
+  /// `sourceURL` is the `track.url` string the cache is keyed on; it defaults
+  /// to the origin's own serialisation for callers that have no other.
+  func localURL(for origin: URL, sourceURL: String? = nil) -> URL? {
+    let port = boundPortValue()
+    guard port != 0 else { return nil }
+    let source = sourceURL ?? origin.absoluteString
+    lock.lock()
+    let token: String
+    if let existing = tokensBySource[source] {
+      token = existing
+    } else {
+      token = Self.newToken()
+      tokensBySource[source] = token
+      origins[token] = origin
+      sourceURLs[token] = source
+    }
+    lock.unlock()
+    #if DEBUG
+      NSLog(
+        "[RNQP-CACHE] route token=%@ -> %@",
+        String(token.prefix(8)), PlaybackErrorMapping.stripQuery(origin.absoluteString))
+    #endif
+    return URL(string: "http://127.0.0.1:\(port)/media/\(token)")
+  }
+
+  /// The consumer's headers, sent on every origin request. Written by
+  /// `startReadThroughServer` — `configure()` and `setLookaheadCache` — so a
+  /// refreshed token reaches requests for items built before it changed.
+  func setHeaders(_ headers: [String: String]) {
+    lock.lock()
+    self.headers = headers
+    lock.unlock()
+  }
+
+  private func resolve(_ token: String) -> MediaSource? {
+    lock.lock()
+    guard let origin = origins[token] else {
+      lock.unlock()
+      return nil
+    }
+    let sourceURL = sourceURLs[token] ?? origin.absoluteString
+    let headers = self.headers
+    let alreadyTouched = touched.contains(token)
+    lock.unlock()
+
+    let cached = cachedFileForOrigin(sourceURL)
+    #if DEBUG
+      NSLog(
+        "[RNQP-CACHE] resolve token=%@ cached=%@ origin=%@",
+        String(token.prefix(8)), cached == nil ? "no" : "yes",
+        PlaybackErrorMapping.stripQuery(origin.absoluteString))
+    #endif
+    if cached != nil && !alreadyTouched {
+      lock.lock()
+      touched.insert(token)
+      lock.unlock()
+      onFirstDiskHit(sourceURL)
+    }
+    return .readThrough(
+      ReadThroughSource(origin: origin, headers: headers, cachedFile: cached, session: session)
+    )
+  }
+
+  /// 128 bits, so the token cannot be enumerated by something else on the
+  /// device. Same shape `MediaHTTPRequest.mediaToken` already validates.
+  private static func newToken() -> String {
+    var bytes = [UInt8](repeating: 0, count: 16)
+    if SecRandomCopyBytes(kSecRandomDefault, bytes.count, &bytes) != errSecSuccess {
+      for i in bytes.indices { bytes[i] = UInt8.random(in: 0 ... 255) }
+    }
+    return bytes.map { String(format: "%02x", $0) }.joined()
+  }
+
+  // MARK: - Lifecycle
+
+  /// Bring the listener up. Returns immediately; `waitUntilBound` is what waits.
+  func start() {
+    listenerLock.lock()
+    guard listener == nil else {
+      listenerLock.unlock()
+      return
+    }
+    let params = NWParameters.tcp
+    // Loopback only. The cast server binds every interface because a receiver
+    // fetches over the LAN; nothing outside this device ever reads from here.
+    params.requiredLocalEndpoint = NWEndpoint.hostPort(host: "127.0.0.1", port: .any)
+    guard let newListener = try? NWListener(using: params) else {
+      listenerLock.unlock()
+      resumeReadinessWaiters()
+      return
+    }
+    listener = newListener
+    listenerLock.unlock()
+
+    newListener.stateUpdateHandler = { [weak self] state in
+      guard let self = self else { return }
+      switch state {
+      case .ready:
+        self.listenerLock.lock()
+        self.boundPort = newListener.port?.rawValue ?? 0
+        self.listenerLock.unlock()
+        self.resumeReadinessWaiters()
+      case .failed, .cancelled:
+        // Drop the listener too, so a later `start()` can try again; a
+        // failed listener left in the slot would make every restart a no-op.
+        self.listenerLock.lock()
+        if self.listener === newListener {
+          self.listener = nil
+          self.boundPort = 0
+        }
+        self.listenerLock.unlock()
+        self.resumeReadinessWaiters()
+      default:
+        break
+      }
+    }
+    newListener.newConnectionHandler = { [weak self] conn in
+      self?.accept(conn)
+    }
+    newListener.start(queue: serverQueue)
+  }
+
+  /// Block until the listener has bound, up to `timeoutMs`; `true` when it
+  /// has. Called right after `start()` on the queue that builds items, so
+  /// every item built afterwards sees a bound port: `localURL(for:)` is nil
+  /// before the bind, and an item built then is bound to its origin for good.
+  /// Binding loopback takes milliseconds; the timeout is for the listener
+  /// that never reaches `.ready`, which `start()` also reports by resuming.
+  @discardableResult
+  func waitUntilBound(timeoutMs: Int = 2000) -> Bool {
+    if boundPortValue() != 0 { return true }
+    let bound = DispatchSemaphore(value: 0)
+    listenerLock.lock()
+    if boundPort != 0 {
+      listenerLock.unlock()
+      return true
+    }
+    bindWaiters.append(bound)
+    listenerLock.unlock()
+    _ = bound.wait(timeout: .now() + .milliseconds(timeoutMs))
+    return boundPortValue() != 0
+  }
+
+  func boundPortValue() -> UInt16 {
+    listenerLock.lock(); defer { listenerLock.unlock() }
+    return boundPort
+  }
+
+  private func resumeReadinessWaiters() {
+    listenerLock.lock()
+    let waiters = bindWaiters
+    bindWaiters.removeAll()
+    listenerLock.unlock()
+    waiters.forEach { $0.signal() }
+  }
+
+  private func accept(_ conn: NWConnection) {
+    let responder = MediaHTTPConnection(
+      connection: conn,
+      resolve: { [weak self] token in self?.resolve(token) }
+    ) { [weak self] in
+      self?.untrack(conn)
+    }
+    listenerLock.lock()
+    connections[ObjectIdentifier(conn)] = responder
+    listenerLock.unlock()
+    responder.start()
+  }
+
+  private func untrack(_ conn: NWConnection) {
+    listenerLock.lock()
+    connections.removeValue(forKey: ObjectIdentifier(conn))
+    listenerLock.unlock()
+  }
+
+  /// Tear the listener down, invalidate the origin session and drop every
+  /// token. Tokens do not outlive a session, and the map is bounded by the
+  /// distinct origins seen in one — so nothing needs revoking as the queue
+  /// changes. A stopped server is not restarted; `startReadThroughServer`
+  /// builds a new one.
+  func stop() {
+    listenerLock.lock()
+    let live = listener
+    listener = nil
+    boundPort = 0
+    let open = connections
+    connections.removeAll()
+    listenerLock.unlock()
+    open.values.forEach { $0.cancel() }
+    live?.cancel()
+    session.invalidateAndCancel()
+    resumeReadinessWaiters()
+
+    lock.lock()
+    origins.removeAll()
+    tokensBySource.removeAll()
+    sourceURLs.removeAll()
+    touched.removeAll()
+    headers.removeAll()
+    lock.unlock()
+  }
+}

package/ios/RemoteCommands.swift

@@ -8,7 +8,9 @@ import MediaPlayer
 /// `pendingStateChangeReason = .system` and routes through the
 /// existing public transport methods.
 ///
-/// Threading: every public method MUST be called on the main thread.
+/// Threading: callable from any queue. Every public method hands its work to
+/// main, which owns `MPRemoteCommandCenter`. Command handlers still arrive
+/// on main — `dispatch` asserts that — and the consumer hops from there.
 /// Handlers registered with `addTarget` fire on main per Apple's docs.
 final class RemoteCommands {
 
@@ -24,11 +26,17 @@ final class RemoteCommands {
     case changePlaybackPosition(seconds: Double)
   }
 
-  /// Set by the owner during `configure()`; cleared during `destroy()`.
-  /// Invoked synchronously on main from the handler. Owner is
+  /// Set by the owner during `configure()` and cleared during `destroy()`,
+  /// both on the owner's player queue; invoked synchronously on main from
+  /// the handler, so the slot is read and written under a lock. Owner is
   /// responsible for stamping the state-change reason BEFORE routing
   /// into transport calls.
-  var onCommand: ((Command) -> Void)?
+  var onCommand: ((Command) -> Void)? {
+    get { commandLock.withLock { commandCallback } }
+    set { commandLock.withLock { commandCallback = newValue } }
+  }
+  private let commandLock = NSLock()
+  private var commandCallback: ((Command) -> Void)?
 
   /// Drive `MPRemoteCommandCenter` `isEnabled` for the skip commands.
   /// Greys out the lock-screen / CarPlay buttons that would no-op
@@ -36,6 +44,11 @@ final class RemoteCommands {
   /// when not installed — the lib must not write to the shared
   /// command center after `uninstall()` has released ownership.
   func setSkipCapability(canSkipNext: Bool, canSkipPrevious: Bool) {
+    RemoteCommands.onMain { self.setSkipCapabilityOnMain(canSkipNext: canSkipNext, canSkipPrevious: canSkipPrevious) }
+  }
+
+  @MainActor
+  private func setSkipCapabilityOnMain(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.
@@ -52,6 +65,16 @@ final class RemoteCommands {
   /// 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) {
+    RemoteCommands.onMain {
+      self.setRemoteControlsOnMain(
+        mode: mode, forwardInterval: forwardInterval, backwardInterval: backwardInterval)
+    }
+  }
+
+  @MainActor
+  private func setRemoteControlsOnMain(
+    mode: RemoteSkipMode, forwardInterval: Double, backwardInterval: Double
+  ) {
     self.skipMode = mode
     self.forwardInterval = forwardInterval
     self.backwardInterval = backwardInterval
@@ -114,6 +137,11 @@ final class RemoteCommands {
 
   /// Register handlers + enable the supported commands. Idempotent.
   func install() {
+    RemoteCommands.onMain { self.installOnMain() }
+  }
+
+  @MainActor
+  private func installOnMain() {
     guard !installed else { return }
     installed = true
     let center = MPRemoteCommandCenter.shared()
@@ -174,6 +202,11 @@ final class RemoteCommands {
   /// owns. Idempotent. Never touches commands the lib didn't enable
   /// in `install()`.
   func uninstall() {
+    RemoteCommands.onMain { self.uninstallOnMain() }
+  }
+
+  @MainActor
+  private func uninstallOnMain() {
     guard installed else { return }
     installed = false
     let center = MPRemoteCommandCenter.shared()
@@ -205,6 +238,13 @@ final class RemoteCommands {
     center.changePlaybackPositionCommand.isEnabled = false
   }
 
+  /// Hands `body` to main, which owns `MPRemoteCommandCenter` and therefore
+  /// the target registrations and `installed` flag below. Always asynchronous,
+  /// so an install and a capability update issued in order land in order.
+  private static func onMain(_ body: @escaping @MainActor () -> Void) {
+    DispatchQueue.main.async { MainActor.assumeIsolated(body) }
+  }
+
   private func dispatch(_ command: Command) {
     assert(Thread.isMainThread,
            "RemoteCommands.dispatch must run on the main thread — " +

package/ios/ReplayGainData.swift

@@ -14,7 +14,7 @@ enum ReplayGainSelectorMode: Equatable {
 /// 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
+/// `AssetReplayGainReader.read(item:)` rather than producing a
 /// ReplayGainData with one nil pair.
 ///
 /// Strict mode (`.album` requires album tag, `.track` requires
@@ -26,14 +26,33 @@ struct ReplayGainData: Equatable {
   /// 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).
+  /// or rejected — `ReplayGainExtractor.acceptPeak` accepts the
+  /// `0.001 ... 2.0` band, so a full-scale `1.0` is kept and an
+  /// encoder zero (`< 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?
 
+  /// All-or-nothing merge of consumer-supplied ReplayGain against
+  /// values detected from the file, decided **per item** — never per
+  /// mode and never per field.
+  ///
+  /// [suppliedClaimed] is `true` when any of the four fields was
+  /// present on the consumer's `TrackItem`, captured before any value
+  /// was validated. When it is `true` the track's ReplayGain comes
+  /// solely from [supplied] and [detected] is discarded in full,
+  /// including for the mode the consumer said nothing about.
+  /// `suppliedClaimed == true` with `supplied == nil` is a real state
+  /// — the consumer owns this track and gave nothing usable — so it
+  /// yields no gain and still discards detection.
+  static func merge(
+    suppliedClaimed: Bool, supplied: ReplayGainData?, detected: ReplayGainData?
+  ) -> ReplayGainData? {
+    return suppliedClaimed ? supplied : detected
+  }
+
   /// Strict mode-aware selector. See NOTES.md §25.
   ///
   /// - `.off`: returns `(nil, nil)` (no-op).