react-native-queue-player 1.2.0 → 2.0.0

package/ios/Tests/CrossfadeAdvanceWithoutFadeTests.swift

@@ -0,0 +1,120 @@
+import AVFoundation
+import XCTest
+@testable import QueuePlayer
+
+/// An item that reaches its end mid-queue with no fade in flight advances the
+/// engine anyway. A fade is how this engine usually crosses a boundary, not
+/// the only way it can — the arm can fail to load, time out, or be cancelled
+/// by a route change or a queue mutation, and the queue must not stop on a
+/// track that has finished.
+final class CrossfadeAdvanceWithoutFadeTests: XCTestCase {
+
+  func testAnItemEndingMidQueueAdvancesToTheNextItem() {
+    let engine = makeEngine(count: 3)
+    engine.play()
+
+    endLeadingItem(on: engine)
+
+    XCTAssertEqual(
+      engine.currentMediaItem?.queueItemId, "id-1",
+      "the engine moves to the next item in the run")
+    XCTAssertEqual(engine.currentMediaItemIndex, 1)
+  }
+
+  /// The queue slot may still hold the instance the arm attached to the
+  /// standby leg, and attaching an item still associated with another player
+  /// raises an exception Swift cannot catch.
+  func testTheAdvanceAttachesAFreshItemRatherThanTheStoredOne() {
+    let engine = makeEngine(count: 3)
+    engine.play()
+    let stored = engine.allMediaItems
+
+    endLeadingItem(on: engine)
+
+    XCTAssertFalse(
+      engine.currentMediaItem === stored[1],
+      "the incoming item is rebuilt, never the stored instance")
+    XCTAssertEqual(
+      engine.currentMediaItem?.queueItemId, stored[1].queueItemId,
+      "the rebuild carries the queue identity across")
+  }
+
+  /// The end-of-item notification hops onto the owner's queue, so a pause
+  /// taken in between must survive the advance.
+  func testAnItemEndingWhilePausedDoesNotResumePlayback() {
+    let engine = makeEngine(count: 3)
+    engine.play()
+    engine.pause()
+
+    endLeadingItem(on: engine)
+
+    XCTAssertEqual(
+      engine.currentMediaItem?.queueItemId, "id-1",
+      "the advance still happens")
+    XCTAssertEqual(
+      engine.timeControlStatus, .paused,
+      "a paused engine stays paused across the advance")
+  }
+
+  func testTheLastItemEndingEndsTheQueueRatherThanAdvancing() {
+    let engine = makeEngine(count: 2)
+    let delegate = RecordingDelegate()
+    engine.delegate = delegate
+    engine.play()
+    engine.seek(toIndex: 1, position: 0)
+
+    endLeadingItem(on: engine)
+
+    XCTAssertTrue(delegate.playbackEnded, "the queue reports that it ran out")
+    XCTAssertEqual(engine.currentMediaItemIndex, 1, "and stays on the last item")
+  }
+
+  // MARK: - Helpers
+
+  private func makeEngine(count: Int) -> CrossfadeEngine {
+    let engine = CrossfadeEngine(crossfadeDurationSeconds: 5.0, confinedTo: .main)
+    let items = (0 ..< count).map { index -> AVPlayerItem in
+      let item = AVPlayerItem(url: URL(string: "http://127.0.0.1:1/\(index).m4a")!)
+      item.queueItemId = "id-\(index)"
+      return item
+    }
+    engine.setItems(items, startIndex: 0, startPositionSeconds: 0)
+    engines.append(engine)
+    return engine
+  }
+
+  /// Post the end-of-item notification the way AVFoundation does, then let the
+  /// engine's hop onto its owner queue run before asserting.
+  private func endLeadingItem(on engine: CrossfadeEngine) {
+    guard let item = engine.currentMediaItem else {
+      return XCTFail("no item is attached to end")
+    }
+    NotificationCenter.default.post(
+      name: .AVPlayerItemDidPlayToEndTime, object: item)
+    let drained = expectation(description: "owner queue drained")
+    DispatchQueue.main.async { drained.fulfill() }
+    wait(for: [drained], timeout: 2.0)
+  }
+
+  private var engines: [CrossfadeEngine] = []
+
+  override func tearDown() {
+    engines.forEach { $0.release() }
+    engines.removeAll()
+    super.tearDown()
+  }
+}
+
+private final class RecordingDelegate: PlaybackEngineDelegate {
+  var playbackEnded = false
+
+  func engineStateMaybeChanged(_ engine: PlaybackEngine, reason: StateChangeReason?) {}
+  func engineDidTransitionTrack(_ engine: PlaybackEngine) {}
+  func engineActiveItemFormatChanged(_ engine: PlaybackEngine) {}
+  func engineDidFailWithError(
+    _ engine: PlaybackEngine, error: Error, item: AVPlayerItem?) {}
+  func engineDidPlayItemToEnd(_ engine: PlaybackEngine) {}
+  func enginePlaybackEnded(_ engine: PlaybackEngine) { playbackEnded = true }
+  func engineCrossfadeDidBegin(_ engine: PlaybackEngine) {}
+  func engineCrossfadeDidCancel(_ engine: PlaybackEngine) {}
+}

