react-native-queue-player 1.2.0 → 2.0.0

package/ios/NetworkRecoveryPolicy.swift

@@ -0,0 +1,32 @@
+import Foundation
+
+/// Whether the network returning should trigger a retry.
+///
+/// Pure and primitive-typed so it can be asserted directly: the player state
+/// it derives from is a Nitrogen-backed type, whose members are not reachable
+/// from the test module under cxx-interop.
+enum NetworkRecoveryPolicy {
+
+  /// - Parameters:
+  ///   - wantsToPlay: the user's transport intent.
+  ///   - isInterrupted: whether an audio-session interruption is in force.
+  ///   - isInError: whether the current track has a failure that has not
+  ///     recovered. Read from the error key rather than the reported state:
+  ///     the state has moved on by the time a network returns.
+  ///   - isTransient: whether that failure is one a network can cure
+  ///     (`PlaybackErrorMapping.isTransient`). A codec, format or auth
+  ///     failure is not, and rebuilding it on every network edge would
+  ///     re-surface the same error each time.
+  ///
+  /// All four must hold. Intent alone would start audio that was never
+  /// playing when the network happens to change; ignoring the interruption
+  /// would start it mid-call; without the error check every interface
+  /// handoff would rebuild a perfectly healthy item; and without the
+  /// transient check a fatal failure would be retried without end.
+  @_spi(QueuePlayerTests)
+  public static func shouldRetry(
+    wantsToPlay: Bool, isInterrupted: Bool, isInError: Bool, isTransient: Bool
+  ) -> Bool {
+    wantsToPlay && !isInterrupted && isInError && isTransient
+  }
+}

package/ios/NowPlayingFormatExtractor.swift

