react-native-queue-player 1.0.0

package/ios/PendingBrowseRequests.swift

@@ -0,0 +1,62 @@
+import Foundation
+
+/// Native-side queue of `parentId`s a controller asked the CarPlay
+/// browse surface to enumerate before the consumer's JS bridge had
+/// pushed a [BrowseSnapshot] into [CarPlayBrowseDataProvider]. The
+/// empty `getChildren` response is the "still loading" UX hint to
+/// the controller; once a snapshot lands, the scene delegate drains
+/// the queue and rebuilds the affected `CPListTemplate` rows so the
+/// cells render with real data.
+///
+/// iOS mirror of the Android `PendingBrowseRequests`. Same shape,
+/// same semantics: idempotent enqueue, atomic drain, idempotent
+/// clear.
+///
+/// Threading: every method is safe to call from any thread —
+/// `NSLock` guards the underlying set.
+final class PendingBrowseRequests {
+
+  /// Record `parentId` as a pending request. Idempotent — duplicate
+  /// enqueues collapse, so a single [drainAll] yields one rebuild
+  /// per unique parent regardless of how many controllers asked for
+  /// it before the snapshot landed.
+  func enqueue(_ parentId: String) {
+    lock.lock()
+    defer { lock.unlock() }
+    pending.insert(parentId)
+  }
+
+  /// Atomically take + clear the pending set. Subsequent calls return
+  /// empty until the next [enqueue].
+  @discardableResult
+  func drainAll() -> Set<String> {
+    lock.lock()
+    defer { lock.unlock() }
+    let drained = pending
+    pending.removeAll()
+    return drained
+  }
+
+  /// Discard every pending entry without triggering any rebuild.
+  /// Invoked when the CarPlay scene tears down so a stale entry
+  /// doesn't strand across the next scene attach.
+  func clear() {
+    lock.lock()
+    defer { lock.unlock() }
+    pending.removeAll()
+  }
+
+  /// Snapshot the pending parents without consuming. Production
+  /// code drains via [drainAll]; this is a test-only seam. Stays
+  /// `internal` (test target imports via `@testable import`) —
+  /// mirrors the Kotlin `internal fun snapshotForTest` shape on
+  /// the Android side.
+  internal func snapshotForTest() -> Set<String> {
+    lock.lock()
+    defer { lock.unlock() }
+    return pending
+  }
+
+  private var pending: Set<String> = []
+  private let lock = NSLock()
+}

package/ios/PitchAlgorithm.swift

@@ -0,0 +1,24 @@
+import AVFoundation
+
+/// Maps the public `PitchCorrectionMode` to the native
+/// `AVAudioTimePitchAlgorithm` stamped on each `AVPlayerItem`.
+///
+/// At unity speed there is nothing to stretch, so every mode resolves to
+/// `.varispeed` — the zero-work passthrough — so no time-domain / spectral
+/// processing graph is primed while playing at normal speed. Above/below
+/// unity: `none` lets pitch follow rate (`.varispeed`), `voice` preserves
+/// pitch with the speech-tuned algorithm (`.timeDomain`), `music` preserves
+/// pitch with the transient-preserving algorithm (`.spectral`).
+enum PitchAlgorithm {
+  static func resolve(
+    mode: PitchCorrectionMode,
+    speed: Float
+  ) -> AVAudioTimePitchAlgorithm {
+    guard speed != 1.0 else { return .varispeed }
+    switch mode {
+    case .none: return .varispeed
+    case .voice: return .timeDomain
+    case .music: return .spectral
+    }
+  }
+}

package/ios/PlaceholderArtwork.swift

