react-native-queue-player 1.0.0

package/ios/AVQueueBuilder.swift

@@ -0,0 +1,200 @@
+import AVFoundation
+
+/// Builder utility for `[AVPlayerItem]` arrays, with HTTP-header +
+/// user-agent injection on remote URLs.
+///
+/// The enum is `public` only so XCTest targets can reach the `Raw`-suffix
+/// helpers through plain `import QueuePlayer` (see NOTES.md §6 for the
+/// Swift ↔ C++ interop reason we can't rely on `@testable import`).
+/// The `Raw` helpers themselves are gated behind `@_spi(QueuePlayerTests)`
+/// so consumers who don't opt into the SPI never see them — the API
+/// surface consumers care about is the Nitrogen-integrated TrackPlayer
+/// methods, not this builder directly.
+///
+/// Constructs AVPlayerItem instances from TrackItem descriptors,
+/// applying the PlayerConfig's custom HTTP headers + user agent.
+///
+/// Headers are the load-bearing feature for Subsonic-behind-reverse-
+/// proxy deployments — every remote fetch (asset read, lookahead-
+/// cache download, artwork fetch) has to carry the consumer app's
+/// auth. `AVURLAssetHTTPHeaderFieldsKey` on the AVURLAsset options
+/// dictionary does this on iOS.
+///
+/// User-Agent handling: AVURLAsset has no dedicated UA option. The
+/// standard workaround is to include `User-Agent: <ua>` inside the
+/// headers dictionary — AVFoundation forwards it through verbatim.
+///
+/// File URLs (`file://...`) skip headers entirely (local assets
+/// don't do HTTP) and opt out of the lookahead cache.
+public enum AVQueueBuilder {
+
+  /// Build AVPlayerItems for every track in `tracks`, applying config
+  /// headers + UA on remote URLs. Returns an empty array for an empty
+  /// input. Never throws — invalid URLs silently produce a nil asset
+  /// which AVQueuePlayer surfaces as a playback error at runtime.
+  ///
+  /// When `cache` is non-nil + a track is fully cached, the
+  /// AVPlayerItem is built from the local file URL instead of the
+  /// remote one. Bytes never hit the network on playback. Partial
+  /// caches fall through to the remote URL — `cache.cachedURL`
+  /// returns nil for entries that haven't fully downloaded.
+  static func buildPlayerItems(
+    tracks: [TrackItem],
+    queueItemIds: [String],
+    config: PlayerConfig,
+    cache: LookaheadCache? = nil
+  ) -> [AVPlayerItem] {
+    // Parallel-array invariant: a violation is a programming error
+    // we own (QueueState uphold-able at construction). `precondition`
+    // fires in Debug + Release; soft-failing would leave caller state
+    // inconsistent (player empty, `self.tracks` populated).
+    precondition(
+      tracks.count == queueItemIds.count,
+      "AVQueueBuilder.buildPlayerItems requires queueItemIds parallel to tracks (1:1)"
+    )
+    return zip(tracks, queueItemIds).compactMap { track, id in
+      makeItem(for: track, queueItemId: id, config: config, cache: cache)
+    }
+  }
+
+  /// Single-item builder. Used by addToQueue. Honours the cache
+  /// lookup when a cache instance is supplied.
+  ///
+  /// `queueItemId` is the lib-generated identity for this AVPlayerItem
+  /// instance — set on the constructed item via the
+  /// `AVPlayerItem.queueItemId` associated-object extension.
+  /// `TrackPlayer` owns the parallel `queueItemIds: [String]` array
+  /// (1:1 with `self.tracks`) and pre-allocates a UUID per queue
+  /// position; the value passed here is the corresponding entry.
+  /// Never derived from any consumer-supplied TrackItem field —
+  /// only `track.url` is required + reliable on consumer data.
+  static func makeItem(
+    for track: TrackItem,
+    queueItemId: String,
+    config: PlayerConfig,
+    cache: LookaheadCache? = nil
+  ) -> AVPlayerItem? {
+    if let cachedURL = cache?.cachedURL(forUrl: track.url) {
+      // Local file URL — no headers needed. `cachedURL` is a pure
+      // read; LRU bookkeeping is opt-in via `touch` so a read-heavy
+      // playback path doesn't trigger a plist write per resolution.
+      cache?.touch(url: track.url)
+      // `automaticallyLoadedAssetKeys` pre-loads the listed keys
+      // asynchronously while the AVPlayerItem itself becomes
+      // addressable — Apple's documented iOS 16+ preferred
+      // construction pattern, shaving first-frame latency vs a
+      // bare `AVPlayerItem(asset:)` that loads keys lazily on first
+      // access.
+      //
+      // `"tracks"` is included here (file:// branch only — the
+      // HTTP path in `makeItemRaw` keeps the original two-key set
+      // so HLS / streaming items don't pay the variant-playlist +
+      // segment-header round-trip at insert time). The local
+      // tracks-key load is free; once it's loaded, the engine's
+      // per-item `audioMix(for:)` install (called BEFORE
+      // `player.insert`) gets a tap-bearing mix synchronously,
+      // which is the only window AVPlayer honours per Apple's
+      // contract (`audioMix` changes after the item starts
+      // rendering are silently dropped).
+      let asset = AVURLAsset(url: cachedURL)
+      let item = AVPlayerItem(
+        asset: asset,
+        automaticallyLoadedAssetKeys: ["playable", "duration", "tracks"]
+      )
+      pinForwardBufferDuration(on: item)
+      item.queueItemId = queueItemId
+      item.sourceURL = track.url
+      return item
+    }
+    let item = makeItemRaw(
+      urlString: track.url,
+      headers: config.httpHeaders,
+      userAgent: config.userAgent)
+    item?.queueItemId = queueItemId
+    item?.sourceURL = track.url
+    return item
+  }
+
+  /// Apple-acknowledged AVPlayer mitigation: explicitly setting
+  /// `preferredForwardBufferDuration = 0.0` on every item closes a
+  /// long-standing AVQueuePlayer bug where items can be dropped
+  /// from the queue (or chain-advanced through while paused) when
+  /// the player decides duration is "exhausted" for an asset whose
+  /// HTTP load hasn't started yet. Apple Dev Forum thread 683744 +
+  /// FB9221518 — leaving the value at its implicit default exposes
+  /// the bug; explicit 0.0 (functionally the same default value,
+  /// but a different code path inside AVPlayer) does not.
+  ///
+  /// Applied uniformly to local + remote items because the bug is
+  /// independent of asset URL scheme; local file:// items are also
+  /// vulnerable when AVQueuePlayer is mid-skip. Exposed via SPI so
+  /// the AVQueueBuilderTests XCTarget can assert it directly on
+  /// `makeItemRaw`-produced items.
+  @_spi(QueuePlayerTests)
+  public static func pinForwardBufferDuration(on item: AVPlayerItem) {
+    item.preferredForwardBufferDuration = 0.0
+  }
+
+  /// Plain-Swift item builder. Takes primitive arguments so it is directly
+  /// callable from XCTest targets without crossing the Swift ↔ C++ interop
+  /// boundary; `makeItem(for:, config:)` is the thin adapter that unpacks
+  /// the Nitrogen-generated `TrackItem` + `PlayerConfig` and delegates here.
+  ///
+  /// Gated behind `@_spi(QueuePlayerTests)` so it stays off the library's
+  /// consumer-facing public surface.
+  @_spi(QueuePlayerTests)
+  public static func makeItemRaw(
+    urlString: String,
+    headers: [String: String]?,
+    userAgent: String?
+  ) -> AVPlayerItem? {
+    guard let url = URL(string: urlString) else { return nil }
+
+    let asset: AVURLAsset
+    if url.isFileURL {
+      asset = AVURLAsset(url: url)
+    } else {
+      asset = AVURLAsset(
+        url: url,
+        options: httpOptionsRaw(headers: headers, userAgent: userAgent))
+    }
+
+    // Apple-preferred AVPlayerItem construction pattern (iOS 16+):
+    // pre-load `playable` + `duration` keys asynchronously so the
+    // first frame is reachable without the AVPlayerItem
+    // round-tripping a synchronous load on first access.
+    let item = AVPlayerItem(
+      asset: asset,
+      automaticallyLoadedAssetKeys: ["playable", "duration"]
+    )
+    pinForwardBufferDuration(on: item)
+    return item
+  }
+
+  /// Plain-Swift merging core — takes primitive arguments so it is
+  /// directly callable from XCTest targets without crossing the Swift↔C++
+  /// interop boundary. `makeItemRaw(urlString:headers:userAgent:)` below
+  /// calls this, and `makeItem(for:, config:)` unpacks its `PlayerConfig`
+  /// argument into the same primitive pair and calls `makeItemRaw`.
+  ///
+  /// Gated behind `@_spi(QueuePlayerTests)` so it stays off the library's
+  /// consumer-facing public surface.
+  ///
+  /// Key spelling: `AVURLAssetHTTPHeaderFieldsKey` is not a public
+  /// Swift API. The raw Obj-C string still works at runtime. See
+  /// NOTES.md §7. We do not implement an
+  /// `AVAssetResourceLoaderDelegate` replacement — see
+  /// `plan/blocked.md`.
+  @_spi(QueuePlayerTests)
+  public static func httpOptionsRaw(
+    headers: [String: String]?,
+    userAgent: String?
+  ) -> [String: Any] {
+    var merged: [String: String] = headers ?? [:]
+    if let ua = userAgent, !ua.isEmpty {
+      merged["User-Agent"] = ua
+    }
+    guard !merged.isEmpty else { return [:] }
+    return ["AVURLAssetHTTPHeaderFieldsKey": merged]
+  }
+}