@@ -29,6 +29,7 @@ enum NowPlayingFormatExtractor {
     // strict concurrency. Hop to main for the read; the remainder of
     // this function works against the captured asset reference.
     let asset: AVAsset = await MainActor.run { item.asset }
+    let sourceURL: String? = await MainActor.run { item.sourceURL }
     let tracks: [AVAssetTrack]
     do {
       tracks = try await asset.load(.tracks)
@@ -72,7 +73,10 @@ enum NowPlayingFormatExtractor {
       if asbd.mBitsPerChannel > 0 { bitsPerChannel = Double(asbd.mBitsPerChannel) }
     }
 
-    let url = (asset as? AVURLAsset)?.url
+    // The media's URL, not the transport's: a routed track's asset URL is the
+    // read-through server's, which has no extension to map a container from
+    // and is never a file URL even when the bytes come off local disk.
+    let url = sourceURL.flatMap { URL(string: $0) } ?? (asset as? AVURLAsset)?.url
     let container = mapContainer(url: url)
     let mimeType = mapMimeType(codec: codec)
     var bitrate: Double? = estimatedDataRate > 0 ? Double(estimatedDataRate) : nil
@@ -82,15 +86,16 @@ enum NowPlayingFormatExtractor {
     //    (`kAudioFilePropertyBitRate`) — reliable for CBR, average
     //    for VBR-with-Xing. MP3-specific because the local-file
     //    AudioFile API needs the format hint up-front.
-    // 2. Streaming http(s):// of any codec: `StreamingBitrateProbe`
-    //    issues a Range:0-65535 fetch and parses via Core Audio's
-    //    `AudioFileStream` (codec-agnostic). Apple does not expose
-    //    a reliable bitrate field for progressive streams via
-    //    AVFoundation; the probe fills the gap.
-    // 3. HLS or any other streaming source the probe couldn't
-    //    parse: `event.averageAudioBitrate` / `event.indicatedBitrate`
-    //    from the AVPlayer access log — surfaces a real value for
-    //    HLS variants whose playlist declares BANDWIDTH.
+    // 2. Local file:// of any other codec: `StreamingBitrateProbe`
+    //    reads a 256 KB prefix off disk and derives a rate via Core
+    //    Audio's `AudioFileStream` (codec-agnostic).
+    // 3. Remote http(s)://, any codec: `event.averageAudioBitrate` /
+    //    `event.indicatedBitrate` from the AVPlayer access log —
+    //    surfaces a real value for HLS variants whose playlist
+    //    declares BANDWIDTH, and for progressive servers that declare
+    //    one. A remote source whose server declares nothing has no
+    //    bitrate: `estimatedDataRate` reports 0 and nothing reads the
+    //    container header off the wire.
     if bitrate == nil, let url = url {
       if url.isFileURL {
         // Local file: try Core Audio's `AudioFile`-based reader
@@ -98,8 +103,7 @@ enum NowPlayingFormatExtractor {
         // single property read). Falls back to the
         // `AudioFileStream` packet-derived probe for codecs
         // without a dedicated reader OR when AudioFile returned
-        // 0 (some transcoded MP3s — the lookahead cache's
-        // Subsonic-served files exhibit this).
+        // 0 (some server-transcoded MP3s).
         if codec == .mp3 {
           bitrate = await readLocalMP3Bitrate(url: url)
         }
@@ -111,10 +115,13 @@ enum NowPlayingFormatExtractor {
         }
       } else if let scheme = url.scheme?.lowercased(),
                 scheme == "http" || scheme == "https" {
-        bitrate = await StreamingBitrateProbe.bitrate(forUrl: url)
-        if bitrate == nil, codec == .mp3 {
-          bitrate = readStreamingMP3Bitrate(item: item)
-        }
+        // Remote: nothing here reads bytes off the wire. The library issues
+        // no side-band range request for a remote track, so the only source
+        // is what the player itself reports — the access log, which declares
+        // a bitrate for HLS variants and for progressive servers that send
+        // one. Not gated on codec: the access log reports whatever the player
+        // negotiated, and MP3 is neither the only nor the usual codec.
+        bitrate = readStreamingBitrate(item: item)
       }
     }
 
@@ -310,7 +317,7 @@ enum NowPlayingFormatExtractor {
       } catch {
         return nil
       }
-      guard let info = MetadataReader.parseFLACStreamInfo(header) else {
+      guard let info = FLACStreamInfo.parse(header) else {
         return nil
       }
       guard info.sampleRate > 0, info.totalSamples > 0 else { return nil }
@@ -351,7 +358,7 @@ enum NowPlayingFormatExtractor {
   /// main); `AVPlayerItem.accessLog()` returns a snapshot and is
   /// safe to call from any thread, matching the off-main usage in
   /// `TrackPlayer.swift`'s DEBUG access-log timeline logger.
-  static func readStreamingMP3Bitrate(item: AVPlayerItem) -> Double? {
+  static func readStreamingBitrate(item: AVPlayerItem) -> Double? {
     guard let event = item.accessLog()?.events.last else { return nil }
     let avgAudio: Double = event.averageAudioBitrate
     if avgAudio.isFinite, avgAudio > 0 { return avgAudio }

package/ios/NowPlayingInfo.swift

@@ -18,15 +18,18 @@ import MediaPlayer
 /// interpolation honest across long-running playback, rate changes, and
 /// background-thread suspensions.
 ///
-/// Threading: every public method MUST be called from the main thread.
-/// Callers in `TrackPlayer` either run inside `onMain {}` or are invoked
-/// from KVO bodies that have already async-hopped to main.
+/// Threading: callable from any queue. Every public method hands its work
+/// to main, which owns both the Now Playing surface and this object's state;
+/// `TrackPlayer` calls in from `playerQueue`. Player state
+/// is pushed in as a `Snapshot` argument — this writer never reads
+/// player state itself, so it holds no synchronous read edge back into
+/// whichever context owns that state.
 final class NowPlayingInfo {
 
-  /// Snapshot of player state at emit time. The provider closure is
-  /// responsible for reading every field within the same main-thread
-  /// tick — divergent values (elapsed taken at t0, rate at t0+Δ) show
-  /// up on the lock-screen scrubber as jitter.
+  /// Snapshot of player state at emit time. The caller is responsible
+  /// for reading every field within the same tick — divergent values
+  /// (elapsed taken at t0, rate at t0+Δ) show up on the lock-screen
+  /// scrubber as jitter.
   struct Snapshot {
     let track: TrackItem?
     /// Current playback position in seconds. NaN / ±Inf coerce to 0.
@@ -34,15 +37,13 @@ final class NowPlayingInfo {
     /// Total duration in seconds. NaN / ±Inf / ≤0 → omit (signals
     /// live-stream / unknown to the system).
     let durationSeconds: Double
-    /// `AVPlayer.rate`. 0 paused, 1 playing at speed, etc.
+    /// Effective playback rate: the configured speed while playing, 0
+    /// otherwise. Not the player's requested rate, which is non-zero while
+    /// waiting to play and would extrapolate the scrubber through a stall.
     let rate: Float
   }
 
-  /// Provider read on every emit. Owner sets it during `configure()`
-  /// and clears it during `destroy()`.
-  var snapshotProvider: (() -> Snapshot)?
-
-  private var periodicTimer: Timer?
+  private var periodicTimer: DispatchSourceTimer?
   /// Subscription to the global cast active-session router. When a
   /// remote session is active, `CastNowPlayingController` owns the
   /// lockscreen surface and this writer becomes a no-op — every
@@ -54,21 +55,38 @@ final class NowPlayingInfo {
   init() {
     castRouterDisposer = PlaybackStateRouter.shared.addActiveChangeListener {
       [weak self] session in
-      self?.castActive = (session != nil)
+      let active = (session != nil)
+      NowPlayingInfo.onMain { self?.castActive = active }
     }
   }
 
+  /// Hands `body` to main, where this object's state and the Now Playing
+  /// surface both live. Always asynchronous, never inline-when-already-on-main:
+  /// mixing the two lets a later write land before an earlier one, and the
+  /// surface is last-write-wins.
+  private static func onMain(_ body: @escaping @MainActor () -> Void) {
+    DispatchQueue.main.async { MainActor.assumeIsolated(body) }
+  }
+
   deinit {
     castRouterDisposer?()
+    // libdispatch retains an armed source, so one that is never cancelled
+    // keeps waking the main queue for the life of the process.
+    periodicTimer?.cancel()
   }
 
   /// Full refresh — metadata + position + rate. Call on track-change.
-  /// A nil snapshot or a snapshot with `track == nil` (queue empty /
-  /// pre-first-track) clears the dictionary so the lock-screen /
-  /// control-center surface goes away.
-  func refreshAll() {
+  /// A snapshot with `track == nil` (queue empty / pre-first-track)
+  /// clears the dictionary so the lock-screen / control-center surface
+  /// goes away.
+  func refreshAll(_ snapshot: Snapshot) {
+    NowPlayingInfo.onMain { self.refreshAllOnMain(snapshot) }
+  }
+
+  @MainActor
+  private func refreshAllOnMain(_ snapshot: Snapshot) {
     if castActive { return }
-    guard let snapshot = snapshotProvider?(), snapshot.track != nil else {
+    guard snapshot.track != nil else {
       MPNowPlayingInfoCenter.default().nowPlayingInfo = nil
       return
     }
@@ -90,13 +108,16 @@ final class NowPlayingInfo {
   /// an artwork-only payload.
   ///
   /// `boundsSize: image.size` and `requestHandler` returning the
-  /// image unchanged matches the canonical SwiftAudioEx /
-  /// react-native-track-player pattern (and Substreamer's real-car
-  /// behaviour). The system handles size negotiation; over-engineering
-  /// the handler (forced 1024² canvas + aspect-fit render) was tested
-  /// and found to make no difference on the standalone CarPlay
-  /// Simulator's main-art region.
+  /// image unchanged is the shape `MPMediaItemArtwork` documents; the
+  /// system handles size negotiation. A forced 1024² canvas with an
+  /// aspect-fit render makes no difference to the CarPlay main-art
+  /// region.
   func applyArtwork(_ image: UIImage) {
+    NowPlayingInfo.onMain { self.applyArtworkOnMain(image) }
+  }
+
+  @MainActor
+  private func applyArtworkOnMain(_ image: UIImage) {
     if castActive { return }
     guard var info = MPNowPlayingInfoCenter.default().nowPlayingInfo else { return }
     info[MPMediaItemPropertyArtwork] = MPMediaItemArtwork(boundsSize: image.size) { _ in image }
@@ -116,9 +137,14 @@ final class NowPlayingInfo {
   /// surface stays absent until this method's late re-publish lands
   /// (typically ~100-500ms after play starts, via the state-change
   /// dispatch in [TrackPlayer]).
-  func refreshPositionAndRate() {
+  func refreshPositionAndRate(_ snapshot: Snapshot) {
+    NowPlayingInfo.onMain { self.refreshPositionAndRateOnMain(snapshot) }
+  }
+
+  @MainActor
+  private func refreshPositionAndRateOnMain(_ snapshot: Snapshot) {
     if castActive { return }
-    guard let snapshot = snapshotProvider?(), snapshot.track != nil else { return }
+    guard snapshot.track != nil else { return }
     guard var info = MPNowPlayingInfoCenter.default().nowPlayingInfo else { return }
     applyPositionAndRate(snapshot, into: &info)
     if snapshot.durationSeconds.isFinite && snapshot.durationSeconds > 0 {
@@ -130,31 +156,41 @@ final class NowPlayingInfo {
   /// Stops the periodic timer and clears the dictionary. Call on
   /// `destroy()` before the audio session deactivates.
   func clear() {
-    stopPeriodicTimer()
-    MPNowPlayingInfoCenter.default().nowPlayingInfo = nil
-  }
-
-  /// Schedule the 10s periodic refresh on the main run loop. Idempotent.
-  /// `tolerance = 1.0` lets the OS coalesce with other timers without
-  /// affecting scrubber accuracy (the system extrapolates from elapsed
-  /// + rate between emits). The closure short-circuits when the player
-  /// is paused — elapsed is unchanged and rate is already 0, so the
-  /// write would be pure noise.
-  func startPeriodicTimer() {
-    stopPeriodicTimer()
-    let timer = Timer(timeInterval: 10, repeats: true) { [weak self] _ in
-      guard let self,
-            let snapshot = self.snapshotProvider?(),
-            snapshot.rate != 0 else { return }
-      self.refreshPositionAndRate()
+    NowPlayingInfo.onMain {
+      self.stopPeriodicTimerOnMain()
+      MPNowPlayingInfoCenter.default().nowPlayingInfo = nil
     }
-    timer.tolerance = 1.0
-    RunLoop.main.add(timer, forMode: .common)
+  }
+
+  /// Schedule the 10s periodic tick on the main queue. Restarts a running
+  /// tick rather than stacking a second one. A 1s leeway lets the OS
+  /// coalesce with other timers without affecting scrubber accuracy (the
+  /// system extrapolates from elapsed + rate between emits). `onTick`
+  /// builds the snapshot on the side that owns player state and pushes the
+  /// refresh; it carries the paused short-circuit, since only that side can
+  /// tell whether the write would be pure noise.
+  func startPeriodicTimer(onTick: @escaping () -> Void) {
+    NowPlayingInfo.onMain { self.startPeriodicTimerOnMain(onTick: onTick) }
+  }
+
+  @MainActor
+  private func startPeriodicTimerOnMain(onTick: @escaping () -> Void) {
+    stopPeriodicTimerOnMain()
+    let timer = DispatchSource.makeTimerSource(queue: .main)
+    timer.schedule(deadline: .now() + 10, repeating: 10, leeway: .seconds(1))
+    timer.setEventHandler { onTick() }
     periodicTimer = timer
+    // The source is resumed exactly once and never suspended — a suspended
+    // source traps libdispatch on release.
+    timer.resume()
   }
 
-  func stopPeriodicTimer() {
-    periodicTimer?.invalidate()
+  /// Cancel the tick source. `cancel()` is safe from any thread; calling it
+  /// on the source's own queue additionally guarantees no further tick runs
+  /// once it returns.
+  @MainActor
+  private func stopPeriodicTimerOnMain() {
+    periodicTimer?.cancel()
     periodicTimer = nil
   }
 

package/ios/OutputRouteMonitor.swift

@@ -44,7 +44,17 @@ final class OutputRouteMonitor {
   /// Latest classification. Read at engine track-boundary fire
   /// so per-transition fade-vs-cut decisions reflect the current
   /// route without depending on a callback delivery deadline.
-  private(set) var currentClass: OutputClass = .localMixable
+  ///
+  /// Written here on main as route changes arrive, read from the queue the
+  /// engine serialises on, so it carries its own lock.
+  var currentClass: OutputClass {
+    classLock.lock()
+    defer { classLock.unlock() }
+    return storedClass
+  }
+
+  private let classLock = NSLock()
+  private var storedClass: OutputClass = .localMixable
 
   /// Convenience accessor — `true` outside AirPlay 2 / CarPlay.
   var isCurrentRouteMixable: Bool {
@@ -107,8 +117,11 @@ final class OutputRouteMonitor {
     let outputs = AVAudioSession.sharedInstance().currentRoute.outputs
     let isNonMixable = outputs.contains { Self.isNonMixableOutput($0) }
     let newClass: OutputClass = isNonMixable ? .nonMixableRemote : .localMixable
-    let flipped = newClass == .nonMixableRemote && currentClass == .localMixable
-    currentClass = newClass
+    // One critical section: the flip test reads the value this write replaces.
+    classLock.lock()
+    let flipped = newClass == .nonMixableRemote && storedClass == .localMixable
+    storedClass = newClass
+    classLock.unlock()
     if flipped {
       onRouteBecameNonMixable?()
     }

package/ios/PendingBrowseRequests.swift

@@ -47,7 +47,7 @@ final class PendingBrowseRequests {
   }
 
   /// Snapshot the pending parents without consuming. Production
-  /// code drains via [drainAll]; this is a test-only seam. Stays
+  /// code drains via [drainAll]; this is for tests only. Stays
   /// `internal` (test target imports via `@testable import`) —
   /// mirrors the Kotlin `internal fun snapshotForTest` shape on
   /// the Android side.

package/ios/PlaceholderArtwork.swift

@@ -17,7 +17,7 @@ enum PlaceholderArtwork {
 
   /// The active placeholder: the consumer-supplied image when one is
   /// configured + loadable, otherwise the bundled RNQP placeholder.
-  static var image: UIImage { customImage ?? bundledImage }
+  static var image: UIImage { lock.withLock { customImage } ?? bundledImage }
 
   /// Set (or clear) the consumer-supplied placeholder from
   /// `PlayerConfig.placeholderArtworkUri`. Loaded from a local `file://`
@@ -26,17 +26,21 @@ enum PlaceholderArtwork {
   /// built-in is a local file, and a remote URL would break offline +
   /// change behaviour; anything else (or an unloadable file) leaves the
   /// bundled placeholder in effect. Decode is synchronous, so a very large
-  /// consumer image briefly blocks the `configure` call. Main-thread only
-  /// (called from `configure`).
+  /// consumer image briefly blocks the `configure` call. Called from
+  /// `configure` on the player queue; the readers are on main.
   static func setCustom(uri: String?) {
     guard let uri = uri, !uri.isEmpty,
           let url = URL(string: uri), url.scheme?.lowercased() == "file" else {
-      customImage = nil
+      lock.withLock { customImage = nil }
       return
     }
-    customImage = UIImage(contentsOfFile: url.path)
+    let image = UIImage(contentsOfFile: url.path)
+    lock.withLock { customImage = image }
   }
 
+  /// Written from `configure()` on the player queue, read wherever the
+  /// now-playing surfaces build their snapshot.
+  private static let lock = NSLock()
   private static var customImage: UIImage?
   private static let bundledImage: UIImage = loadImage()