@@ -0,0 +1,46 @@
+import UIKit
+
+/// Bundled fallback artwork used by the lock-screen / NowPlayingInfo
+/// surface when the consumer-supplied `track.artworkUrl` is missing
+/// or unreachable. Lazy-loaded once at first use; cached for the
+/// process lifetime.
+///
+/// Resource resolution follows the CocoaPods `resource_bundles` rule:
+/// the lib's podspec packages `ios/Resources/RNQP-placeholder.jpg`
+/// into `QueuePlayer.bundle` inside the consuming app. We locate
+/// the bundle relative to this class's framework, then load the
+/// JPEG. Last-resort fallback is a 1×1 transparent UIImage so the
+/// surface NEVER hands `nil` to MPNowPlayingInfoCenter — null artwork
+/// is the failure mode that drops notification controls on some
+/// Android skins (mirror that defence on iOS too).
+enum PlaceholderArtwork {
+
+  static let image: UIImage = loadImage()
+
+  private static func loadImage() -> UIImage {
+    let frameworkBundle = Bundle(for: BundleToken.self)
+    if let resourceURL = frameworkBundle.url(forResource: "QueuePlayer", withExtension: "bundle"),
+       let resourceBundle = Bundle(url: resourceURL),
+       let path = resourceBundle.path(forResource: "RNQP-placeholder", ofType: "jpg"),
+       let img = UIImage(contentsOfFile: path) {
+      return img
+    }
+    // Static-library fallback: resources sit at the framework root
+    // when the host app links the lib statically (no .bundle suffix).
+    if let path = frameworkBundle.path(forResource: "RNQP-placeholder", ofType: "jpg"),
+       let img = UIImage(contentsOfFile: path) {
+      return img
+    }
+    return makeTransparentFallback()
+  }
+
+  private static func makeTransparentFallback() -> UIImage {
+    let renderer = UIGraphicsImageRenderer(size: CGSize(width: 1, height: 1))
+    return renderer.image { ctx in
+      UIColor.clear.setFill()
+      ctx.fill(CGRect(x: 0, y: 0, width: 1, height: 1))
+    }
+  }
+
+  private final class BundleToken {}
+}

package/ios/PlaybackEngine.swift

