react-native-queue-player 1.2.0 → 2.0.0

package/ios/CrossfadeEngine.swift

@@ -16,17 +16,20 @@ import Foundation
 ///   `TrackPlayer` is the canonical position; the engine
 ///   advances the standby leg's currentItem to the next queue
 ///   position ahead of fade-start.
-/// - Equal-power curve approximated via N short linear
-///   `setVolumeRamp` sub-ramps. `setVolumeRamp` is linear-only
-///   per the AVFoundation API; ~50 sub-ramps over a fade window
+/// - Equal-power curve approximated via N short `setVolumeRamp`
+///   sub-ramps. AVFoundation does not document the ramp's curve, so
+///   each sub-ramp is treated as linear; ~50 sub-ramps over a fade window
 ///   is auditorily indistinguishable from true `cos(t·π/2)` /
 ///   `sin(t·π/2)`.
 /// - Standby preroll via `AVPlayer.preroll(atRate: 1.0)` ~500ms
 ///   before fade-start so the audio output graph is hot when
 ///   its volume ramp begins.
-/// - Backward seek through a scheduled ramp window corrupts the
-///   mix per Wade Tregaskis's `setVolumeRamp` findings —
-///   recovery is `audioMix = nil` + `volume = userVolume`.
+/// - Workaround: a backward seek through a scheduled `setVolumeRamp`
+///   window leaves the mix in place and the volume wrong on the next
+///   play-through; recovery is `audioMix = nil` + `volume = userVolume`.
+///   TODO: monitor upstream for fixes —
+///   https://wadetregaskis.com/fading-audio-with-avplayer/ documents the
+///   symptom; there is no Apple Feedback number to track.
 /// - Per-boundary route check via `OutputRouteMonitor`: if the
 ///   active route is `.airPlay` / `.carAudio`, the boundary
 ///   hard-cuts (no fade) for that transition. Mid-fade route