package/ios/Tests/CrossfadeEngineIncomingMixTests.swift

@@ -0,0 +1,122 @@
+import AVFoundation
+import XCTest
+@testable import QueuePlayer
+
+/// The crossfade leading leg installs its EQ / visualizer / ReplayGain tap-mix
+/// before it renders. AVPlayer honours `audioMix` only before an item renders,
+/// and `AVPlayerItem.status == .readyToPlay` does not imply the asset's `tracks`
+/// key has loaded — the provider yields nil until it is — so a leg that wants
+/// the tap is held at rate 0 until the tracks load and the mix is installed,
+/// then resumed. Miss that window and the tap is absent for the whole track.
+///
+/// The incoming-leg attach, which is reached only through a real crossfade's
+/// arm chain, is covered end-to-end by the demo `boundary-audio-chain` suite
+/// (it drives an actual boundary on device); a unit test that drives the real
+/// fade is too sensitive to a loaded CI simulator's arm-chain timing.
+@MainActor
+final class CrossfadeEngineIncomingMixTests: XCTestCase {
+
+  /// A tap-wanting consumer holds a freshly-seated leading leg at rate 0 until
+  /// its `tracks` key loads and the tap-bearing mix is installed, then resumes
+  /// it — the leg never renders untapped, and it does not strand at rate 0.
+  func testLeadingLegHeldForTapUntilMixInstalledThenResumes() async throws {
+    let url = try requireFixture(name: "silence-cbr-128", ext: "mp3")
+    let provider = TapWantingTracksGatedMixProvider()
+    let engine = CrossfadeEngine(
+      crossfadeDurationSeconds: 0.5, confinedTo: .main)
+    defer { engine.release() }
+    engine.setAudioMixProvider(provider)
+    engine.setItems(
+      [makeItem(url: url, id: "leading"), makeItem(url: url, id: "incoming")],
+      startIndex: 0,
+      startPositionSeconds: 0
+    )
+
+    // A fresh `AVURLAsset` starts `.unknown`, so the leading item is not yet
+    // `.readyToPlay` here. A tap is wanted, so play() must hold the leg at
+    // rate 0 rather than start it rendering before the mix is installed.
+    engine.play()
+    XCTAssertEqual(
+      engine.timeControlStatus, .paused,
+      "a tap-wanting leading leg must be held at rate 0 until its mix is "
+        + "installed, not started rendering by play()"
+    )
+
+    // The `.readyToPlay` observer loads tracks, installs the tap-bearing mix,
+    // then resumes the held leg — it must reach `.playing`, not strand.
+    try await waitUntil("the held leading leg resumes playing") {
+      engine.timeControlStatus == .playing
+    }
+    let leading = try XCTUnwrap(engine.currentMediaItem)
+    let installed = leading.audioMix?.inputParameters.first
+      as? AVMutableAudioMixInputParameters
+    XCTAssertTrue(
+      installed === provider.issued["leading"],
+      "the leading leg must carry the provider's tap-bearing mix once playing; "
+        + "a nil or foreign mix means it resumed untapped"
+    )
+  }
+
+  // MARK: - helpers
+
+  /// Built without `tracks` in `automaticallyLoadedAssetKeys`, so the asset's
+  /// tracks key is unloaded until something explicitly loads it — the state a
+  /// remote item is in when the arm chain picks it up.
+  private func makeItem(url: URL, id: String) -> AVPlayerItem {
+    let item = AVPlayerItem(asset: AVURLAsset(url: url))
+    item.queueItemId = id
+    return item
+  }
+
+  private func waitUntil(
+    _ what: String,
+    timeout: TimeInterval = 20,
+    _ condition: () -> Bool
+  ) async throws {
+    let deadline = Date().addingTimeInterval(timeout)
+    while Date() < deadline {
+      if condition() { return }
+      try await Task.sleep(nanoseconds: 20_000_000)
+    }
+    XCTFail("timed out waiting for \(what)")
+  }
+
+  private func requireFixture(name: String, ext: String) throws -> URL {
+    let bundle = Bundle(for: type(of: self))
+    if let url = bundle.url(forResource: name, withExtension: ext) {
+      return url
+    }
+    let candidates = bundle.urls(forResourcesWithExtension: ext, subdirectory: nil) ?? []
+    if let match = candidates.first(where: { $0.deletingPathExtension().lastPathComponent == name }) {
+      return match
+    }
+    // Fixtures are bundled via `test_spec.resources` in QueuePlayer.podspec.
+    // A miss means the test-harness pod install regressed — that's a real
+    // infrastructure failure, not a conditionally-inapplicable test.
+    return try XCTUnwrap(
+      nil as URL?,
+      "fixture \(name).\(ext) not bundled — pod install regression in tests-harness"
+    )
+  }
+}
+
+/// Like `AudioTapProvider`, reports a live tap consumer so the crossfade engine
+/// holds a not-yet-ready leading leg for the tap rather than resuming it
+/// immediately. Issues a real tap-bearing mix once tracks load.
+private final class TapWantingTracksGatedMixProvider: AudioMixProvider {
+  private(set) var issued: [String: AVMutableAudioMixInputParameters] = [:]
+
+  func anyConsumerWantsTap() -> Bool { true }
+
+  func audioMix(for item: AVPlayerItem) -> AVAudioMix? {
+    guard case .loaded(let tracks) = item.asset.status(of: .tracks),
+          let track = tracks.first(where: { $0.mediaType == .audio }) else {
+      return nil
+    }
+    let params = AVMutableAudioMixInputParameters(track: track)
+    let mix = AVMutableAudioMix()
+    mix.inputParameters = [params]
+    issued[item.queueItemId ?? ""] = params
+    return mix
+  }
+}