package/ios/Array+SafeSubscript.swift

@@ -0,0 +1,6 @@
+extension Array {
+  /// Bounds-checked subscript that returns nil for out-of-range indices.
+  subscript(safe index: Int) -> Element? {
+    indices.contains(index) ? self[index] : nil
+  }
+}

package/ios/ArtworkLoader.swift

@@ -0,0 +1,136 @@
+import Foundation
+import UIKit
+
+/// Multi-request artwork loader shared across the CarPlay browse +
+/// Now Playing surfaces and the lock-screen / control-center
+/// `MPNowPlayingInfoCenter` flow.
+///
+/// Concurrency model: every `load(uri:completion:)` issues an
+/// independent `URLSessionDataTask`. There is no per-loader
+/// "single-in-flight" policy — CarPlay's `CPListImageRowItem`
+/// rendering needs many image fetches resolved in parallel, and a
+/// list scroll cannot tolerate one fetch cancelling the prior. The
+/// caller (e.g. [ArtworkResolver] for the now-playing single-slot
+/// surface) decides whether late completions should be dropped.
+///
+/// Caching: `NSCache<NSURL, UIImage>` keyed on the URL. Memory
+/// pressure can evict; a re-load after eviction silently re-fetches.
+/// The cache is shared across every caller of the same loader
+/// instance, so browse-list loads warm subsequent now-playing reads.
+///
+/// Threading: `load` is called on any thread; completion fires on
+/// main. `file://` decodes hop to a utility queue so a multi-MB
+/// consumer-supplied bitmap does not hitch the main thread on a
+/// track change.
+final class ArtworkLoader {
+
+  /// HTTP headers to send on every artwork request. Owner sets from
+  /// the live `PlayerConfig.httpHeaders` snapshot. Last write wins.
+  /// Reads + writes are NSLock-protected — `load(uri:)` is called
+  /// on any thread; `ArtworkResolver` mutates from main while a
+  /// fetch may still be in flight on a URLSession queue.
+  var configHeaders: [String: String]? {
+    get { configLock.withLock { _configHeaders } }
+    set { configLock.withLock { _configHeaders = newValue } }
+  }
+
+  /// User-agent override for artwork requests. Owner sets from
+  /// `PlayerConfig.userAgent`. When nil, URLSession's default UA wins.
+  /// Header precedence: `URLRequest.setValue(_:forHTTPHeaderField:)`
+  /// is last-write-wins; `User-Agent` is written first then any
+  /// matching key in [configHeaders] overrides.
+  var configUserAgent: String? {
+    get { configLock.withLock { _configUserAgent } }
+    set { configLock.withLock { _configUserAgent = newValue } }
+  }
+
+  init(session: URLSession = URLSession(configuration: .ephemeral)) {
+    self.session = session
+  }
+
+  /// Load `uri` to a [UIImage], or `nil` when the URI is missing /
+  /// invalid / unreachable. Completion fires on the main queue.
+  ///
+  /// - `nil` / empty string → `nil` immediately (no fetch).
+  /// - `file://` → off-main decode via `UIImage(contentsOfFile:)`.
+  /// - `http://` / `https://` → URLSession data task, cached on
+  ///   success.
+  /// - Any other scheme → `nil` immediately (the lib has no contract
+  ///   for `data://`, `blob://`, custom schemes).
+  func load(uri: String?, completion: @escaping (UIImage?) -> Void) {
+    guard let uri = uri, !uri.isEmpty else {
+      DispatchQueue.main.async { completion(nil) }
+      return
+    }
+
+    if uri.hasPrefix("file://"),
+       let nsurl = URL(string: uri) {
+      let path = nsurl.path
+      DispatchQueue.global(qos: .userInitiated).async {
+        let image = UIImage(contentsOfFile: path)
+        DispatchQueue.main.async { completion(image) }
+      }
+      return
+    }
+
+    guard let nsurl = URL(string: uri),
+          let scheme = nsurl.scheme,
+          scheme == "http" || scheme == "https" else {
+      DispatchQueue.main.async { completion(nil) }
+      return
+    }
+
+    if let cached = cache.object(forKey: nsurl as NSURL) {
+      DispatchQueue.main.async { completion(cached) }
+      return
+    }
+
+    var req = URLRequest(url: nsurl)
+    req.timeoutInterval = 10
+    // Snapshot under the lock so a concurrent setter during fetch
+    // build can't interleave the UA write + headers loop.
+    let (ua, headers): (String?, [String: String]?) = configLock.withLock {
+      (_configUserAgent, _configHeaders)
+    }
+    if let ua = ua {
+      req.setValue(ua, forHTTPHeaderField: "User-Agent")
+    }
+    if let headers = headers {
+      for (key, value) in headers {
+        req.setValue(value, forHTTPHeaderField: key)
+      }
+    }
+
+    let cache = self.cache
+    let task = session.dataTask(with: req) { data, _, _ in
+      let image: UIImage? = data.flatMap { UIImage(data: $0) }
+      if let image = image {
+        cache.setObject(image, forKey: nsurl as NSURL)
+      }
+      DispatchQueue.main.async { completion(image) }
+    }
+    task.resume()
+  }
+
+  /// Drop every cached entry. Owner calls on `destroy()` or whenever
+  /// the consumer's auth credentials rotate (a stale cached image
+  /// fetched with a now-invalid auth header is still rendered from
+  /// the cache; clearing forces a re-fetch with fresh headers).
+  func clearCache() {
+    cache.removeAllObjects()
+  }
+
+  private let cache = NSCache<NSURL, UIImage>()
+  private let session: URLSession
+
+  private let configLock = NSLock()
+  private var _configHeaders: [String: String]?
+  private var _configUserAgent: String?
+}
+
+private extension NSLock {
+  func withLock<T>(_ body: () throws -> T) rethrows -> T {
+    lock(); defer { unlock() }
+    return try body()
+  }
+}