@@ -0,0 +1,319 @@
+import AVFoundation
+import Foundation
+
+// `StateChangeReason` and `RepeatMode` are Nitrogen-generated enums in
+// the same module — no extra imports needed.
+
+/// Strategy abstraction over the audio output pipeline.
+///
+/// Two concrete implementations:
+///  - `GaplessEngine`: single `AVQueuePlayer`, native gapless via item chaining.
+///  - `CrossfadeEngine`: dual `AVPlayer` with equal-power gain ramping
+///    via `AVMutableAudioMix.setVolumeRamp(...)` at track boundaries.
+///
+/// The engine owns the player instance(s), audio-thread effects, and
+/// track-boundary scheduling. The lib's `TrackPlayer` holds the canonical
+/// queue model + listener registries + system-side surfaces (NowPlaying,
+/// RemoteCommands, AudioSession, ArtworkResolver) and routes transport /
+/// queue calls through whichever engine is active. Engine swap (gapless ↔
+/// crossfade) is a `handoff` at the next track boundary.
+///
+/// Threading: methods are called on the main actor by convention. State
+/// queries (positions, indices, isPlaying) are read off the underlying
+/// player and so reflect the same single-threaded view AVFoundation
+/// provides on the main thread. `async` methods are launched on the same
+/// actor; impl is responsible for any internal off-actor work (e.g. the
+/// crossfade engine's standby preroll).
+protocol PlaybackEngine: AnyObject {
+
+  /// Build the underlying player(s), apply [items] starting at
+  /// [startIndex] / [startPositionSeconds], and wait for the
+  /// underlying player(s) to reach a playable state.
+  ///
+  /// Empty [items] is allowed; the engine prepares an empty queue
+  /// and `currentMediaItemIndex` returns `-1` until items arrive
+  /// via `setItems` / `insertItems`.
+  func prepare(
+    items: [AVPlayerItem],
+    startIndex: Int,
+    startPositionSeconds: TimeInterval
+  ) async
+
+  /// Release the underlying player(s) and stop all background work.
+  /// After `release`, no further methods are valid.
+  func release()
+
+  // MARK: - Queue mutation
+
+  /// Drain the queue and re-install the slice of [items] from
+  /// [startIndex] onward. Items before [startIndex] are not held —
+  /// `AVQueuePlayer` is forward-only and the canonical queue model
+  /// lives on `TrackPlayer`. After the call,
+  /// `allMediaItems.count == max(0, items.count - startIndex)`.
+  /// Active index resolves to `items[startIndex]` at
+  /// [startPositionSeconds].
+  ///
+  /// `removeAllItems()` runs unconditionally before the slice
+  /// install. Empty [items], [startIndex] out of range, or
+  /// [startIndex] >= items.count all leave the queue drained.
+  /// Player rate is captured pre-drain and restored post-install
+  /// so a `playing → setItems → still-playing` sequence survives
+  /// the rebuild.
+  ///
+  /// `GaplessEngine` implementation: `removeAllItems` + insert loop
+  /// + seek. `CrossfadeEngine` implementation: assign queue snapshot
+  /// + active-index tracking; leading leg loads items[startIndex],
+  /// standby preroll arms for items[startIndex + 1] when applicable.
+  ///
+  /// Caller (`TrackPlayer`) constructs `[AVPlayerItem]` via
+  /// `AVQueueBuilder` so consumer config (HTTP headers, user-agent,
+  /// lookahead-cache file:// rewrites) is applied before items
+  /// reach the engine.
+  func setItems(
+    _ items: [AVPlayerItem],
+    startIndex: Int,
+    startPositionSeconds: TimeInterval
+  )
+
+  /// Surgically insert [items] after [after]. `nil` [after]
+  /// appends to the END of the queue (matches
+  /// `AVQueuePlayer.insert(_:after:)`'s contract: `nil` afterItem
+  /// → end of queue).
+  ///
+  /// Returns `true` when the engine accepted every item without
+  /// falling back to a full rebuild. Returns `false` when the
+  /// engine could not honour the surgical insert (`AVQueuePlayer.canInsert`
+  /// returned false on at least one item, or the standby leg
+  /// could not absorb the new item) — the caller treats `false`
+  /// as a signal to invoke `setItems` with the authoritative
+  /// queue snapshot.
+  @discardableResult
+  func insertItems(
+    _ items: [AVPlayerItem],
+    after: AVPlayerItem?
+  ) -> Bool
+
+  /// Remove [item] from the engine's queue. Removing the current
+  /// item on `GaplessEngine` triggers `AVQueuePlayer` auto-advance
+  /// to the next queued item; on `CrossfadeEngine` removing the
+  /// leading leg's item triggers boundary handoff + standby
+  /// promotion. No-op when [item] is not present.
+  func remove(_ item: AVPlayerItem)
+
+  /// Remove every item from the queue. After this call,
+  /// `currentMediaItem == nil` and `allMediaItems` is empty. Used
+  /// by `TrackPlayer.fullRebuildPlayerQueue` before re-inserting
+  /// the post-mutation queue snapshot.
+  func removeAllItems()
+
+  /// Whether [item] can be inserted after [after] without
+  /// disrupting playback. Mirrors `AVQueuePlayer.canInsert`:
+  /// `nil` [after] checks insert-at-end of the queue.
+  /// `CrossfadeEngine` returns `true` when the standby leg can
+  /// accept the item.
+  func canInsert(_ item: AVPlayerItem, after: AVPlayerItem?) -> Bool
+
+  // MARK: - Transport
+
+  func play()
+  func pause()
+  func stop()
+  func seek(toIndex index: Int, position: TimeInterval)
+  func skipToNext()
+  func skipToPrevious()
+
+  // MARK: - Config
+
+  func setVolume(_ volume: Float)
+  func setPlaybackSpeed(_ speed: Float)
+  /// Set the persisted playback speed WITHOUT touching the live rate
+  /// (so it won't start a paused player — `setPlaybackSpeed` sets
+  /// `AVPlayer.rate`, which would). `play()` applies it on the next
+  /// resume. Used to carry the user's speed into a freshly-built engine
+  /// at configure / engine-swap-while-paused without auto-starting.
+  func seedPlaybackSpeed(_ speed: Float)
+  func setRepeatMode(_ mode: RepeatMode)
+  /// Set how pitch behaves when speed != 1.0. The engine stamps the
+  /// resolved `AVAudioTimePitchAlgorithm` on its live item(s) and on
+  /// every item it later attaches. Non-local engines (cast / AirPlay)
+  /// no-op — the receiver owns its own rendering.
+  func setPitchCorrectionMode(_ mode: PitchCorrectionMode)
+
+  // MARK: - State
+
+  /// Current item index within the engine's queue. Returns `-1`
+  /// when the queue is empty (matches the canonical sentinel in
+  /// `TrackPlayer`). When non-empty, mirrors the AVQueuePlayer's
+  /// resolved index.
+  var currentMediaItemIndex: Int { get }
+  var currentPositionSeconds: TimeInterval { get }
+  var currentDurationSeconds: TimeInterval { get }
+  var bufferedPositionSeconds: TimeInterval { get }
+  var isPlaying: Bool { get }
+  /// The underlying player's time-control status. Drives the unified
+  /// `PlayerState` derivation (`PlayerStateDerivation`), so
+  /// `.waitingToPlayAtSpecifiedRate` (initial load / rebuffer) surfaces as
+  /// `.buffering`. Crossfade reports the active leg's status.
+  var timeControlStatus: AVPlayer.TimeControlStatus { get }
+  var currentMediaItem: AVPlayerItem? { get }
+
+  /// Snapshot of every queued `AVPlayerItem`. Called rarely
+  /// (engine swap, diagnostic dumps); impl may allocate. The
+  /// canonical queue model lives on `TrackPlayer`; engines do not
+  /// duplicate it for hot-path reads.
+  var allMediaItems: [AVPlayerItem] { get }
+
+  // MARK: - Effect chain
+
+  /// Set the single active `AudioMixProvider`. The engine consults
+  /// it when building or refreshing each `AVPlayerItem`'s
+  /// `audioMix`. Setting `nil` detaches; calling with a fresh
+  /// provider replaces the previous one. The engine holds the
+  /// provider strongly until it is replaced or set to `nil`.
+  ///
+  /// Single-slot by design — equalizer + visualizer share a single
+  /// `MTAudioProcessingTap` chain inside one provider rather than
+  /// composing multiple providers.
+  func setAudioMixProvider(_ provider: AudioMixProvider?)
+
+  /// Re-evaluate every existing item's `audioMix` by re-asking the
+  /// active provider for each. Called by the provider when its
+  /// internal state changes (e.g. EQ enable / disable toggle).
+  /// No-op when no provider is set.
+  func refreshAllItemMixes()
+
+  // MARK: - Handoff
+
+  /// Hand playback off to [nextEngine] when the user changes
+  /// `PlaybackMode`.
+  ///
+  /// Contract:
+  ///  - The receiver inherits the donor's queue, current index, and
+  ///    current position; the caller does NOT pre-call `prepare` on
+  ///    [nextEngine].
+  ///  - When [atTrackBoundary] is `true`, the donor plays the
+  ///    active track to its natural end and the receiver starts
+  ///    playing the NEXT queue position fresh.
+  ///  - When [atTrackBoundary] is `false` (idle player or empty
+  ///    queue), the swap is immediate; receiver picks up at the
+  ///    inherited position.
+  ///  - The donor's `release` is the caller's responsibility AFTER
+  ///    the boundary fires; the engine itself does not self-release.
+  func handoff(to nextEngine: PlaybackEngine, atTrackBoundary: Bool) async
+
+  // MARK: - Delegate
+
+  /// Single delegate receiving state / track / progress / error /
+  /// queue-end events. `TrackPlayer` is the canonical delegate;
+  /// engines fire on the main actor.
+  ///
+  /// Threading: setter MUST be invoked on the main actor to avoid
+  /// a write-vs-fire race during `handoff`.
+  var delegate: PlaybackEngineDelegate? { get set }
+}
+
+/// Engine → TrackPlayer event channel.
+///
+/// Delivers raw AVFoundation-flavored signals; the delegate
+/// (typically `TrackPlayer`) consults the canonical queue model +
+/// lib-internal pending-reason flags to compute the JS-facing event
+/// shape. The Android counterpart fires structurally similar
+/// callbacks with Media3-flavored parameters in `PlaybackEngine.kt`.
+protocol PlaybackEngineDelegate: AnyObject {
+
+  /// Fires when the player's effective state may have changed
+  /// (rate / status / timeControlStatus transitioned). The delegate
+  /// consults [engine] state, the canonical queue model, and
+  /// lib-internal pending-reason flags to compute the emitted
+  /// `PlayerState`.
+  ///
+  /// [reason] carries the lib's typed `StateChangeReason` when the
+  /// underlying signal was an interruption / route-change / focus
+  /// event the engine has already classified. The delegate stamps
+  /// it onto its own pending-reason channel before `PlayerState`
+  /// dedup runs. `nil` when the signal came from a generic
+  /// `rate` / `status` / `timeControlStatus` change with no
+  /// classification — the delegate preserves any previously-stamped
+  /// pending reason in that case.
+  func engineStateMaybeChanged(
+    _ engine: PlaybackEngine,
+    reason: StateChangeReason?
+  )
+
+  /// Fires when the underlying player's `timeControlStatus`
+  /// transitions to / from `.playing`. Drives diagnostics +
+  /// progress-tick wake-up.
+  func engineIsPlayingChanged(_ engine: PlaybackEngine, isPlaying: Bool)
+
+  /// Fires on `AVPlayer.currentItem` KVO when the active item
+  /// changes (auto-advance, user skip, queue replace). The
+  /// delegate translates against its own state machine (e.g.
+  /// consuming a pending user-skip reason).
+  func engineDidTransitionTrack(_ engine: PlaybackEngine)
+
+  /// Fires when the active item's `tracks` populate with format
+  /// details (codec / sample rate / channel count / bitrate). Drives
+  /// `TrackPlayer.refreshNowPlayingFormatForActiveItem`. Android
+  /// counterpart fires on `Player.Listener.onTracksChanged`.
+  func engineActiveItemFormatChanged(_ engine: PlaybackEngine)
+
+  /// Fires on a player item failure (`AVPlayerItem.failedToPlayToEndTime`
+  /// or `AVPlayerItem.status == .failed`). The delegate maps the
+  /// underlying `Error` via the lib's `PlaybackErrorMapping`.
+  func engineDidFailWithError(_ engine: PlaybackEngine, error: Error)
+
+  /// Fires on every `AVPlayerItemDidPlayToEndTime` — i.e. each
+  /// item's natural end, including non-terminal items in a queue.
+  /// Drives the gapless-gap timing log (DEBUG-only diagnostic) and
+  /// is the iOS counterpart of Android's
+  /// `onAutoTransitionDiscontinuity`.
+  func engineDidPlayItemToEnd(_ engine: PlaybackEngine)
+
+  /// Fires when the queue ends naturally — the LAST item's
+  /// `didPlayToEndTime` with no further items + repeat mode allows
+  /// completion. The delegate consults the canonical queue model
+  /// + repeat mode to decide whether this is queue-end or a
+  /// per-track end that should be ignored. Note that
+  /// [engineDidPlayItemToEnd] fires for the same item; this
+  /// callback fires AFTER it for the queue-end case only.
+  func enginePlaybackEnded(_ engine: PlaybackEngine)
+
+  /// Fires when a crossfade begins ramping — i.e. the standby
+  /// player has started playback at volume 0 and the leading leg's
+  /// fade-out has begun. The delegate treats this as the canonical
+  /// "active track changed" trigger and emits `onTrackChange` +
+  /// repoints `MPNowPlayingInfoCenter` to the incoming track. The
+  /// subsequent `engineDidTransitionTrack` for the same incoming
+  /// index is a structural KVO echo and must be deduplicated.
+  ///
+  /// Crossfade-only — `GaplessEngine` never invokes this.
+  /// `incomingIndex` is the global queue index of the fading-in
+  /// track.
+  func engineCrossfadeDidBegin(_ engine: PlaybackEngine, incomingIndex: Int)
+
+  /// Fires when an in-flight crossfade is cancelled before
+  /// `swapRoles` runs (pause / stop / audio-focus loss / queue
+  /// mutation that invalidates the standby leg). The delegate
+  /// reverts JS-facing state to the leading leg — emit
+  /// `onTrackChange(reason: .crossfadeCancelled)` for the leading
+  /// track + repoint `MPNowPlayingInfoCenter` back. Pairs with
+  /// `engineCrossfadeDidBegin`: only fires when a `DidBegin` was
+  /// fired earlier and the fade did not complete.
+  ///
+  /// Crossfade-only. `revertedIndex` is the leading-leg index that
+  /// is now the active track.
+  func engineCrossfadeDidCancel(_ engine: PlaybackEngine, revertedIndex: Int)
+}
+
+/// Single-slot audio-mix provider. The equalizer + visualizer share
+/// a single provider that builds an `MTAudioProcessingTap`-backed
+/// `AVAudioMix` per `AVPlayerItem` the engine constructs.
+///
+/// `audioMix(for:)` is called on the main thread; implementations
+/// may allocate freshly or cache + reuse. Returning `nil` skips
+/// attachment for that item — used to bypass mix on items that
+/// don't support a tap (HLS sources).
+protocol AudioMixProvider: AnyObject {
+  /// Build the audio mix for [item], or return `nil` to skip.
+  func audioMix(for item: AVPlayerItem) -> AVAudioMix?
+}