@@ -42,8 +45,8 @@ final class CrossfadeEngine: PlaybackEngine {
 
   /// User-set fade duration captured at construction time. Both
   /// `AVAudioMix` ramp scheduling and the role-swap timer
-  /// coordinate against this value; runtime duration changes
-  /// require a fresh engine instance via `handoff`.
+  /// coordinate against this value; runtime duration changes go
+  /// through `setPlaybackMode`, which constructs a new engine.
   private let crossfadeDurationSeconds: TimeInterval
 
   /// Pre-fade preroll lead so the standby leg's audio output
@@ -51,14 +54,24 @@ final class CrossfadeEngine: PlaybackEngine {
   /// platform research recommendation.
   static let prerollLeadSeconds: TimeInterval = 0.5
 
+  /// Backstop for the part of the arm chain the status wait does not cover:
+  /// the incoming asset's `tracks` load and preroll, which begin once the
+  /// standby leg reports ready and have no bound of their own.
+  ///
+  /// Measured from that flip rather than from the arm, because an arm fires at
+  /// most `maxCrossfadeMs + prerollLeadSeconds` before the leading track ends —
+  /// a deadline measured from the arm and longer than that could only ever
+  /// expire after the boundary it exists to protect.
+  static let armDeadlineSeconds: TimeInterval = 5.0
+
   /// Equal-power approximation step count. ~50 sub-ramps over a
   /// 6-second fade is below the audibility threshold for the
   /// difference between staircased and continuous cos/sin.
   static let subRampCount: Int = 50
 
   /// Volume multiplier applied to both legs during the fade.
-  /// Tracked so manual `setVolume(v)` survives a subsequent
-  /// fade cancel / handoff.
+  /// Tracked so manual `setVolume(v)` survives a fade cancel or the
+  /// role swap at fade end.
   private var userVolume: Float = 1.0
 
   /// Tracked so the user's playback speed survives a crossfade
@@ -99,6 +112,20 @@ final class CrossfadeEngine: PlaybackEngine {
 
   // MARK: - Queue model
 
+  /// The queue the owner serialises player access on. Every callback this
+  /// engine delivers, and every timer and observer it installs, lands here —
+  /// the fade state below carries no lock, so it is only safe while one queue
+  /// owns both it and the transport calls driving it.
+  private let ownerQueue: DispatchQueue
+
+  /// Run `body` on the owner's queue and await its result, for the points
+  /// where an async fade step has to touch that state again.
+  private func onOwnerQueue<T>(_ body: @escaping () -> T) async -> T {
+    await withCheckedContinuation { (cont: CheckedContinuation<T, Never>) in
+      self.ownerQueue.async { cont.resume(returning: body()) }
+    }
+  }
+
   /// Engine-internal queue snapshot — caller sets via
   /// `setItems`; engine advances `currentIndex` on user skip /
   /// auto-advance. Each `AVPlayer` instance holds at most one
@@ -121,7 +148,9 @@ final class CrossfadeEngine: PlaybackEngine {
   /// `NSInvalidArgumentException` when called on a different
   /// instance than the one that issued the token, so the player
   /// is captured alongside the token. Removed on pause / stop /
-  /// seek / skip / role-swap / release; re-installed on play.
+  /// release / removeAllItems, and by setItems / remove when they drain
+  /// the engine; re-installed on play; stopped and restarted across
+  /// `completeCrossfade`.
   private var armingObserver: (player: AVPlayer, token: Any)?
 
   /// `true` after [armCrossfade] has prerolled standby for the
@@ -134,21 +163,11 @@ final class CrossfadeEngine: PlaybackEngine {
   /// against a fresh fade.
   private var fadeCompletionTask: Task<Void, Never>?
 
-  /// Audio-mix provider supplied by `Equalizer` (and future
-  /// `Visualizer`). Per-AVPlayerItem `AVAudioMix` is built
-  /// per-item via the provider's `audioMix(for:)`.
+  /// Audio-mix provider set via `setAudioMixProvider` — the
+  /// `AudioTapProvider` shared by `Equalizer` and `Visualizer`. Each
+  /// AVPlayerItem's `AVAudioMix` comes from its `audioMix(for:)`.
   private var mixProvider: AudioMixProvider?
 
-  /// Resolves a track's source URL to its lookahead-cache local file
-  /// URL when fully cached, else nil. Supplied by `TrackPlayer` (reads
-  /// `LookaheadCache.cachedURL(forUrl:)` lazily so it always sees the
-  /// current cache). The engine re-resolves at every late item attach
-  /// (skip cross-attach, fade-arm preroll) so a track that finished
-  /// caching AFTER its queue item was first built from the remote URL
-  /// is played from the local file — instead of re-loading the remote
-  /// asset, whose `.tracks` round-trip can fail the now-playing format
-  /// extractor.
-  private var cachedURLResolver: ((String) -> URL?)?
 
   /// Released-once flag so `release()` is idempotent.
   private var released: Bool = false
@@ -169,10 +188,27 @@ final class CrossfadeEngine: PlaybackEngine {
   /// the leading-leg error path.
   private var standbyReadyTimeout: DispatchWorkItem?
 
+  /// Deadline on the whole arm chain, not just the wait for the standby leg's
+  /// status.
+  ///
+  /// `standbyReadyTimeout` is cancelled the moment the status flips, and the
+  /// work after that — loading the incoming asset's `tracks` key — has no
+  /// bound of its own. Without this deadline a remote asset that never
+  /// resolves leaves `standbyArmed` set, and the engine work deferred on
+  /// that flag never flushes.
+  private var armDeadline: DispatchWorkItem?
+
+  /// Whether volume ramps have actually been written onto either leg's mix
+  /// parameters. Only a written ramp can leave the mix in the state
+  /// `cancelFadeInternal`'s reset recovers from, and being armed is not the
+  /// same thing: the chain can be armed and still waiting for the incoming
+  /// asset, with nothing written yet.
+  private var rampsScheduled = false
+
   /// Generation counter incremented at every [awaitStandbyReady]
   /// entry. Closures captured by the KVO observer + the timeout
   /// `DispatchWorkItem` carry their generation value — if a new
-  /// arm cycle increments the counter while a stale main-async
+  /// arm cycle increments the counter while a stale `ownerQueue`
   /// hop is pending, the gate inside the closure short-circuits.
   /// Defends against a narrow race where the original arm's
   /// `.readyToPlay` callback fires AFTER `cancelFadeInternal` +
@@ -183,7 +219,7 @@ final class CrossfadeEngine: PlaybackEngine {
 
   /// `\.timeControlStatus` KVO on the leading leg + the player it
   /// was registered against. Re-installed on every role swap.
-  /// Fires `engineStateMaybeChanged` + `engineIsPlayingChanged`.
+  /// Fires `engineStateMaybeChanged`.
   private var leadingTimeControlObserver: NSKeyValueObservation?
 
   /// `\.currentItem.tracks` KVO on the leading leg's currentItem.
@@ -195,6 +231,15 @@ final class CrossfadeEngine: PlaybackEngine {
   /// Routes `.failed` through `engineDidFailWithError`.
   private var leadingItemStatusObserver: NSKeyValueObservation?
 
+  /// `\.isPlaybackBufferEmpty` / `\.isPlaybackLikelyToKeepUp` /
+  /// `\.isPlaybackBufferFull` KVO on the leading leg's currentItem. Each fires
+  /// `engineBufferStateMaybeChanged` so a fast local reload's empty→full edge
+  /// reaches the discrete buffer-state surface — the gapless engine gets the
+  /// same from its own item KVO. Re-installed on role swap and on `setItems`.
+  private var leadingItemBufferEmptyObserver: NSKeyValueObservation?
+  private var leadingItemBufferKeepUpObserver: NSKeyValueObservation?
+  private var leadingItemBufferFullObserver: NSKeyValueObservation?
+
   /// Block-based `NotificationCenter` observer tokens for the
   /// AVPlayerItem lifecycle notifications. Filtered inside the
   /// block to leading-leg only. Removed in `release`.
@@ -203,12 +248,13 @@ final class CrossfadeEngine: PlaybackEngine {
 
   // MARK: - Init
 
-  init(crossfadeDurationSeconds: TimeInterval) {
+  init(crossfadeDurationSeconds: TimeInterval, confinedTo ownerQueue: DispatchQueue) {
     precondition(
       crossfadeDurationSeconds >= 0,
       "crossfadeDurationSeconds must be non-negative"
     )
     self.crossfadeDurationSeconds = crossfadeDurationSeconds
+    self.ownerQueue = ownerQueue
 
     let p1 = AVPlayer()
     p1.automaticallyWaitsToMinimizeStalling = true
@@ -228,9 +274,8 @@ final class CrossfadeEngine: PlaybackEngine {
       // doesn't arbitrarily silence one of the two players. The
       // outgoing leg snaps to userVolume; the standby drops its
       // item.
-      DispatchQueue.main.async { [weak self] in
-        self?.cancelFade()
-      }
+      guard let self else { return }
+      self.ownerQueue.async { self.cancelFade() }
     }
 
     // Lib-wide notifications fire for any AVPlayerItem; the
@@ -239,46 +284,27 @@ final class CrossfadeEngine: PlaybackEngine {
     itemDidPlayToEndToken = NotificationCenter.default.addObserver(
       forName: .AVPlayerItemDidPlayToEndTime,
       object: nil,
-      queue: .main
+      // `nil` delivers on the posting thread — AVFoundation's, not ours — so
+      // the hop onto the owner's queue is explicit below.
+      queue: nil
     ) { [weak self] note in
-      self?.handleItemDidPlayToEnd(note)
+      guard let self else { return }
+      self.ownerQueue.async { self.handleItemDidPlayToEnd(note) }
     }
     itemFailedToPlayToEndToken = NotificationCenter.default.addObserver(
       forName: .AVPlayerItemFailedToPlayToEndTime,
       object: nil,
-      queue: .main
+      // `nil` delivers on the posting thread — AVFoundation's, not ours — so
+      // the hop onto the owner's queue is explicit below.
+      queue: nil
     ) { [weak self] note in
-      self?.handleItemFailedToPlayToEnd(note)
+      guard let self else { return }
+      self.ownerQueue.async { self.handleItemFailedToPlayToEnd(note) }
     }
-
-    // iOS 26+ AVRoutingPlaybackArbiter would let the engine name
-    // the preferred participant for non-mixable routes (AirPlay
-    // 2 / wireless CarPlay) so iOS doesn't arbitrarily silence
-    // one of two playing AVPlayer instances during the
-    // engagement transient. The current iOS SDK in this build
-    // ships AVRoutingPlaybackArbiter but the
-    // `preferredParticipantForNonMixableAudioRoutes` property
-    // marker is unavailable on iOS at the SDK header level —
-    // tracked as a follow-up once the SDK exposes it on iOS or
-    // an alternative API surface lands.
-  }
-
-  /// No-op placeholder — see init comment for the iOS 26+
-  /// AVRoutingPlaybackArbiter follow-up.
-  private func updateRoutingArbiter() {
-    // Intentional no-op pending SDK availability.
   }
 
   // MARK: - Lifecycle
 
-  func prepare(
-    items: [AVPlayerItem],
-    startIndex: Int,
-    startPositionSeconds: TimeInterval
-  ) async {
-    setItems(items, startIndex: startIndex, startPositionSeconds: startPositionSeconds)
-  }
-
   func release() {
     guard !released else { return }
     released = true
@@ -299,6 +325,7 @@ final class CrossfadeEngine: PlaybackEngine {
       itemFailedToPlayToEndToken = nil
     }
     routeMonitor.stop()
+    AVQueueBuilder.cancelLoading(dropping: queue)
     leadingPlayer.replaceCurrentItem(with: nil)
     standbyPlayer.replaceCurrentItem(with: nil)
     queue.removeAll()
@@ -314,11 +341,24 @@ final class CrossfadeEngine: PlaybackEngine {
     startIndex: Int,
     startPositionSeconds: TimeInterval
   ) {
+    // `replaceCurrentItem` below drops the leading leg to rate 0, so a
+    // rebuild issued mid-playback would silently pause. Capture the intent
+    // and restore the rate after the new item is seated — the same contract
+    // `GaplessEngine.setItems` upholds across its own rebuild. The run
+    // resumes exactly when a `play()` is still standing over it.
+    let shouldResume = wantsPlayback
     cancelFadeInternal()
+    // The outgoing slice is discarded here. Anything the incoming set reuses
+    // keeps its loads — a cancelled asset never becomes playable, and this
+    // engine deliberately rebuilds items on reused assets at seek, remove
+    // and fade-arm.
+    AVQueueBuilder.cancelLoading(dropping: queue, keeping: items)
     queue = items
     teardownLeadingObservers()
     if items.isEmpty || startIndex < 0 || startIndex >= items.count {
       currentIndex = -1
+      stopArmingObserver()
+      leadingPlayer.pause()
       leadingPlayer.replaceCurrentItem(with: nil)
       standbyPlayer.replaceCurrentItem(with: nil)
       return
@@ -335,8 +375,10 @@ final class CrossfadeEngine: PlaybackEngine {
         completionHandler: nil
       )
     }
+    if shouldResume {
+      resumeLeadingRespectingTap()
+    }
     installLeadingObservers()
-    updateRoutingArbiter()
     delegate?.engineDidTransitionTrack(self)
   }
 
@@ -376,12 +418,24 @@ final class CrossfadeEngine: PlaybackEngine {
         currentIndex = queue.count - 1
       }
       if currentIndex < 0 {
+        stopArmingObserver()
+        leadingPlayer.pause()
         leadingPlayer.replaceCurrentItem(with: nil)
       } else {
-        let next = queue[currentIndex]
+        let shouldResume = wantsPlayback
+        teardownLeadingObservers()
+        // Never the stored instance: the slot that shifts in here may be the
+        // item the arm attached to the standby leg, and attaching an item
+        // still associated with another player raises an exception Swift
+        // cannot catch.
+        let next = rebuiltItem(at: currentIndex)
         applyMixIfNeeded(to: next)
         applyPitchAlgorithm(to: next)
         leadingPlayer.replaceCurrentItem(with: next)
+        if shouldResume {
+          resumeLeadingRespectingTap()
+        }
+        installLeadingObservers()
       }
     } else if idx < currentIndex {
       currentIndex -= 1
@@ -389,7 +443,15 @@ final class CrossfadeEngine: PlaybackEngine {
   }
 
   func removeAllItems() {
+    // Nothing left to want: an intent left standing here resumes the next run
+    // installed rather than waiting to be asked.
+    stopArmingObserver()
+    // Detaching the item does not stop the player — `replaceCurrentItem(with:
+    // nil)` leaves the rate where it was, so the next item seated on this leg
+    // would start on contact. Draining parks it.
+    leadingPlayer.pause()
     cancelFadeInternal()
+    AVQueueBuilder.cancelLoading(dropping: queue)
     queue.removeAll()
     currentIndex = -1
     leadingPlayer.replaceCurrentItem(with: nil)
@@ -406,9 +468,12 @@ final class CrossfadeEngine: PlaybackEngine {
   // MARK: - Transport
 
   func play() {
-    // Resume at the user's speed (AVPlayer.play() resets rate to 1.0).
-    leadingPlayer.rate = userPlaybackSpeed
+    // Start the arming observer first so `wantsPlayback` is true before the
+    // leading `.readyToPlay` observer might resume a leg held for its tap.
+    // `resumeLeadingRespectingTap` restores the user's speed (AVPlayer.play()
+    // would reset rate to 1.0).
     startArmingObserver()
+    resumeLeadingRespectingTap()
   }
 
   func pause() {
@@ -435,16 +500,16 @@ final class CrossfadeEngine: PlaybackEngine {
 
   func seek(toIndex index: Int, position: TimeInterval) {
     guard index >= 0, index < queue.count else { return }
-    // Capture playing intent before the fade-cancel: a cross-attach
+    // Read playing intent before the fade-cancel: a cross-attach
     // (replaceCurrentItem) drops the leading player to rate 0, so the
     // new leg must be resumed at the user's speed below to match the
     // gapless skip (which restores rate across its queue rebuild).
-    let wasPlaying = isPlaying
+    let shouldResume = wantsPlayback
     // Seek is itself a track-change: the engineDidTransitionTrack
     // fire at the end of this method is the authoritative active-
     // track flip for the new index. Suppress the cancel-revert
     // emit so a mid-fade seek doesn't dispatch an intermediate
-    // engineCrossfadeDidCancel(revertedIndex: outgoing) event
+    // `engineCrossfadeDidCancel` (a revert to the outgoing leg)
     // before the seek's own track-change lands.
     cancelFadeInternal(emitRevert: false)
     teardownLeadingObservers()
@@ -466,9 +531,13 @@ final class CrossfadeEngine: PlaybackEngine {
         // zero to honour the seek contract.
         existing.seek(to: .zero, completionHandler: nil)
       }
+      // No re-attach here, but an item that reached its end has parked its leg
+      // at rate 0, and seeking back into it must play from where it lands.
+      if shouldResume {
+        resumeLeadingRespectingTap()
+      }
       standbyArmed = false
       installLeadingObservers()
-      updateRoutingArbiter()
       delegate?.engineDidTransitionTrack(self)
       return
     }
@@ -486,20 +555,17 @@ final class CrossfadeEngine: PlaybackEngine {
     // queueItemId across so TrackPlayer.matchTrackIndex can still
     // resolve the new item back to its queue position.
     let target = AVPlayerItem(
-      // Prefer the lookahead cache's local file when the track has
-      // cached since the queue item was built from its remote URL —
-      // otherwise this fresh item re-loads the remote asset and the
-      // `.tracks` round-trip can fail the now-playing format extractor.
-      asset: cacheResolvedAsset(for: existing),
-      // Mirror AVQueueBuilder.makeItem fully — including "tracks". A forward
-      // skip to a cached track rebuilds the incoming leg here; without the
-      // tracks key auto-loading, the `.new`-only tracks KVO never fires for
-      // the fresh item and the now-playing format never resolves.
-      automaticallyLoadedAssetKeys: ["playable", "duration", "tracks"]
+      asset: existing.asset,
+      automaticallyLoadedAssetKeys: ["playable", "duration"]
     )
     target.preferredForwardBufferDuration = 0.0
     target.queueItemId = existing.queueItemId
     target.sourceURL = existing.sourceURL
+    target.suppliedReplayGain = existing.suppliedReplayGain
+    // The routing stamp lives on the item instance (associated object), not the
+    // reused asset, so carry it too — without it source classification reads the
+    // default `false` and reports a cache-served track as `.streaming`.
+    target.isRoutedThroughReadThroughServer = existing.isRoutedThroughReadThroughServer
     // Replace the queue slot with the rebuilt item — any cached
     // AVPlayerItem reference held by a future callsite (e.g. an
     // armCrossfade re-arming on this index) must read queue[index]
@@ -515,15 +581,14 @@ final class CrossfadeEngine: PlaybackEngine {
         completionHandler: nil
       )
     }
-    if wasPlaying {
-      // replaceCurrentItem leaves the player at rate 0 — resume at the
-      // user's speed (mirrors play() / completeCrossfade) so a skip while
-      // playing at a non-default speed doesn't fall back to 1.0x.
-      leadingPlayer.rate = userPlaybackSpeed
+    if shouldResume {
+      // replaceCurrentItem leaves the player at rate 0 — resume respecting a
+      // wanted tap (mirrors play() / seek) so a skip while playing at a
+      // non-default speed doesn't fall back to 1.0x and the tap survives.
+      resumeLeadingRespectingTap()
     }
     standbyArmed = false
     installLeadingObservers()
-    updateRoutingArbiter()
     delegate?.engineDidTransitionTrack(self)
   }
 
@@ -610,9 +675,12 @@ final class CrossfadeEngine: PlaybackEngine {
   }
 
   var isPlaying: Bool {
-    // Reads the leading leg unconditionally (both legs play mid-fade); the
-    // `timeControlStatus` accessor below deliberately reads the active leg
-    // (standby while fading) to match `currentMediaItem` for state derivation.
+    // Whether the outgoing leg is audible right now — not whether the engine
+    // was asked to play. It reads false mid-fade once the leading leg's item
+    // has ended, and false while a leg is buffering, so a caller deciding
+    // whether to restore a rate wants `wantsPlayback` instead. The
+    // `timeControlStatus` accessor below reads the active leg (standby while
+    // fading) to match `currentMediaItem` for state derivation.
     leadingPlayer.timeControlStatus == .playing
   }
 
@@ -629,6 +697,24 @@ final class CrossfadeEngine: PlaybackEngine {
     return player.currentItem
   }
 
+  /// The outgoing leg's item for the whole fade — `currentMediaItem` switches
+  /// to the incoming leg as soon as the fade starts, which is the wrong end to
+  /// anchor an installed run on.
+  var leadingQueueItemId: String? {
+    leadingPlayer.currentItem?.queueItemId
+  }
+
+  var isFadePendingOrActive: Bool { standbyArmed || fadeInFlight }
+
+  /// Both legs while a fade is scheduled or running: the standby leg carries a
+  /// prerolled item that is about to be heard, and a mutation that removes it
+  /// out from under the arm chain strands the fade on an item the queue no
+  /// longer has.
+  var attachedQueueItemIds: [String] {
+    [leadingPlayer.currentItem?.queueItemId, standbyPlayer.currentItem?.queueItemId]
+      .compactMap { $0 }
+  }
+
   var allMediaItems: [AVPlayerItem] {
     queue
   }
@@ -640,64 +726,29 @@ final class CrossfadeEngine: PlaybackEngine {
     refreshAllItemMixes()
   }
 
-  func setCachedURLResolver(_ resolver: ((String) -> URL?)?) {
-    cachedURLResolver = resolver
-  }
-
-  /// The lookahead cache's local file URL for [item]'s source track,
-  /// when it has fully cached since the item was built; nil when no
-  /// resolver is wired, the item carries no source URL, or the cache
-  /// misses. Keyed by the verbatim `sourceURL` the cache was keyed
-  /// with — never the asset URL (already `file://` once local).
-  private func cachedLocalURL(for item: AVPlayerItem) -> URL? {
-    guard let resolver = cachedURLResolver, let url = item.sourceURL else {
-      return nil
-    }
-    return resolver(url)
-  }
-
-  /// The asset a queue item should be (re)built from at a late attach:
-  /// the lookahead cache's local file when [existing]'s track has
-  /// since cached, else [existing]'s own asset. Re-resolving here lets
-  /// a forward/back skip to a now-cached track play from local disk
-  /// rather than re-loading the remote asset.
-  private func cacheResolvedAsset(for existing: AVPlayerItem) -> AVAsset {
-    // Reuse the existing asset when it's already this cache file (built
-    // cached at queue-build time) — the cross-attach rebuilds the item
-    // regardless, so there's nothing to upgrade and a fresh AVURLAsset
-    // on the same file would just be a wasted allocation.
-    guard let cachedURL = cachedLocalURL(for: existing),
-          (existing.asset as? AVURLAsset)?.url != cachedURL else {
-      return existing.asset
-    }
-    return AVURLAsset(url: cachedURL)
-  }
-
-  /// If [index]'s queue item was built from a remote URL whose track
-  /// has since fully cached, swap the slot for a fresh item backed by
-  /// the local cache file (carrying `queueItemId` + `sourceURL` across)
-  /// and return it; otherwise return the existing item unchanged. Lets
-  /// the fade-arm preroll pick up a track that cached after the queue
-  /// was first built so an auto-advance crossfade plays from local disk.
-  private func cacheUpgradedItem(at index: Int) -> AVPlayerItem {
+  /// Resolve the item for [index] as a **fresh** `AVPlayerItem`.
+  ///
+  /// Never hands back the stored instance. Attaching an `AVPlayerItem` that is
+  /// still associated with another `AVPlayer` raises an `NSException` that
+  /// Swift cannot catch, and the association is released asynchronously with
+  /// no API to observe it — so an item that was on a leg a moment ago is not
+  /// safe to attach, and there is no way to ask whether it is. `seek(toIndex:)`
+  /// rebuilds for the same reason.
+  private func rebuiltItem(at index: Int) -> AVPlayerItem {
     let existing = queue[index]
-    // Only rebuild on the genuine remote→cached transition. When the slot
-    // was already built from this cache file (cached at queue-build time),
-    // reuse the prepared item rather than discarding its buffers for an
-    // identical rebuild + re-preroll.
-    guard let cachedURL = cachedLocalURL(for: existing),
-          (existing.asset as? AVURLAsset)?.url != cachedURL else {
-      return existing
-    }
-    let upgraded = AVPlayerItem(
-      asset: AVURLAsset(url: cachedURL),
-      automaticallyLoadedAssetKeys: ["playable", "duration", "tracks"]
+    let rebuilt = AVPlayerItem(
+      asset: existing.asset,
+      automaticallyLoadedAssetKeys: ["playable", "duration"]
     )
-    upgraded.preferredForwardBufferDuration = 0.0
-    upgraded.queueItemId = existing.queueItemId
-    upgraded.sourceURL = existing.sourceURL
-    queue[index] = upgraded
-    return upgraded
+    rebuilt.preferredForwardBufferDuration = 0.0
+    rebuilt.queueItemId = existing.queueItemId
+    rebuilt.sourceURL = existing.sourceURL
+    rebuilt.suppliedReplayGain = existing.suppliedReplayGain
+    // Carry the read-through routing stamp (an item-instance associated object)
+    // so source classification keeps reporting `.cached` across the rebuild.
+    rebuilt.isRoutedThroughReadThroughServer = existing.isRoutedThroughReadThroughServer
+    queue[index] = rebuilt
+    return rebuilt
   }
 
   func refreshAllItemMixes() {
@@ -713,6 +764,10 @@ final class CrossfadeEngine: PlaybackEngine {
     if let standby = standbyPlayer.currentItem, standby.audioMix == nil {
       standby.audioMix = mixProvider?.audioMix(for: standby)
     }
+    // `audioMix(for:)` reports the asset it built for, so walking the standby
+    // leg last leaves the *upcoming* track standing as the active asset. Say
+    // which one is actually audible.
+    mixProvider?.noteActiveAsset(leadingPlayer.currentItem?.asset)
   }
 
   private func applyMixIfNeeded(to item: AVPlayerItem) {
@@ -721,6 +776,100 @@ final class CrossfadeEngine: PlaybackEngine {
     item.audioMix = mix
   }
 
+  /// Resume the leading leg for a fresh seat / resume, holding it at rate 0
+  /// when a consumer wants the tap and the item is not yet ready to render.
+  ///
+  /// AVPlayer honours `audioMix` only before an item renders; a mix set once
+  /// the leg is playing is silently dropped and the equaliser / visualizer tap
+  /// never prepares. When a tap is wanted we keep a not-yet-ready leg at rate 0
+  /// and let the leading `.readyToPlay` observer load tracks, install the mix,
+  /// then resume the held leg (see `installLeadingObservers` and
+  /// `installLeadingTapMixThenResume`). When the item is already `.readyToPlay`
+  /// the `.new`-only status observer will not fire, so drive that same path
+  /// here. The common no-tap path — and any provider without a consumer
+  /// model — resumes immediately, unchanged.
+  ///
+  /// Callers hold a live playback intent. Used for fresh seats and `play()`,
+  /// and for the same-instance seek so it cannot start a leg a preceding seat
+  /// is holding. NOT used by `completeCrossfade` (it promotes an
+  /// already-rendering leg — holding would pause live audio) or the repeat-one
+  /// loop (the same already-ready item).
+  private func resumeLeadingRespectingTap() {
+    let player = leadingPlayer
+    guard let item = player.currentItem else {
+      player.rate = userPlaybackSpeed
+      return
+    }
+    guard mixProvider?.anyConsumerWantsTap() == true else {
+      player.rate = userPlaybackSpeed
+      return
+    }
+    // A deterministically-missing local file never reaches `.readyToPlay`, and
+    // `installLeadingObservers` surfaces its failure without installing a
+    // status observer — so nothing would resume a held leg. Resume directly:
+    // it cannot render a tap anyway, and the failure path drives the retry.
+    if let asset = item.asset as? AVURLAsset, asset.url.isFileURL,
+       !FileManager.default.fileExists(atPath: asset.url.path) {
+      player.rate = userPlaybackSpeed
+      return
+    }
+    if item.status == .readyToPlay {
+      // Already ready: the `.new`-only status observer will not fire, so drive
+      // the tracks-load → mix-install → resume here. The leg is still held at
+      // rate 0 (not rendering) until that completes.
+      installLeadingTapMixThenResume(item: item)
+      return
+    }
+    // Not yet ready: leave the leg at rate 0. `installLeadingObservers` arms
+    // `autoWaits = true` for a not-yet-ready item and its `.readyToPlay`
+    // observer installs the mix and then resumes this held leg.
+  }
+
+  /// Load the leading item's `tracks` key, then install its tap-mix and resume
+  /// a leg held for the tap. `.readyToPlay` does not guarantee the asset's
+  /// `tracks` key is loaded — that is a separate async load — and
+  /// `audioMix(for:)` yields nil until it is (the reason the arm path loads
+  /// tracks before attaching the standby's mix). Loading first guarantees the
+  /// mix builds, so the tap is live before the first sample. The leg stays held
+  /// (rate 0 under a live play-intent, `autoWaits` true) until the completion
+  /// installs the mix, permits render, and resumes it.
+  ///
+  /// The load is bounded by `armDeadlineSeconds`, matching the standby arm
+  /// deadline: a stall after `.readyToPlay` must not leave the held leg silent
+  /// forever, so on timeout (or a load failure) the leg resumes untapped. The
+  /// completion installs the mix only while the leg is still held (rate 0):
+  /// once it has resumed, AVPlayer drops a mix set on a rendering item and
+  /// leaks its tap cascade (see `refreshAllItemMixes`), so a consumer that
+  /// subscribed after an untapped seat is left to the format-changed catch-up.
+  /// Re-checks the engine is live and the item is still the captured leg's
+  /// current one across the load.
+  private func installLeadingTapMixThenResume(item: AVPlayerItem) {
+    let player = leadingPlayer
+    let asset = item.asset
+    Task { [weak self] in
+      await withTaskGroup(of: Void.self) { group in
+        group.addTask { _ = try? await asset.load(.tracks) }
+        group.addTask {
+          try? await Task.sleep(
+            nanoseconds: UInt64(Self.armDeadlineSeconds * 1_000_000_000))
+        }
+        _ = await group.next()
+        group.cancelAll()
+      }
+      guard let self else { return }
+      await self.onOwnerQueue {
+        guard !self.released, player.currentItem === item else { return }
+        if player.rate == 0 {
+          self.refreshAllItemMixes()
+        }
+        player.automaticallyWaitsToMinimizeStalling = false
+        if self.wantsPlayback, player.rate == 0 {
+          player.rate = self.userPlaybackSpeed
+        }
+      }
+    }
+  }
+
   func setPitchCorrectionMode(_ mode: PitchCorrectionMode) {
     pitchCorrectionMode = mode
     reapplyPitchToCurrentLegs()
@@ -744,16 +893,6 @@ final class CrossfadeEngine: PlaybackEngine {
     if let standby = standbyPlayer.currentItem { applyPitchAlgorithm(to: standby) }
   }
 
-  // MARK: - Handoff
-
-  func handoff(to nextEngine: PlaybackEngine, atTrackBoundary: Bool) async {
-    // Engine handoff (gapless ↔ crossfade) is driven by
-    // TrackPlayer.swift's mode-switch path which holds the
-    // canonical queue model. The engine's own `release()` is
-    // the caller's responsibility AFTER the swap.
-    return
-  }
-
   // MARK: - Equal-power gain math
 
   /// Equal-power gain pair for fade progress `t ∈ [0, 1]`.
@@ -821,22 +960,34 @@ final class CrossfadeEngine: PlaybackEngine {
 
   // MARK: - Boundary arming
 
+  /// Whether the transport wants playback, independent of which leg is
+  /// producing sound.
+  ///
+  /// The arming observer is the intent: `play()` installs it; `pause()`,
+  /// `stop()` and `release()` remove it; every path that drains the engine
+  /// removes it, because a run with nothing in it is not a run being played;
+  /// and `completeCrossfade` stops and restarts it across the role flip,
+  /// synchronously, so no reader sees the gap.
+  ///
+  /// A leg's rate or status cannot answer this. Mid-fade the outgoing leading
+  /// leg has already stopped while the incoming one plays, and an item that
+  /// has reached its end leaves its leg at rate 0 with the transport still
+  /// wanting to play. Restoring the rate from either of those leaves the
+  /// engine paused against the consumer's intent.
+  private var wantsPlayback: Bool { armingObserver != nil }
+
   /// Boundary-arming periodic time observer. Watches the leading
   /// leg's time at 200ms cadence; when within
   /// `effectiveCrossfadeSeconds + prerollLeadSeconds` of track end,
   /// prerolls standby + schedules the equal-power ramp on both
   /// legs' `AVMutableAudioMixInputParameters`.
-  ///
-  /// Cancellation: `pause` / `stop` / `seek` / `skipToNext` /
-  /// `skipToPrevious` / `release` all remove the observer. `play`
-  /// re-installs it.
   private func startArmingObserver() {
     if armingObserver != nil { return }
     let player = leadingPlayer
     let interval = CMTime(seconds: 0.2, preferredTimescale: CMTimeScale(NSEC_PER_SEC))
     let token = player.addPeriodicTimeObserver(
       forInterval: interval,
-      queue: .main
+      queue: ownerQueue
     ) { [weak self] _ in
       self?.maybeArmCrossfade()
     }
@@ -860,6 +1011,12 @@ final class CrossfadeEngine: PlaybackEngine {
     // would advance past the track the user asked to repeat.
     if repeatMode == .track { return }
     if currentIndex < 0 || currentIndex >= queue.count - 1 { return }  // last track or empty
+    // Only a leg that is rendering arms. A rate written onto a leg sitting at
+    // its end — a play() after the queue ended — reports the end position
+    // without moving, and arming there would fade into whatever was queued
+    // behind the finished track. A leg stalled inside the arm window waits
+    // for the tick on which it resumes, so the standby prerolls from then.
+    if leadingPlayer.timeControlStatus != .playing { return }
     guard let leading = leadingPlayer.currentItem else { return }
     let duration = leading.duration
     if !duration.isNumeric { return }
@@ -895,22 +1052,24 @@ final class CrossfadeEngine: PlaybackEngine {
   /// wait until the status reaches `.readyToPlay` before invoking
   /// `preroll`; `runFade` chains through the readiness callback so
   /// the timing semantics (preroll → ramp schedule → wall-clock
-  /// completion) are preserved. The pre-attach `seek(to: .zero)`
-  /// on the prior implementation was redundant — `replaceCurrentItem`
-  /// resets the item's playhead — and was masking the readiness
-  /// race because seek-on-detached-item is a documented no-op on
-  /// modern iOS.
+  /// completion) are preserved. No seek before the attach:
+  /// `replaceCurrentItem` resets the item's playhead.
   private func armCrossfade(durationSeconds: TimeInterval) {
-    let nextIdx = currentIndex + 1
-    guard nextIdx < queue.count else {
+    // Validate the index here rather than trusting the caller's earlier
+    // check: `currentIndex + 1` is a trapping add, so a `currentIndex` of
+    // `Int.max` crashes the process before any bounds check can run.
+    // `NSNotFound` is `Int.max` on 64-bit, so a not-found sentinel that
+    // reaches this field is fatal rather than merely wrong.
+    let idx = currentIndex
+    let count = queue.count
+    guard idx >= 0, idx < count - 1 else {
       standbyArmed = false
+      armDeadline?.cancel()
+      armDeadline = nil
       return
     }
-    // Re-resolve against the cache: a track that finished caching after
-    // the queue was built is swapped for its local file here so the
-    // auto-advance fade plays from local disk, not the remote URL.
-    let nextItem = cacheUpgradedItem(at: nextIdx)
-    applyMixIfNeeded(to: nextItem)
+    let nextIdx = idx + 1
+    let nextItem = rebuiltItem(at: nextIdx)
     applyPitchAlgorithm(to: nextItem)
     let standby = standbyPlayer
     standby.replaceCurrentItem(with: nextItem)
@@ -918,6 +1077,9 @@ final class CrossfadeEngine: PlaybackEngine {
     awaitStandbyReady(standby) { [weak self] in
       guard let self else { return }
       if self.released || !self.standbyArmed { return }
+      // The status wait's own timeout is cancelled by the flip that got us
+      // here; everything below is unbounded without this.
+      self.startArmDeadline()
       // Explicit `tracks` key load on the freshly-replaced standby
       // asset BEFORE preroll. `AVPlayerItem.status == .readyToPlay`
       // does NOT guarantee the asset's tracks key is loaded —
@@ -925,32 +1087,50 @@ final class CrossfadeEngine: PlaybackEngine {
       // tracks to be present so it can attach the volume-ramp
       // audioMix to the standby item.
       let nextAsset = nextItem.asset
-      Task { @MainActor [weak self] in
+      Task { [weak self] in
         do {
           _ = try await nextAsset.load(.tracks)
         } catch {
-          self?.cancelFadeInternal()
+          if let self { await self.onOwnerQueue { self.cancelFadeInternal() } }
           return
         }
         guard let self else { return }
-        if self.released || !self.standbyArmed { return }
-        standby.automaticallyWaitsToMinimizeStalling = false
-        // Await preroll via a checked continuation so the rest of
-        // the chain stays on @MainActor. Spawning a fresh Task
-        // inside `preroll`'s @escaping completion would create a
-        // @Sendable-closure-captures-non-Sendable-self warning
-        // because preroll's callback queue is unspecified.
+        // The preroll rate is read on the owner queue with the arm check,
+        // so it is the speed set while the fade was being armed.
+        let (armed, prerollRate) = await self.onOwnerQueue { () -> (Bool, Float) in
+          if self.released || !self.standbyArmed { return (false, 1.0) }
+        // Provider mix goes on here, between the tracks load and the
+        // preroll: `audioMix(for:)` yields nil for an item whose tracks
+        // key isn't loaded, and AVPlayer drops an `audioMix` set once the
+        // item has begun rendering. That leaves this the only window in
+        // which a remote incoming item can pick up the EQ / ReplayGain /
+        // visualizer tap, and `runFade` schedules its ramp onto whatever
+        // input parameters are attached by then. Read the item back off
+        // the leg — the queue slot can be rebuilt across the await.
+          if let attached = standby.currentItem {
+            self.applyMixIfNeeded(to: attached)
+          }
+          standby.automaticallyWaitsToMinimizeStalling = false
+          return (true, self.userPlaybackSpeed)
+        }
+        guard armed else { return }
+        // Await preroll via a checked continuation rather than spawning a
+        // fresh Task inside `preroll`'s @escaping completion, which would
+        // warn about a @Sendable closure capturing non-Sendable self —
+        // preroll's callback queue is unspecified.
         _ = await withCheckedContinuation { (cont: CheckedContinuation<Bool, Never>) in
-          standby.preroll(atRate: 1.0) { ready in
+          standby.preroll(atRate: prerollRate) { ready in
             cont.resume(returning: ready)
           }
         }
-        if self.released || !self.standbyArmed { return }
-        // Best-effort restore: cancel/release paths drop the
-        // standby item entirely, so a missed restore here is
-        // bounded by the next replaceCurrentItem.
-        standby.automaticallyWaitsToMinimizeStalling = priorAutoStall
-        self.runFade(durationSeconds: durationSeconds)
+        await self.onOwnerQueue {
+          if self.released || !self.standbyArmed { return }
+          // Best-effort restore: cancel/release paths drop the
+          // standby item entirely, so a missed restore here is
+          // bounded by the next replaceCurrentItem.
+          standby.automaticallyWaitsToMinimizeStalling = priorAutoStall
+          self.runFade(durationSeconds: durationSeconds)
+        }
       }
     }
   }
@@ -962,6 +1142,22 @@ final class CrossfadeEngine: PlaybackEngine {
   /// `standbyArmed` before acting. Backed by a 5s wall-clock
   /// timeout that calls `cancelFadeInternal` if the status never
   /// flips (stuck-load defence).
+  /// Bound the arm chain so a standby leg that never becomes playable cannot
+  /// leave the engine armed indefinitely. Generous relative to the ready-wait:
+  /// this is the backstop for everything after it, not a second attempt at the
+  /// same deadline.
+  private func startArmDeadline() {
+    armDeadline?.cancel()
+    let deadline = DispatchWorkItem { [weak self] in
+      guard let self else { return }
+      self.armDeadline = nil
+      guard self.standbyArmed, !self.fadeInFlight else { return }
+      self.cancelFadeInternal()
+    }
+    armDeadline = deadline
+    ownerQueue.asyncAfter(deadline: .now() + Self.armDeadlineSeconds, execute: deadline)
+  }
+
   private func awaitStandbyReady(_ player: AVPlayer, ready: @escaping () -> Void) {
     standbyReadyObserver?.invalidate()
     standbyReadyObserver = nil
@@ -979,10 +1175,10 @@ final class CrossfadeEngine: PlaybackEngine {
       let s = obs.status
       // `.unknown` is the start state — wait for the first real flip.
       guard s == .readyToPlay || s == .failed else { return }
-      DispatchQueue.main.async { [weak self] in
-        guard let self else { return }
+      guard let self else { return }
+      self.ownerQueue.async {
         // Cross-cycle race guard: if a new armCrossfade cycle
-        // started after this observer queued its main-async hop,
+        // started after this observer queued its `ownerQueue` hop,
         // the generation counter has advanced — this fire belongs
         // to a stale standby and must not run `ready()` against
         // the new arm's state.
@@ -1011,7 +1207,7 @@ final class CrossfadeEngine: PlaybackEngine {
       self.cancelFadeInternal()
     }
     standbyReadyTimeout = timeout
-    DispatchQueue.main.asyncAfter(deadline: .now() + 5.0, execute: timeout)
+    self.ownerQueue.asyncAfter(deadline: .now() + 5.0, execute: timeout)
   }
 
   /// Input parameters to drive the fade ramp on [item]. Reuses the item's
@@ -1068,9 +1264,24 @@ final class CrossfadeEngine: PlaybackEngine {
       return
     }
 
+    // The leading ramp anchors on the leg's current play position; a
+    // non-numeric CMTime (an unresolved timebase — a leg that reached the fade
+    // before its clock settled, which host load makes more likely) traps
+    // AVFoundation's `setVolumeRamp` on the invalid time range. Abort the fade
+    // cleanly instead. The standby ramp anchors at kCMTimeZero and is exempt.
+    let leadingFadeStart = leading.currentTime()
+    guard leadingFadeStart.isNumeric else {
+      NSLog("[RNQP-CROSSFADE] runFade aborting — leading currentTime not numeric; cancelling fade")
+      cancelFadeInternal()
+      return
+    }
+
     fadeInFlight = true
+    // The chain reached the fade, so its backstop has done its job; the fade
+    // has its own completion path.
+    armDeadline?.cancel()
+    armDeadline = nil
 
-    let leadingFadeStart = leading.currentTime()
     let ramps = Self.equalPowerSubRamps(durationSeconds: durationSeconds)
 
     // Reuse each leg's EXISTING tap-bearing input parameters so the EQ /
@@ -1083,6 +1294,7 @@ final class CrossfadeEngine: PlaybackEngine {
     // bare ramp-only params object only when the leg carries no tap (no
     // EQ/viz/RG consumer, HLS, or tracks not yet loaded).
     let leadingParams = fadeParams(for: leading, track: leadingTrack)
+    rampsScheduled = true
     for ramp in ramps {
       let absStart = leadingFadeStart + ramp.timeRange.start
       let timeRange = CMTimeRange(start: absStart, duration: ramp.timeRange.duration)
@@ -1118,7 +1330,10 @@ final class CrossfadeEngine: PlaybackEngine {
     standby.audioMix = standbyMix
 
     standbyPlayer.volume = userVolume  // ramp inside the mix handles the actual envelope
-    standbyPlayer.play()
+    // Start at the user's speed rather than `play()`'s implicit 1.0, so the
+    // incoming track is not audibly played at normal speed for the length of
+    // the fade and then snapped.
+    standbyPlayer.rate = userPlaybackSpeed
 
     // Active-track flip: the standby leg is now audibly playing
     // (volume 0 → ramping up). Notify the delegate so JS-facing
@@ -1128,8 +1343,7 @@ final class CrossfadeEngine: PlaybackEngine {
     // etc.) also flips at this point because `fadeInFlight = true`
     // is already set above; the delegate sees consistent state
     // across the callback.
-    let incomingIdx = currentIndex + 1
-    delegate?.engineCrossfadeDidBegin(self, incomingIndex: incomingIdx)
+    delegate?.engineCrossfadeDidBegin(self)
 
     // Post-fade swap scheduled in wall-clock — the asset-time-keyed
     // ramps complete in this many seconds regardless of pause
@@ -1140,13 +1354,14 @@ final class CrossfadeEngine: PlaybackEngine {
     // pauses+resumes within one boundary window.
     fadeCompletionTask?.cancel()
     let durationNs = UInt64(durationSeconds * 1_000_000_000)
-    fadeCompletionTask = Task { @MainActor [weak self] in
+    fadeCompletionTask = Task { [weak self] in
       do {
         try await Task.sleep(nanoseconds: durationNs)
       } catch {
         return  // cancelled
       }
-      self?.completeCrossfade()
+      guard let self else { return }
+      await self.onOwnerQueue { self.completeCrossfade() }
     }
   }
 
@@ -1182,14 +1397,17 @@ final class CrossfadeEngine: PlaybackEngine {
       newLeading.audioMix = nil
       applyMixIfNeeded(to: newLeading)
     }
-    // The promoted standby was prerolled + played at rate 1.0; restore
-    // the user's playback speed so it survives the transition.
+    // The promoted standby already runs at the user's speed; restamping it
+    // here keeps the promotion total when the speed changed mid-fade.
     leadingPlayer.rate = userPlaybackSpeed
     standbyArmed = false
+    rampsScheduled = false
     currentIndex += 1
     startArmingObserver()
     installLeadingObservers()
-    updateRoutingArbiter()
+    // Settled before the transition: work held back for this fade belongs to
+    // the run the transition is about to be told to extend.
+    delegate?.engineFadeDidSettle(self)
     delegate?.engineDidTransitionTrack(self)
   }
 
@@ -1200,44 +1418,75 @@ final class CrossfadeEngine: PlaybackEngine {
     standbyReadyObserver = nil
     standbyReadyTimeout?.cancel()
     standbyReadyTimeout = nil
+    armDeadline?.cancel()
+    armDeadline = nil
     // Capture pre-state: if a fade was in flight we already fired
     // `engineCrossfadeDidBegin` for `currentIndex + 1` — the
     // delegate believes the incoming is active. We must fire
-    // `engineCrossfadeDidCancel(revertedIndex: currentIndex)` so
-    // the delegate reverts active-track state back to the leading
+    // `engineCrossfadeDidCancel` so the delegate reverts
+    // active-track state back to the leading
     // leg. `emitRevert: false` is for callers that will immediately
     // set a new active track themselves (e.g. seek to a different
     // index) — emitting the intermediate revert would surface a
     // spurious track-change to the outgoing leg before the caller's
     // own track-change.
     let wasMidFade = fadeInFlight
-    let leadingIdx = currentIndex
+    let wasArmed = standbyArmed
+    let hadScheduledRamp = rampsScheduled
     fadeInFlight = false
     standbyArmed = false
-    // Backward seek through a scheduled ramp window leaves the
-    // mix in a wonky state per Wade Tregaskis — strip the mix
-    // and re-apply the EQ-only mix to recover.
-    if let leading = leadingPlayer.currentItem {
-      leading.audioMix = nil
-      applyMixIfNeeded(to: leading)
-    }
-    if let standby = standbyPlayer.currentItem {
-      standby.audioMix = nil
+    rampsScheduled = false
+    // Workaround: a backward seek through a scheduled ramp window
+    // leaves the mix in place with the wrong volume — strip the mix
+    // and re-apply the EQ-only mix to recover. See the type doc for
+    // the source.
+    //
+    // Only when a ramp was scheduled: this runs on the item that is already
+    // rendering, and re-applying builds a fresh processing tap that AVPlayer
+    // silently drops on an item already in flight. Callers that cancel
+    // routinely — every `remove` in a rebuild's removal loop — would otherwise
+    // pay one dropped tap cascade per item removed.
+    if hadScheduledRamp {
+      if let leading = leadingPlayer.currentItem {
+        leading.audioMix = nil
+        applyMixIfNeeded(to: leading)
+      }
+      if let standby = standbyPlayer.currentItem {
+        standby.audioMix = nil
+      }
     }
     leadingPlayer.volume = userVolume
     standbyPlayer.volume = 0
+    // `runFade` gave this leg a rate. Dropping its item does not stop it, so
+    // without the pause the next arm attaches to a leg already advancing: its
+    // mix is set on an item that has begun rendering and is silently dropped,
+    // and the fade's ramp, anchored at asset-time zero, is already in the past.
+    standbyPlayer.pause()
+    // The arm turns this off as a documented precondition of `preroll` and
+    // restores it once prerolled. A cancel in between skips that restore, and
+    // the value survives the role flip that makes this leg the leading one —
+    // where it means playback resumes into a stall instead of waiting.
+    standbyPlayer.automaticallyWaitsToMinimizeStalling = true
     standbyPlayer.replaceCurrentItem(with: nil)
     if wasMidFade && emitRevert {
-      delegate?.engineCrossfadeDidCancel(self, revertedIndex: leadingIdx)
+      delegate?.engineCrossfadeDidCancel(self)
+    }
+    // Every end of a fade, not just a reverted one. A cancel taken during the
+    // arm window emits no revert — there is no track change to undo — but work
+    // held back for the fade still has to be released, and pause, stop, the
+    // arm deadline, a standby that fails to load and a route change all end
+    // here without ever reaching `wasMidFade`.
+    if wasMidFade || hadScheduledRamp || wasArmed {
+      delegate?.engineFadeDidSettle(self)
     }
   }
 
   // MARK: - Engine event observer install/teardown
 
   /// Install KVO on the leading leg's `timeControlStatus` (drives
-  /// `engineStateMaybeChanged` + `engineIsPlayingChanged`) and on
-  /// the leading leg's currentItem `tracks` / `status` (drives
-  /// format-ready + failed-to-load delegate fires). Called whenever
+  /// `engineStateMaybeChanged`) and on the leading leg's currentItem
+  /// `tracks` / `status` (drives format-ready + failed-to-load
+  /// delegate fires). Called whenever
   /// the leading leg or its currentItem changes — i.e. from
   /// [setItems], [seek], and [completeCrossfade] after the role
   /// flip. Idempotent — teardown runs first inside.
@@ -1246,15 +1495,34 @@ final class CrossfadeEngine: PlaybackEngine {
     let player = leadingPlayer
     leadingTimeControlObserver = player.observe(
       \.timeControlStatus, options: [.new]
-    ) { [weak self] obs, _ in
-      let isPlayingNow = obs.timeControlStatus == .playing
-      DispatchQueue.main.async {
-        guard let self else { return }
+    ) { [weak self] _, _ in
+      guard let self else { return }
+      self.ownerQueue.async {
         self.delegate?.engineStateMaybeChanged(self, reason: nil)
-        self.delegate?.engineIsPlayingChanged(self, isPlaying: isPlayingNow)
       }
     }
     if let item = player.currentItem {
+      // A local file that does not exist is deterministically unplayable, and
+      // its `AVURLAsset` load can stall in `.unknown` indefinitely on `AVPlayer`
+      // under host load — the item never reaches `.failed`, so a status observer
+      // would never surface it and the leg sits buffering with no error. Fail it
+      // now, and install no status observer for this item: a load that does
+      // eventually reach `.failed` would otherwise re-report the same dead
+      // source through the observer below, under a second error code that is
+      // fatal where the missing-file code is transient — the retry path. A retry
+      // re-seats the item and re-runs this check, so a source that appears is
+      // picked up then. Read the asset's own URL, the one the player will load.
+      if let asset = item.asset as? AVURLAsset, asset.url.isFileURL,
+         !FileManager.default.fileExists(atPath: asset.url.path) {
+        let missing = NSError(
+          domain: NSURLErrorDomain, code: NSURLErrorFileDoesNotExist,
+          userInfo: [NSLocalizedDescriptionKey: "The requested file does not exist."])
+        self.ownerQueue.async { [weak self] in
+          guard let self else { return }
+          self.delegate?.engineDidFailWithError(self, error: missing, item: item)
+        }
+        return
+      }
       leadingItemTracksObserver = item.observe(
         \.tracks, options: [.new]
       ) { [weak self] obs, _ in
@@ -1263,8 +1531,8 @@ final class CrossfadeEngine: PlaybackEngine {
         // tracks array is populated so the gapless KVO path's
         // dedup contract is matched.
         guard !obs.tracks.isEmpty else { return }
-        DispatchQueue.main.async {
-          guard let self else { return }
+        guard let self else { return }
+        self.ownerQueue.async {
           self.delegate?.engineActiveItemFormatChanged(self)
         }
       }
@@ -1274,21 +1542,122 @@ final class CrossfadeEngine: PlaybackEngine {
       // propagates and the now-playing format stays nil. Mirrors what
       // `.initial` would have delivered.
       if !item.tracks.isEmpty {
-        DispatchQueue.main.async { [weak self] in
+        self.ownerQueue.async { [weak self] in
           guard let self else { return }
           self.delegate?.engineActiveItemFormatChanged(self)
         }
       }
+      // Leading-leg initial-buffer leniency, mirroring the gapless engine's
+      // `gaplessFlipArmed`. A freshly seated item waits to minimize stalling
+      // until it is `.readyToPlay`, then plays without further waiting. Without
+      // the flip the leading leg keeps `automaticallyWaitsToMinimizeStalling`
+      // set after a resume / engine swap and can take longer than a caller's
+      // settle window to reach `.playing`. Re-arm to `true` for a not-yet-ready
+      // item so a play-before-buffered waits rather than stalling to paused;
+      // flip to `false` once the item is ready so a resume starts promptly.
+      // `player` is captured so the leg that owns this item is the one flipped
+      // even if the leading role has since swapped.
+      player.automaticallyWaitsToMinimizeStalling = item.status != .readyToPlay
       leadingItemStatusObserver = item.observe(
         \.status, options: [.new]
       ) { [weak self] obs, _ in
+        if obs.status == .readyToPlay {
+          // Flip on `ownerQueue` like every other mutation here (and the gapless
+          // flip in `dispatchItemStatus`), re-checking the item is still the
+          // leg's current one. KVO does not abort an in-flight callback on
+          // `invalidate()`, so a stale `.readyToPlay` for a since-replaced item
+          // must not strand `autoWaits = false` on a fresh not-yet-ready item —
+          // the very stall the re-arm above prevents.
+          self?.ownerQueue.async {
+            guard let self, player.currentItem === obs else { return }
+            if self.mixProvider?.anyConsumerWantsTap() == true {
+              // A tap is wanted. Install this item's audio tap BEFORE
+              // permitting prompt render: AVPlayer honours `audioMix` only
+              // before the item starts rendering (Apple contract, the same one
+              // `GaplessEngine.setItems` installs before enqueue for) — a mix
+              // set once the leg is already playing is silently dropped, its
+              // `MTAudioProcessingTap` never prepares, and the equaliser and
+              // visualizer tap lose their audio. `.readyToPlay` does not
+              // guarantee the asset's `tracks` key is loaded and
+              // `audioMix(for:)` yields nil until it is, so load tracks first
+              // (as the arm path does for the standby), then install the mix
+              // and resume any leg held at rate 0 for the tap. The leg stays
+              // held (`autoWaits` true) until that completes; a consumer that
+              // subscribes mid-playback then joins the already-running tap
+              // instead of needing an unreliable mid-render re-attach.
+              self.installLeadingTapMixThenResume(item: obs)
+            } else {
+              // No tap wanted: nothing to install; permit prompt render, and
+              // resume a leg that was held for a tap since dropped (a consumer
+              // unsubscribed before this fired) — leaving it at rate 0 would
+              // strand it silent. A genuine pause has cleared `wantsPlayback`
+              // (via `stopArmingObserver`), so this does not override it.
+              player.automaticallyWaitsToMinimizeStalling = false
+              if self.wantsPlayback, player.rate == 0 {
+                player.rate = self.userPlaybackSpeed
+              }
+            }
+          }
+          return
+        }
         guard obs.status == .failed else { return }
         let underlying = obs.error ?? NSError(
           domain: "CrossfadeEngine", code: -1, userInfo: nil
         )
-        DispatchQueue.main.async {
+        guard let self else { return }
+        // `obs` is the leading leg's current item — the one that failed.
+        self.ownerQueue.async {
+          self.delegate?.engineDidFailWithError(self, error: underlying, item: obs)
+        }
+      }
+      // Bootstrap: `.new`-only KVO won't fire when the item is ALREADY `.failed`
+      // at install time — a source that reached `.failed` between `setItems` and
+      // the reinstall a `seek` runs. The reinstalled observer never sees the
+      // transition, so surface it here, as `.initial` and the tracks observer
+      // above both do.
+      if item.status == .failed {
+        let underlying = item.error ?? NSError(
+          domain: "CrossfadeEngine", code: -1, userInfo: nil
+        )
+        self.ownerQueue.async { [weak self] in
+          guard let self else { return }
+          self.delegate?.engineDidFailWithError(self, error: underlying, item: item)
+        }
+      }
+      // Buffer-flag KVO so a discrete buffer-state change reaches
+      // `onBufferStateChange` on the crossfade engine, the same way the gapless
+      // `AVQueuePlayer`'s item KVO delivers it. Without it the buffer surface
+      // recomputes only on transport calls and the 500ms progress tick, so a
+      // fast local reload's empty→full edge lands between samples and no change
+      // is emitted. Routed to a delegate that recomputes ONLY the buffer surface
+      // — no direct player-state emission; folding buffer edges into the state
+      // path would churn `PlayerState` on every load edge.
+      let onBuffer: (AVPlayerItem, Any) -> Void = { [weak self] _, _ in
+        guard let self else { return }
+        self.ownerQueue.async { [weak self] in
+          guard let self else { return }
+          self.delegate?.engineBufferStateMaybeChanged(self)
+        }
+      }
+      leadingItemBufferEmptyObserver = item.observe(
+        \.isPlaybackBufferEmpty, options: [.new], changeHandler: onBuffer)
+      leadingItemBufferKeepUpObserver = item.observe(
+        \.isPlaybackLikelyToKeepUp, options: [.new], changeHandler: onBuffer)
+      leadingItemBufferFullObserver = item.observe(
+        \.isPlaybackBufferFull, options: [.new], changeHandler: onBuffer)
+      // Bootstrap: `.new`-only KVO won't fire for an item ALREADY buffer-ready
+      // at install time — a cached / preloaded skip. Deliver the current reading
+      // once, as the tracks / status bootstraps above do. Guarded on the ready
+      // flags for the same reason those are guarded on `!tracks.isEmpty` /
+      // `.failed`: bootstrap only when there is a settled state to deliver. An
+      // unconditional fire queues a recompute on the owner queue on EVERY
+      // seat / seek / advance — most of which seat a not-yet-buffered item that
+      // the KVO will report when it settles — and that per-install churn shifts
+      // the crossfade arm / preroll interleave on the serial queue under load.
+      if item.isPlaybackLikelyToKeepUp || item.isPlaybackBufferFull {
+        self.ownerQueue.async { [weak self] in
           guard let self else { return }
-          self.delegate?.engineDidFailWithError(self, error: underlying)
+          self.delegate?.engineBufferStateMaybeChanged(self)
         }
       }
     }
@@ -1301,6 +1670,12 @@ final class CrossfadeEngine: PlaybackEngine {
     leadingItemTracksObserver = nil
     leadingItemStatusObserver?.invalidate()
     leadingItemStatusObserver = nil
+    leadingItemBufferEmptyObserver?.invalidate()
+    leadingItemBufferEmptyObserver = nil
+    leadingItemBufferKeepUpObserver?.invalidate()
+    leadingItemBufferKeepUpObserver = nil
+    leadingItemBufferFullObserver?.invalidate()
+    leadingItemBufferFullObserver = nil
   }
 
   private func handleItemDidPlayToEnd(_ note: Notification) {
@@ -1314,7 +1689,12 @@ final class CrossfadeEngine: PlaybackEngine {
     // every track (incl. the last), so it must precede the queue-end check.
     if repeatMode == .track, !fadeInFlight, currentIndex >= 0 {
       leadingPlayer.seek(to: .zero)
-      leadingPlayer.play()
+      // `play()` resets the rate to 1.0, dropping the user's speed on every
+      // loop; and the notification hops onto the owner queue, so a pause taken
+      // in between must not be undone here.
+      if wantsPlayback {
+        leadingPlayer.rate = userPlaybackSpeed
+      }
       return
     }
     // Queue-end detection: leading played its last item to end
@@ -1328,7 +1708,60 @@ final class CrossfadeEngine: PlaybackEngine {
        currentIndex >= 0,
        currentIndex >= queue.count - 1 {
       delegate?.enginePlaybackEnded(self)
+      return
+    }
+    // The item ended mid-run with no fade to carry the boundary. Advancing
+    // is this engine's job either way: a fade is how it usually crosses, not
+    // the only way it can.
+    //
+    // Reachable whenever the arm did not happen or did not survive — the
+    // standby failed to load, the arm chain timed out, a route change or a
+    // queue mutation cancelled it, or the item was the last one installed and
+    // there was nothing to preroll. Without this the queue simply stops on a
+    // track that has finished, and nothing arrives to restart it.
+    if !fadeInFlight, currentIndex >= 0, currentIndex < queue.count - 1 {
+      advanceWithoutFade()
+    }
+  }
+
+  /// Attach the next queue item to the leading leg and advance the index, for
+  /// an item that reached its end with no fade to carry the boundary.
+  ///
+  /// Follows `seek(toIndex:)`: capture playback intent, tear the fade state
+  /// down through the one path that owns it, rebuild the incoming item, and
+  /// resume only if the engine was playing.
+  private func advanceWithoutFade() {
+    if released { return }
+    // The end-of-item notification hops onto the owner queue, so a pause taken
+    // in between must not be undone by the rate write below.
+    let shouldResume = wantsPlayback
+    // Never by hand: the arm leaves a KVO observation, two timers and a task
+    // behind, and the standby leg holding a buffering item. Suppress the
+    // revert emit — the transition fired at the end of this method is the
+    // authoritative track change.
+    cancelFadeInternal(emitRevert: false)
+    // `engineFadeDidSettle` above releases work deferred for the fade, which
+    // can reconcile the run. Re-read the bounds it may have moved.
+    guard currentIndex >= 0, currentIndex + 1 < queue.count else { return }
+    teardownLeadingObservers()
+    let nextIndex = currentIndex + 1
+    // Fresh instance, never the stored one: the queue slot may still hold the
+    // item the arm attached to the standby leg, and attaching an item that is
+    // still associated with another player raises an uncatchable exception.
+    let next = rebuiltItem(at: nextIndex)
+    // Both before the attach: AVPlayer drops an `audioMix` set on an item that
+    // has begun rendering, leaking the processing tap it carries.
+    applyMixIfNeeded(to: next)
+    applyPitchAlgorithm(to: next)
+    leadingPlayer.replaceCurrentItem(with: next)
+    currentIndex = nextIndex
+    if shouldResume {
+      // `replaceCurrentItem` leaves the player at rate 0 — resume respecting a
+      // wanted tap, as `seek(toIndex:)` does.
+      resumeLeadingRespectingTap()
     }
+    installLeadingObservers()
+    delegate?.engineDidTransitionTrack(self)
   }
 
   private func handleItemFailedToPlayToEnd(_ note: Notification) {
@@ -1337,6 +1770,7 @@ final class CrossfadeEngine: PlaybackEngine {
     let underlying = (note.userInfo?[AVPlayerItemFailedToPlayToEndTimeErrorKey] as? Error)
       ?? item.error
       ?? NSError(domain: "CrossfadeEngine", code: -2, userInfo: nil)
-    delegate?.engineDidFailWithError(self, error: underlying)
+    // Guarded above as the leading leg's current item.
+    delegate?.engineDidFailWithError(self, error: underlying, item: item)
   }
 }