package/ios/Tests/CrossfadeEngineTests.swift

@@ -0,0 +1,164 @@
+import AVFoundation
+import XCTest
+@testable import QueuePlayer
+
+/// Coverage for `CrossfadeEngine`'s construction, delegate assignment and
+/// index contract.
+///
+/// The index contract is the load-bearing part: the engine indexes within
+/// whatever slice it was handed, so its indices are NOT queue positions.
+/// Callers translate by `queueItemId` identity. These tests cover the engine
+/// side of that contract — slice-relative indexing, ordered identity-bearing
+/// `allMediaItems`, and identity surviving the seek cross-attach. The
+/// translation itself lives in `TrackPlayer.engineIndex(forQueuePosition:)`,
+/// which needs a configured engine and is covered by the
+/// `non-zero-start-index-seeks-within-the-started-track` demo step.
+///
+/// The negative-duration constructor guard at
+/// `CrossfadeEngine.init(crossfadeDurationSeconds:)` is not testable — a
+/// `precondition` trap is non-recoverable from XCTest. The load-bearing
+/// guard for runtime callers is the clamp inside
+/// `PlaybackModeStateMachine`; the constructor check is a defensive belt.
+final class CrossfadeEngineTests: XCTestCase {
+
+  func testConstructorAcceptsNonNegativeCrossfadeDuration() {
+    let engine = CrossfadeEngine(crossfadeDurationSeconds: 5.0, confinedTo: .main)
+    XCTAssertEqual(engine.currentMediaItemIndex, -1, "a fresh engine holds no queue")
+    XCTAssertTrue(engine.allMediaItems.isEmpty)
+  }
+
+  func testDelegateIsWirable() {
+    let engine = CrossfadeEngine(crossfadeDurationSeconds: 5.0, confinedTo: .main)
+    let delegate = NoopDelegate()
+    engine.delegate = delegate
+    XCTAssertTrue(engine.delegate === delegate)
+  }
+
+  // MARK: - Index contract
+
+  /// Items carrying the lib-generated identity the translation relies on.
+  private func makeItems(ids: [String]) -> [AVPlayerItem] {
+    ids.map { id in
+      let item = AVPlayerItem(url: URL(fileURLWithPath: "/dev/null/\(id).mp3"))
+      item.queueItemId = id
+      return item
+    }
+  }
+
+  func testEngineIndexesWithinItsOwnSliceNotTheQueuePosition() {
+    let engine = CrossfadeEngine(crossfadeDurationSeconds: 5.0, confinedTo: .main)
+    // The slice a caller hands over when playback starts at queue position 5.
+    engine.setItems(makeItems(ids: ["q5", "q6", "q7"]), startIndex: 0, startPositionSeconds: 0)
+
+    // Zero, not 5 — the engine has no knowledge of the queue position the
+    // slice came from. Reading this as a queue position seats the wrong track.
+    XCTAssertEqual(engine.currentMediaItemIndex, 0)
+    XCTAssertEqual(engine.allMediaItems.count, 3)
+  }
+
+  /// `allMediaItems` exposes the installed slice in order, with identities
+  /// intact. Callers translate a queue position into an engine index through
+  /// this, so an engine that reordered or dropped identities would break the
+  /// translation silently.
+  func testAllMediaItemsPreservesSliceOrderAndIdentity() {
+    let engine = CrossfadeEngine(crossfadeDurationSeconds: 5.0, confinedTo: .main)
+    engine.setItems(makeItems(ids: ["q5", "q6", "q7"]), startIndex: 0, startPositionSeconds: 0)
+
+    XCTAssertEqual(engine.allMediaItems.map(\.queueItemId), ["q5", "q6", "q7"])
+  }
+
+  /// The cross-attach inside `seek` rebuilds the target item; identity has to
+  /// survive it or the translation stops resolving after the first seek.
+  func testIdentitySurvivesTheSeekCrossAttach() {
+    let engine = CrossfadeEngine(crossfadeDurationSeconds: 5.0, confinedTo: .main)
+    engine.setItems(makeItems(ids: ["q5", "q6", "q7"]), startIndex: 0, startPositionSeconds: 0)
+
+    engine.seek(toIndex: 1, position: 0)
+
+    XCTAssertEqual(engine.allMediaItems.map(\.queueItemId), ["q5", "q6", "q7"])
+    XCTAssertEqual(engine.currentMediaItem?.queueItemId, "q6")
+  }
+
+  /// The seek cross-attach rebuilds the target item; the read-through routing
+  /// stamp has to survive it too, or `getCurrentTrackSource()` reports a
+  /// cache-served track as `.streaming` (the gapless engine never rebuilds, so
+  /// it never loses the stamp).
+  func testRoutingStampSurvivesTheSeekCrossAttach() {
+    let engine = CrossfadeEngine(crossfadeDurationSeconds: 5.0, confinedTo: .main)
+    let items = makeItems(ids: ["q5", "q6", "q7"])
+    items.forEach { $0.isRoutedThroughReadThroughServer = true }
+    engine.setItems(items, startIndex: 0, startPositionSeconds: 0)
+
+    engine.seek(toIndex: 1, position: 0)
+
+    XCTAssertEqual(
+      engine.allMediaItems.map(\.isRoutedThroughReadThroughServer),
+      [true, true, true],
+      "the rebuilt item must keep its read-through routing stamp")
+  }
+
+  func testSeekToIndexMovesWithinTheEngineSlice() {
+    let engine = CrossfadeEngine(crossfadeDurationSeconds: 5.0, confinedTo: .main)
+    engine.setItems(makeItems(ids: ["q5", "q6", "q7"]), startIndex: 0, startPositionSeconds: 0)
+
+    engine.seek(toIndex: 2, position: 0)
+    XCTAssertEqual(engine.currentMediaItemIndex, 2)
+    XCTAssertEqual(engine.currentMediaItem?.queueItemId, "q7")
+  }
+
+  func testSeekOutsideTheSliceIsRejected() {
+    let engine = CrossfadeEngine(crossfadeDurationSeconds: 5.0, confinedTo: .main)
+    engine.setItems(makeItems(ids: ["q5", "q6", "q7"]), startIndex: 0, startPositionSeconds: 0)
+
+    engine.seek(toIndex: 7, position: 0)
+    XCTAssertEqual(engine.currentMediaItemIndex, 0, "an out-of-slice index must not move the engine")
+  }
+
+  /// A missing local file's `AVURLAsset` load can stall in `.unknown` on
+  /// `AVPlayer`, so `.failed` never fires and the failure never reaches the
+  /// delegate. Seating one must surface `engineDidFailWithError` from the file's
+  /// non-existence directly, rather than wait on the load.
+  func testAMissingLocalFileSurfacesAFailure() {
+    let engine = CrossfadeEngine(crossfadeDurationSeconds: 5.0, confinedTo: .main)
+    let delegate = FailCapturingDelegate()
+    engine.delegate = delegate
+    let missing = URL(fileURLWithPath: "/tmp/rnqp-missing-\(UUID().uuidString).mp3")
+    let item = AVPlayerItem(url: missing)
+    item.queueItemId = "missing"
+    item.sourceURL = missing.absoluteString
+
+    let fired = expectation(description: "a missing local file surfaces a failure")
+    delegate.onFail = { error in
+      let ns = error as NSError
+      if ns.domain == NSURLErrorDomain, ns.code == NSURLErrorFileDoesNotExist { fired.fulfill() }
+    }
+    engine.setItems([item], startIndex: 0, startPositionSeconds: 0)
+
+    wait(for: [fired], timeout: 3.0)
+  }
+}
+
+private final class NoopDelegate: PlaybackEngineDelegate {
+  func engineStateMaybeChanged(_ engine: PlaybackEngine, reason: StateChangeReason?) {}
+  func engineDidTransitionTrack(_ engine: PlaybackEngine) {}
+  func engineActiveItemFormatChanged(_ engine: PlaybackEngine) {}
+  func engineDidFailWithError(
+    _ engine: PlaybackEngine, error: Error, item: AVPlayerItem?) {}
+  func engineDidPlayItemToEnd(_ engine: PlaybackEngine) {}
+  func enginePlaybackEnded(_ engine: PlaybackEngine) {}
+  func engineCrossfadeDidBegin(_ engine: PlaybackEngine) {}
+  func engineCrossfadeDidCancel(_ engine: PlaybackEngine) {}
+}
+
+private final class FailCapturingDelegate: PlaybackEngineDelegate {
+  var onFail: ((Error) -> Void)?
+  func engineStateMaybeChanged(_ engine: PlaybackEngine, reason: StateChangeReason?) {}
+  func engineDidTransitionTrack(_ engine: PlaybackEngine) {}
+  func engineActiveItemFormatChanged(_ engine: PlaybackEngine) {}
+  func engineDidFailWithError(
+    _ engine: PlaybackEngine, error: Error, item: AVPlayerItem?) { onFail?(error) }
+  func engineDidPlayItemToEnd(_ engine: PlaybackEngine) {}
+  func enginePlaybackEnded(_ engine: PlaybackEngine) {}
+  func engineCrossfadeDidBegin(_ engine: PlaybackEngine) {}
+  func engineCrossfadeDidCancel(_ engine: PlaybackEngine) {}
+}