package/ios/ArtworkResolver.swift

@@ -0,0 +1,87 @@
+import Foundation
+import UIKit
+
+/// Resolves a `track.artworkUrl` to a `UIImage` for the lock-screen /
+/// control-center surface. Always delivers a non-nil image: when the
+/// URL is null / empty / invalid / unreachable, the bundled
+/// `PlaceholderArtwork` image is the floor.
+///
+/// Single in-flight policy: starting a new `resolve(...)` bumps a
+/// monotonic sequence counter. Completions captured against an older
+/// sequence are dropped in favour of the latest caller's expectation
+/// (e.g. a same-URL re-resolve issued during an in-flight fetch
+/// correctly drops the prior request's response).
+///
+/// Delegates the actual URI → UIImage resolution to [ArtworkLoader],
+/// which owns the cache + URLSession. Sharing the loader across
+/// callers (e.g. the CarPlay browse builder) means every browse-list
+/// fetch warms the now-playing cache and vice versa.
+final class ArtworkResolver {
+
+  /// HTTP headers to send on every artwork request. Forwarded to the
+  /// underlying loader so the next `resolve(...)` reads fresh.
+  var configHeaders: [String: String]? {
+    get { loader.configHeaders }
+    set { loader.configHeaders = newValue }
+  }
+
+  /// User-agent override for artwork requests. Forwarded to the loader.
+  var configUserAgent: String? {
+    get { loader.configUserAgent }
+    set { loader.configUserAgent = newValue }
+  }
+
+  /// Owner injects an [ArtworkLoader] when sharing a cache + session
+  /// across resolvers. Default constructs a private loader with an
+  /// ephemeral session — no cookie jar, no shared on-disk cache.
+  init(loader: ArtworkLoader = ArtworkLoader()) {
+    self.loader = loader
+  }
+
+  /// Convenience: build a private loader bound to [session]. Lets
+  /// tests inject a `URLProtocol`-stubbed session without owning the
+  /// loader directly.
+  convenience init(session: URLSession) {
+    self.init(loader: ArtworkLoader(session: session))
+  }
+
+  /// Resolve `url` to a UIImage. Completion fires on main with the
+  /// placeholder when anything goes wrong (nil URL, non-http(s)
+  /// scheme, network failure). Completion is intentionally DROPPED
+  /// when the resolver is cancelled (`cancelInFlight`) or superseded
+  /// by a later `resolve(...)` — the new caller's completion is the
+  /// only one the consumer cares about. Threading: completion fires
+  /// on main.
+  func resolve(url: String?, completion: @escaping (UIImage) -> Void) {
+    self.currentSeq &+= 1
+    let seq = self.currentSeq
+
+    loader.load(uri: url) { [weak self] image in
+      guard let self = self, self.currentSeq == seq else { return }
+      completion(image ?? PlaceholderArtwork.image)
+    }
+  }
+
+  /// Bump the sequence counter so any in-flight loader completion
+  /// captured against the old seq is dropped. The underlying
+  /// `URLSessionDataTask` is intentionally not cancelled — bytes
+  /// already in transit will populate the loader's cache for a
+  /// future `resolve(...)` that hits the same URL.
+  func cancelInFlight() {
+    currentSeq &+= 1
+  }
+
+  /// Clear the underlying loader's cache + drop the in-flight
+  /// completion. Idempotent and reusable: a subsequent `resolve(...)`
+  /// is valid and uses the same underlying session.
+  func reset() {
+    cancelInFlight()
+    loader.clearCache()
+  }
+
+  private let loader: ArtworkLoader
+  /// Monotonic resolve-call counter. Captured into completion closures
+  /// to drop responses for superseded requests, including same-URL
+  /// re-resolves that the URL-string compare cannot distinguish.
+  private var currentSeq: UInt64 = 0
+}