package/ios/PlaybackErrorMapping.swift

@@ -0,0 +1,195 @@
+import AVFoundation
+import Foundation
+
+/// iOS-side mapping from raw `NSError` (AVFoundation / NSURLError /
+/// CoreMedia / etc.) into the lib-standardized `PlaybackErrorCode`
+/// vocabulary. Pure function; no `TrackPlayer` instance state.
+///
+/// Mirrors `PlaybackErrorMapping.kt` on the Android side. Both
+/// implementations consult the standardized code (not the raw native
+/// code) to drive the transient/fatal classifier so the
+/// retry-eligibility contract is platform-agnostic.
+///
+/// **Two-tier classifier for AVFoundation `CANNOT_OPEN`:** the user-
+/// reported "Cannot Open" string is fired both for genuine transient
+/// failures (slow-to-respond server triggering the AVError fallback)
+/// and for permanent corruption. We classify CANNOT_OPEN as transient
+/// ONLY when the underlying error chain contains an `NSURLErrorDomain`
+/// entry (i.e. wrapped network failure); bare AVError -11800 with no
+/// network underlying is treated as fatal.
+public enum PlaybackErrorMapping {
+
+  /// Classify an `NSError` (or nil for the catch-all "no underlying")
+  /// case into the lib-standardized code.
+  public static func classify(_ underlying: NSError?) -> PlaybackErrorCode {
+    guard let err = underlying else { return .cannotOpen }
+
+    switch err.domain {
+    case NSURLErrorDomain:
+      return classifyNSURLError(err.code)
+    case AVFoundationErrorDomain:
+      return classifyAVFoundationError(err)
+    default:
+      // CoreMediaErrorDomain, kCFErrorDomain, etc. — no specific
+      // mapping today; fall through to UNKNOWN so consumers see the
+      // raw nativeCode + nativeDomain via the rich PlaybackError
+      // shape rather than a misleading lib-standardized code.
+      return .unknown
+    }
+  }
+
+  /// Whether the lib should retry on this code automatically (subject
+  /// to `PlayerConfig.autoRetries`). Codec / format / auth errors
+  /// never recover; network errors typically do.
+  public static func isTransient(_ code: PlaybackErrorCode) -> Bool {
+    switch code {
+    case .timeout, .connectionLost, .networkUnreachable,
+         .sourceUnreachable, .cannotOpen, .unknown:
+      return true
+    case .httpError, .authError, .cleartextNotPermitted,
+         .fileFormatNotRecognized, .decoderNotFound, .decodingFailed:
+      return false
+    }
+  }
+
+  /// Strip query strings from a native error message so logged
+  /// `nativeMessage` doesn't carry auth tokens (Subsonic-style
+  /// `s=…&t=…` salt+token pairs in stream URLs end up inside
+  /// `localizedDescription` strings).
+  ///
+  /// Walks the entire message, removing every `?…(whitespace|end)`
+  /// run so a multi-URL error message ("redirect from
+  /// `https://a.com/x?token=A` failed; trying
+  /// `https://b.com/y?token=B` ...") has BOTH query strings stripped.
+  @_spi(QueuePlayerTests)
+  public static func stripQuery(_ message: String) -> String {
+    var result = ""
+    var idx = message.startIndex
+    while idx < message.endIndex {
+      if message[idx] == "?" {
+        // Find next whitespace (or end) and skip the run.
+        idx = message[idx...].firstIndex(where: { $0.isWhitespace }) ?? message.endIndex
+      } else {
+        result.append(message[idx])
+        idx = message.index(after: idx)
+      }
+    }
+    return result
+  }
+
+  // MARK: - Test-friendly "Raw" surface
+  //
+  // NOTES.md §6: Swift's `-cxx-interoperability-mode=default` hides
+  // members of functions whose signatures touch Nitrogen-generated
+  // C++-backed types when viewed from a different Swift module.
+  // `classify` / `isTransient` reference `PlaybackErrorCode` — a
+  // Nitrogen type — so XCTest can't reach them directly. Provide a
+  // parallel surface that takes/returns Strings (the enum's
+  // stringValue) for unit-test access. Production code uses the
+  // typed surface above; tests use the Raw surface.
+
+  /// Test-only string-returning variant of `classify`.
+  @_spi(QueuePlayerTests)
+  public static func classifyRaw(_ underlying: NSError?) -> String {
+    return classify(underlying).stringValue
+  }
+
+  /// Test-only string-input variant of `isTransient`.
+  @_spi(QueuePlayerTests)
+  public static func isTransientRaw(_ codeString: String) -> Bool {
+    guard let code = PlaybackErrorCode(fromString: codeString) else { return false }
+    return isTransient(code)
+  }
+
+  /// Test-only string-input variant of `messageFor`.
+  @_spi(QueuePlayerTests)
+  public static func messageForRaw(_ codeString: String) -> String {
+    guard let code = PlaybackErrorCode(fromString: codeString) else { return "" }
+    return messageFor(code)
+  }
+
+  /// Lib-mapped human-readable message for a standardized code. Used
+  /// when the consumer doesn't want to render the raw native message
+  /// (which can be platform-jargon-heavy). Consistent across iOS +
+  /// Android.
+  public static func messageFor(_ code: PlaybackErrorCode) -> String {
+    switch code {
+    case .timeout: return "Network request timed out."
+    case .connectionLost: return "Network connection lost."
+    case .networkUnreachable: return "Network unreachable."
+    case .httpError: return "Server returned an error response."
+    case .authError: return "Authentication required or rejected."
+    case .cleartextNotPermitted: return "Cleartext HTTP not permitted by app transport policy."
+    case .fileFormatNotRecognized: return "Audio format not recognized."
+    case .decoderNotFound: return "No decoder available for this audio format."
+    case .decodingFailed: return "Audio decoder failure."
+    case .sourceUnreachable: return "Audio source could not be reached."
+    case .cannotOpen: return "Audio source could not be opened."
+    case .unknown: return "Playback failed."
+    }
+  }
+
+  // MARK: - Private mapping helpers
+
+  private static func classifyNSURLError(_ code: Int) -> PlaybackErrorCode {
+    switch code {
+    case NSURLErrorTimedOut:
+      return .timeout
+    case NSURLErrorNotConnectedToInternet,
+         NSURLErrorDNSLookupFailed,
+         NSURLErrorCannotFindHost,
+         NSURLErrorInternationalRoamingOff,
+         NSURLErrorDataNotAllowed,
+         NSURLErrorCallIsActive:
+      return .networkUnreachable
+    case NSURLErrorNetworkConnectionLost,
+         NSURLErrorCannotConnectToHost,
+         NSURLErrorRequestBodyStreamExhausted:
+      return .connectionLost
+    case NSURLErrorBadURL,
+         NSURLErrorUnsupportedURL,
+         NSURLErrorFileDoesNotExist,
+         NSURLErrorFileIsDirectory:
+      return .sourceUnreachable
+    case NSURLErrorAppTransportSecurityRequiresSecureConnection:
+      return .cleartextNotPermitted
+    case NSURLErrorUserAuthenticationRequired,
+         NSURLErrorClientCertificateRequired:
+      return .authError
+    default:
+      return .unknown
+    }
+  }
+
+  private static func classifyAVFoundationError(_ err: NSError) -> PlaybackErrorCode {
+    // Raw AVError code constants from <AVFoundation/AVError.h>. Using
+    // raw Ints (not AVError.Code rawValues) because Swift overlay
+    // case-name coverage varies across SDK versions; these constants
+    // are stable + documented.
+    switch err.code {
+    case -11828,  // AVErrorFileFormatNotRecognized
+         -11829,  // AVErrorFailedToParse
+         -11852:  // AVErrorContentIsNotAuthorized
+      return .fileFormatNotRecognized
+    case -11833,  // AVErrorDecoderNotFound
+         -11839:  // AVErrorDecoderTemporarilyUnavailable
+      return .decoderNotFound
+    case -11800,  // AVErrorUnknown (generic decoding fall-through)
+         -11849:  // AVErrorContentIsProtected
+      return .decodingFailed
+    case -11867,  // AVErrorNoLongerPlayable
+         -11819:  // AVErrorMediaServicesWereReset
+      return .cannotOpen
+    default:
+      // Two-tier classifier: bare AVError without a wrapped
+      // NSURLErrorDomain underlying is fatal (e.g. real corruption).
+      // AVError WITH a network underlying surfaces as transient
+      // CANNOT_OPEN so auto-retry can handle slow-server cases.
+      if let inner = err.userInfo[NSUnderlyingErrorKey] as? NSError,
+         inner.domain == NSURLErrorDomain {
+        return .cannotOpen  // transient classifier in `isTransient`
+      }
+      return .unknown
+    }
+  }
+}