package/ios/Tests/CrossfadeMixReapplyTests.swift

@@ -0,0 +1,66 @@
+import AVFoundation
+import XCTest
+@testable import QueuePlayer
+
+/// The rendering item's audio mix is rebuilt only when a ramp was scheduled.
+///
+/// Rebuilding it means a fresh processing tap on an item already in flight,
+/// which AVPlayer silently drops — so a cancel that had no ramp to unwind must
+/// leave the mix it is already rendering alone.
+final class CrossfadeMixReapplyTests: XCTestCase {
+
+  func testRemovingItemsDoesNotRebuildTheRenderingItemsMix() {
+    let engine = CrossfadeEngine(crossfadeDurationSeconds: 5.0, confinedTo: .main)
+    let provider = CountingMixProvider()
+    engine.setAudioMixProvider(provider)
+    engine.setItems(items(count: 4), startIndex: 0, startPositionSeconds: 0)
+    let afterInstall = provider.buildCount
+
+    // The removal loop a rebuild runs when it replaces a divergent tail.
+    for item in engine.allMediaItems.suffix(3) {
+      engine.remove(item)
+    }
+
+    XCTAssertEqual(
+      provider.buildCount, afterInstall,
+      "removing queued items must not rebuild the mix of the item playing")
+  }
+
+  /// Arming happens from the boundary observer during playback, so the armed
+  /// half of this contract is covered by the crossfade demo suites rather than
+  /// here; what is reachable is that a cancel with no ramp to unwind leaves the
+  /// rendering item's mix as it is.
+  func testCancellingWithNothingArmedLeavesTheMixAlone() {
+    let engine = CrossfadeEngine(crossfadeDurationSeconds: 5.0, confinedTo: .main)
+    let provider = CountingMixProvider()
+    engine.setAudioMixProvider(provider)
+    engine.setItems(items(count: 2), startIndex: 0, startPositionSeconds: 0)
+    let afterInstall = provider.buildCount
+
+    engine.cancelFade()
+
+    XCTAssertEqual(provider.buildCount, afterInstall)
+  }
+
+  private func items(count: Int) -> [AVPlayerItem] {
+    (0 ..< count).map { index in
+      let item = AVPlayerItem(
+        url: URL(string: "http://127.0.0.1:1/\(index).m4a")!)
+      item.queueItemId = "id-\(index)"
+      return item
+    }
+  }
+}
+
+/// Counts how many times a mix is built, which is what the dropped-tap hazard
+/// is really about.
+private final class CountingMixProvider: AudioMixProvider {
+  private(set) var buildCount = 0
+
+  func audioMix(for item: AVPlayerItem) -> AVAudioMix? {
+    buildCount += 1
+    return AVMutableAudioMix()
+  }
+
+  func noteActiveAsset(_ asset: AVAsset?) {}
+}