package/ios/AudioCategoryMapping.swift

@@ -0,0 +1,48 @@
+import AVFoundation
+
+/// Maps `PlayerConfig.audioContentType` + `PlayerConfig.audioCategoryOptions`
+/// to the AVAudioSession `Mode` + `CategoryOptions` used during
+/// `AudioSession.activate()`.
+///
+/// Pure function; no instance state. Mirrors `PlaybackErrorMapping`
+/// + `InterruptionEventMapping`.
+///
+/// `audioContentType == .speech` triggers two effects:
+/// 1. AVAudioSession mode flips to `.spokenAudio` (per Apple HIG —
+///    spoken-audio sessions PAUSE under nav-voice instead of ducking).
+/// 2. `interruptSpokenAudio` defaults to `true` (interrupt other apps'
+///    spoken-audio sessions, mix with their music). Consumer-supplied
+///    `interruptSpokenAudio` overrides the default.
+enum AudioCategoryMapping {
+
+  /// AVAudioSession mode for the supplied content type. `nil` /
+  /// `.music` → `.default`; `.speech` → `.spokenAudio`.
+  static func mode(for contentType: AudioContentType?) -> AVAudioSession.Mode {
+    if contentType == .speech {
+      return .spokenAudio
+    }
+    return .default
+  }
+
+  /// AVAudioSession category options. Each consumer-supplied flag
+  /// maps to a single option; `interruptSpokenAudio` defaults
+  /// `true` when `contentType == .speech`, `false` otherwise.
+  static func options(
+    for opts: AudioCategoryOptions?,
+    contentType: AudioContentType?
+  ) -> AVAudioSession.CategoryOptions {
+    var result: AVAudioSession.CategoryOptions = []
+    if opts?.duckOthers == true {
+      result.insert(.duckOthers)
+    }
+    if opts?.mixWithOthers == true {
+      result.insert(.mixWithOthers)
+    }
+    let speechDefault = (contentType == .speech)
+    let interruptSpokenAudio = opts?.interruptSpokenAudio ?? speechDefault
+    if interruptSpokenAudio {
+      result.insert(.interruptSpokenAudioAndMixWithOthers)
+    }
+    return result
+  }
+}