package/ios/Tests/CrossfadePlaybackIntentTests.swift

@@ -0,0 +1,81 @@
+import AVFoundation
+import XCTest
+@testable import QueuePlayer
+
+/// `seek(toIndex:)` and `setItems` resume from the transport's intent, never
+/// from a leg's rate or status.
+///
+/// `replaceCurrentItem` drops the player it is called on to rate 0, so each of
+/// these paths has to put the rate back. Reading a leg to decide whether to is
+/// wrong in two states the engine is routinely in: mid-fade, where the
+/// outgoing leading leg has already stopped while the incoming one plays, and
+/// at the end of an item, where the leg sits at rate 0 with the transport
+/// still wanting playback. Either reading leaves the queue silently paused.
+///
+/// What is reachable here is the half that must NOT resume. The resuming half
+/// needs a leg genuinely at rate 0 with playback still wanted, and only real
+/// playback produces that: measured on the simulator, an item pointed at an
+/// unreachable URL holds `timeControlStatus == .waitingToPlayAtSpecifiedRate`
+/// indefinitely and never drops its rate, so every assertion built on one is
+/// vacuous. The `consecutive-auto-advance` and `queue-end-then-set-queue` demo
+/// suites cover both halves on both engines.
+final class CrossfadePlaybackIntentTests: XCTestCase {
+
+  func testASeekAfterPauseStaysPaused() {
+    let engine = makeEngine(count: 3)
+    engine.play()
+    engine.pause()
+
+    engine.seek(toIndex: 1, position: 0)
+
+    XCTAssertEqual(
+      engine.timeControlStatus, .paused,
+      "a paused engine is not resumed by a seek")
+  }
+
+  func testAReinstallBeforeAnyPlayStaysPaused() {
+    let engine = makeEngine(count: 3)
+
+    engine.setItems(items(count: 3, from: 10), startIndex: 0, startPositionSeconds: 0)
+
+    XCTAssertEqual(
+      engine.timeControlStatus, .paused,
+      "an engine that was never told to play stays stopped")
+  }
+
+  func testASeekAfterStopStaysPaused() {
+    let engine = makeEngine(count: 3)
+    engine.play()
+    engine.stop()
+
+    engine.seek(toIndex: 2, position: 0)
+
+    XCTAssertEqual(engine.timeControlStatus, .paused)
+  }
+
+  // MARK: - Helpers
+
+  private func items(count: Int, from base: Int = 0) -> [AVPlayerItem] {
+    (0 ..< count).map { offset in
+      let index = base + offset
+      let item = AVPlayerItem(url: URL(string: "http://127.0.0.1:1/\(index).m4a")!)
+      item.queueItemId = "id-\(index)"
+      return item
+    }
+  }
+
+  private func makeEngine(count: Int) -> CrossfadeEngine {
+    let engine = CrossfadeEngine(crossfadeDurationSeconds: 5.0, confinedTo: .main)
+    engine.setItems(items(count: count), startIndex: 0, startPositionSeconds: 0)
+    engines.append(engine)
+    return engine
+  }
+
+  private var engines: [CrossfadeEngine] = []
+
+  override func tearDown() {
+    engines.forEach { $0.release() }
+    engines.removeAll()
+    super.tearDown()
+  }
+}

package/ios/Tests/EngineSwapTests.swift

@@ -0,0 +1,91 @@
+import AVFoundation
+import XCTest
+@testable import QueuePlayer
+
+/// A playback-mode swap installs the window on the new engine and always
+/// releases the one it replaces.
+final class EngineSwapTests: XCTestCase {
+
+  private var player: TrackPlayer!
+
+  override func setUp() async throws {
+    try await super.setUp()
+    player = TrackPlayer()
+  }
+
+  override func tearDown() async throws {
+    if let player {
+      _ = try await player.destroy().await()
+    }
+    player = nil
+    try await super.tearDown()
+  }
+
+  /// Nothing at or after the current position can be built, so the new engine
+  /// is left empty — and the old one still goes.
+  func testTheOldEngineIsReleasedWhenNothingCanBeSeated() async throws {
+    let player = try XCTUnwrap(self.player)
+    let old = ActiveItemEngineStub()
+    await player.onPlayerQueue {
+      _ = player.queueState.replaceAll([PlayerFixtures.track(id: "t0", url: "")])
+      player.currentTrackIndex = 0
+      player.engine = old
+    }
+
+    await player.onPlayerQueue {
+      player.applyEngineSwapForMode(PlaybackMode(kind: .gapless, crossfadeDurationMs: nil))
+    }
+
+    XCTAssertTrue(old.released, "the replaced engine is released whatever was seated")
+    let installed = await player.onPlayerQueueValue { player.engine?.allMediaItems.count ?? -1 }
+    XCTAssertEqual(installed, 0, "an unbuildable current track seats nothing")
+  }
+
+  func testTheOldEngineIsReleasedOnAnOrdinarySwap() async throws {
+    let player = try XCTUnwrap(self.player)
+    let old = ActiveItemEngineStub()
+    await player.onPlayerQueue {
+      _ = player.queueState.replaceAll([
+        PlayerFixtures.track(id: "t0", url: "https://example.com/0.m4a"),
+        PlayerFixtures.track(id: "t1", url: "https://example.com/1.m4a"),
+      ])
+      player.currentTrackIndex = 0
+      player.engine = old
+    }
+
+    await player.onPlayerQueue {
+      player.applyEngineSwapForMode(PlaybackMode(kind: .gapless, crossfadeDurationMs: nil))
+    }
+
+    XCTAssertTrue(old.released)
+    let installed = await player.onPlayerQueueValue { player.engine?.allMediaItems.count ?? -1 }
+    XCTAssertEqual(installed, 2, "the window is installed on the new engine")
+  }
+
+  // MARK: - seatIndex
+
+  private func item(_ id: String) -> AVPlayerItem {
+    let item = AVPlayerItem(url: URL(fileURLWithPath: "/dev/null/\(id).mp3"))
+    item.queueItemId = id
+    return item
+  }
+
+  func testTheSeatIsTheCurrentItemWhenItBuilt() {
+    let items = [item("a"), item("b"), item("c")]
+    XCTAssertEqual(
+      TrackPlayer.seatIndex(in: items, sliceIds: ["a", "b", "c"], currentId: "b"), 1)
+  }
+
+  /// A current position whose item did not build seats on the next built
+  /// position forward, never on the trail behind it.
+  func testTheSeatMovesForwardPastAnUnbuiltCurrentItem() {
+    let items = [item("a"), item("c")]
+    XCTAssertEqual(
+      TrackPlayer.seatIndex(in: items, sliceIds: ["a", "b", "c"], currentId: "b"), 1)
+  }
+
+  func testThereIsNoSeatWhenNothingAheadBuilt() {
+    let items = [item("a")]
+    XCTAssertNil(TrackPlayer.seatIndex(in: items, sliceIds: ["a", "b", "c"], currentId: "b"))
+  }
+}