react-native-queue-player 1.2.0 → 2.0.0

package/ios/Tests/AssetReplayGainReaderTests.swift

@@ -0,0 +1,228 @@
+import XCTest
+@testable import QueuePlayer
+
+/// Unit tests for `AssetReplayGainReader.tagName(info:key:)` — the pure
+/// reduction of AVFoundation's three container-dependent metadata shapes
+/// to one comparable ReplayGain tag name.
+///
+/// The shapes below are measured, not assumed:
+/// - MP3 / ID3v2 `TXXX`: `info = REPLAYGAIN_TRACK_GAIN`, `key = TXXX`
+/// - FLAC / Vorbis: `info = nil`, `key = REPLAYGAIN_TRACK_GAIN`
+/// - M4A / iTunes freeform: `info = nil`,
+///   `key = com.apple.iTunes.replaygain_track_gain`
+///
+/// The rule: `info` when non-blank, else `key`; then the segment after
+/// the last `.`; then uppercased.
+final class AssetReplayGainReaderTests: XCTestCase {
+
+  private let replayGainNames = [
+    ReplayGainExtractor.trackGainKey,
+    ReplayGainExtractor.trackPeakKey,
+    ReplayGainExtractor.albumGainKey,
+    ReplayGainExtractor.albumPeakKey,
+  ]
+
+  private func assertNotAReplayGainName(
+    _ actual: String?,
+    _ message: String,
+    file: StaticString = #file, line: UInt = #line
+  ) {
+    guard let actual = actual else { return }
+    XCTAssertFalse(
+      replayGainNames.contains(actual), message, file: file, line: line
+    )
+  }
+
+  /// Every test below whose only other assertions are negative pairs
+  /// them with this. `assertNotAReplayGainName` is satisfied by `nil`,
+  /// so without a derivation that demonstrably works, "this key does
+  /// not resolve to a ReplayGain name" is equally satisfied by a
+  /// `tagName` that resolves nothing at all.
+  private func assertNameDerivationIsLive(
+    file: StaticString = #file, line: UInt = #line
+  ) {
+    XCTAssertEqual(
+      AssetReplayGainReader.tagName(info: nil, key: "REPLAYGAIN_TRACK_GAIN"),
+      ReplayGainExtractor.trackGainKey,
+      "positive control — a known-good key must resolve to its name",
+      file: file, line: line
+    )
+  }
+
+  // MARK: - The three measured container shapes
+
+  func testAnID3UserTextFrameTakesItsNameFromTheInfoField() {
+    XCTAssertEqual(
+      AssetReplayGainReader.tagName(
+        info: "REPLAYGAIN_TRACK_GAIN", key: "TXXX"
+      ),
+      ReplayGainExtractor.trackGainKey,
+      "MP3: the frame id is TXXX; the name is in the info field"
+    )
+  }
+
+  func testAVorbisCommentTakesItsNameFromTheKey() {
+    XCTAssertEqual(
+      AssetReplayGainReader.tagName(
+        info: nil, key: "REPLAYGAIN_TRACK_GAIN"
+      ),
+      ReplayGainExtractor.trackGainKey,
+      "FLAC: the key is already the name"
+    )
+  }
+
+  func testAnM4AFreeformKeyReducesToItsLastDotSegment() {
+    XCTAssertEqual(
+      AssetReplayGainReader.tagName(
+        info: nil, key: "com.apple.iTunes.replaygain_track_gain"
+      ),
+      ReplayGainExtractor.trackGainKey,
+      "M4A: reverse-DNS identifier, trimmed to its last segment and uppercased"
+    )
+  }
+
+  func testAllFourM4AFreeformKeysReduceToTheirReplayGainNames() {
+    let cases: [(String, String)] = [
+      ("com.apple.iTunes.replaygain_track_gain", ReplayGainExtractor.trackGainKey),
+      ("com.apple.iTunes.replaygain_track_peak", ReplayGainExtractor.trackPeakKey),
+      ("com.apple.iTunes.replaygain_album_gain", ReplayGainExtractor.albumGainKey),
+      ("com.apple.iTunes.replaygain_album_peak", ReplayGainExtractor.albumPeakKey),
+    ]
+    for (key, expected) in cases {
+      XCTAssertEqual(
+        AssetReplayGainReader.tagName(info: nil, key: key), expected,
+        "\(key) must reduce to \(expected)"
+      )
+    }
+  }
+
+  // MARK: - Info / key precedence
+
+  func testABlankInfoFieldFallsBackToTheKey() {
+    // Empty and whitespace-only are both blank — a nil check alone lets
+    // an empty info field shadow a usable key.
+    XCTAssertEqual(
+      AssetReplayGainReader.tagName(
+        info: "", key: "REPLAYGAIN_TRACK_GAIN"
+      ),
+      ReplayGainExtractor.trackGainKey,
+      "an empty info field falls back to the key"
+    )
+    XCTAssertEqual(
+      AssetReplayGainReader.tagName(
+        info: "   ", key: "REPLAYGAIN_TRACK_GAIN"
+      ),
+      ReplayGainExtractor.trackGainKey,
+      "a whitespace-only info field falls back to the key"
+    )
+  }
+
+  func testALowercaseInfoFieldIsUppercased() {
+    XCTAssertEqual(
+      AssetReplayGainReader.tagName(
+        info: "replaygain_album_gain", key: "TXXX"
+      ),
+      ReplayGainExtractor.albumGainKey
+    )
+  }
+
+  func testWithNeitherInfoNorKeyThereIsNoName() {
+    assertNameDerivationIsLive()
+    XCTAssertNil(AssetReplayGainReader.tagName(info: nil, key: nil))
+  }
+
+  // MARK: - Names that must not reach the ReplayGain lookup
+
+  func testAnOrdinalKeyYieldsNoReplayGainName() {
+    // ffmpeg writes `mdta` metadata under ordinal keys ("1", "2", ...);
+    // the tag name is unrecoverable from them and none may match.
+    assertNameDerivationIsLive()
+    for key in ["1", "2", "10"] {
+      assertNotAReplayGainName(
+        AssetReplayGainReader.tagName(info: nil, key: key),
+        "ordinal key \(key) must not resolve to a ReplayGain name"
+      )
+    }
+  }
+
+  func testAnUnrelatedTagNameYieldsNoReplayGainName() {
+    assertNameDerivationIsLive()
+    for key in ["TITLE", "ARTIST", "com.apple.iTunes.iTunNORM"] {
+      assertNotAReplayGainName(
+        AssetReplayGainReader.tagName(info: nil, key: key),
+        "\(key) must not resolve to a ReplayGain name"
+      )
+    }
+  }
+
+  func testAKeyEndingInADotYieldsNoUsableName() {
+    // The last-segment split has nothing after the separator. It must
+    // return safely rather than trap on an out-of-range index, and must
+    // never hand back an empty name.
+    assertNameDerivationIsLive()
+    for key in ["com.apple.iTunes.", ".", "..", "REPLAYGAIN_TRACK_GAIN."] {
+      let name = AssetReplayGainReader.tagName(info: nil, key: key)
+      XCTAssertNotEqual(name, "", "\(key) must not yield an empty name")
+      assertNotAReplayGainName(
+        name, "\(key) must not resolve to a ReplayGain name"
+      )
+    }
+  }
+
+  // MARK: - Opus double-correction guard
+
+
+  func testIsOpusContainerRecognisesOpusExtension() {
+    XCTAssertTrue(
+      AssetReplayGainReader.isOpusContainer(
+        url: URL(string: "https://example.test/track.opus")!
+      )
+    )
+    XCTAssertTrue(
+      AssetReplayGainReader.isOpusContainer(
+        url: URL(string: "https://example.test/track.ogg")!
+      )
+    )
+  }
+
+  /// The guard reads the track's own URL, never the URL the asset is bound to.
+  ///
+  /// A routed track's asset URL is the read-through server's — a token with no
+  /// extension — so a guard that asked the asset would fail open on every Opus
+  /// track and apply a `REPLAYGAIN_*` tag on top of the decoder's own
+  /// `OpusHead.output_gain`. That is audible, and no playback suite covers it.
+  func testAServerTokenURLIsNotMistakenForANonOpusContainer() {
+    XCTAssertFalse(
+      AssetReplayGainReader.isOpusContainer(
+        url: URL(string: "http://127.0.0.1:52341/media/0123456789abcdef0123456789abcdef")!
+      ),
+      "the transport URL carries no container — the guard must read sourceURL"
+    )
+    XCTAssertTrue(
+      AssetReplayGainReader.isOpusContainer(
+        url: URL(string: "https://example.test/track.opus")!
+      ),
+      "and the media URL still identifies Opus"
+    )
+  }
+
+  func testIsOpusContainerReturnsFalseForOtherFormats() {
+    XCTAssertFalse(
+      AssetReplayGainReader.isOpusContainer(
+        url: URL(string: "https://example.test/track.mp3")!
+      )
+    )
+    XCTAssertFalse(
+      AssetReplayGainReader.isOpusContainer(
+        url: URL(string: "https://example.test/track.m4a")!
+      )
+    )
+    XCTAssertFalse(
+      AssetReplayGainReader.isOpusContainer(
+        url: URL(string: "https://example.test/track.flac")!
+      )
+    )
+  }
+
+  // MARK: - FLAC STREAMINFO
+}

package/ios/Tests/AudioTapProviderDispatchTargetTests.swift

@@ -0,0 +1,158 @@
+import AVFoundation
+import XCTest
+@testable import QueuePlayer
+
+/// The tap provider's engine-facing mix work runs on the dispatch target it
+/// was given: inline when the caller is already on that target, on the target
+/// itself otherwise. `resetMixDispatchTarget` puts it back on main, and
+/// `detachFromEngine` clears the provider off the engine it was attached to.
+final class AudioTapProviderDispatchTargetTests: XCTestCase {
+
+  func testRefreshRunsInlineWhenTheCallerIsOnTheMixQueue() {
+    let provider = AudioTapProvider()
+    let engine = MixDispatchEngineStub()
+    provider.wireToPlaybackEngine(engine)
+    let queue = makeQueue(label: "inline")
+    provider.setMixDispatchTarget(
+      queue,
+      isCurrent: { DispatchQueue.getSpecific(key: MixDispatchEngineStub.queueKey) == "inline" })
+
+    queue.sync { provider.refreshActiveItemMixes() }
+
+    XCTAssertEqual(
+      engine.observedTargets, ["inline"],
+      "an in-queue caller reaches the engine before the call returns, without "
+        + "a second hop onto the queue it is already on")
+  }
+
+  func testRefreshLandsOnTheInjectedQueueWhenTheCallerIsNotOnIt() {
+    let provider = AudioTapProvider()
+    let engine = MixDispatchEngineStub()
+    provider.wireToPlaybackEngine(engine)
+    let landed = expectation(description: "refresh reaches the engine")
+    engine.onRefresh = { landed.fulfill() }
+    provider.setMixDispatchTarget(makeQueue(label: "deferred"), isCurrent: { false })
+
+    provider.refreshActiveItemMixes()
+
+    wait(for: [landed], timeout: 1.0)
+    XCTAssertEqual(engine.observedTargets, ["deferred"])
+  }
+
+  func testResetMixDispatchTargetReturnsTheWorkToMain() {
+    let provider = AudioTapProvider()
+    let engine = MixDispatchEngineStub()
+    provider.wireToPlaybackEngine(engine)
+    provider.setMixDispatchTarget(makeQueue(label: "player"), isCurrent: { false })
+
+    provider.resetMixDispatchTarget()
+    provider.refreshActiveItemMixes()
+
+    XCTAssertEqual(engine.observedTargets, [nil], "the player queue is no longer the target")
+    XCTAssertEqual(
+      engine.observedMainThreadFlags, [true],
+      "a main-thread caller runs inline once the target is back on main")
+  }
+
+  func testDetachFromEngineClearsTheEngineMixProvider() {
+    let provider = AudioTapProvider()
+    let engine = MixDispatchEngineStub()
+    provider.wireToPlaybackEngine(engine)
+    XCTAssertNotNil(engine.lastSetProvider)
+
+    provider.detachFromEngine()
+
+    XCTAssertNil(engine.lastSetProvider)
+    provider.refreshActiveItemMixes()
+    XCTAssertTrue(
+      engine.observedTargets.isEmpty,
+      "a detached provider has no engine left to refresh")
+  }
+
+  /// A queue tagged with its own label so the stub can report which target an
+  /// engine call arrived on.
+  private func makeQueue(label: String) -> DispatchQueue {
+    let queue = DispatchQueue(label: "test.mixDispatch.\(label)")
+    queue.setSpecific(key: MixDispatchEngineStub.queueKey, value: label)
+    return queue
+  }
+}
+
+/// Records the dispatch target of every `refreshAllItemMixes` call and the last
+/// provider set on it. All other PlaybackEngine methods are no-op stubs.
+private final class MixDispatchEngineStub: PlaybackEngine {
+
+  /// Tags a queue built by the test; `nil` in `observedTargets` means the call
+  /// arrived on a thread with no tagged queue.
+  static let queueKey = DispatchSpecificKey<String>()
+
+  private let lock = NSLock()
+  private var observed: [String?] = []
+  private var observedOnMain: [Bool] = []
+  var lastSetProvider: AudioMixProvider?
+  var onRefresh: (() -> Void)?
+
+  var observedTargets: [String?] {
+    lock.lock()
+    defer { lock.unlock() }
+    return observed
+  }
+
+  /// Whether each recorded call arrived on the main thread — an untagged
+  /// target is only evidence of "main" together with this.
+  var observedMainThreadFlags: [Bool] {
+    lock.lock()
+    defer { lock.unlock() }
+    return observedOnMain
+  }
+
+  func setAudioMixProvider(_ provider: AudioMixProvider?) {
+    lastSetProvider = provider
+  }
+
+  func refreshAllItemMixes() {
+    let target = DispatchQueue.getSpecific(key: Self.queueKey)
+    let onMain = Thread.isMainThread
+    lock.lock()
+    observed.append(target)
+    observedOnMain.append(onMain)
+    lock.unlock()
+    onRefresh?()
+  }
+
+  func release() {}
+  func setItems(_ items: [AVPlayerItem], startIndex: Int, startPositionSeconds: TimeInterval) {}
+  @discardableResult
+  func insertItems(_ items: [AVPlayerItem], after: AVPlayerItem?) -> Bool { true }
+  func remove(_ item: AVPlayerItem) {}
+  func removeAllItems() {}
+  func canInsert(_ item: AVPlayerItem, after: AVPlayerItem?) -> Bool { true }
+  func play() {}
+  func pause() {}
+  func stop() {}
+  func seek(toIndex index: Int, position: TimeInterval) {}
+  func skipToNext() {}
+  func skipToPrevious() {}
+  func setVolume(_ volume: Float) {}
+  func setPlaybackSpeed(_ speed: Float) {}
+  func seedPlaybackSpeed(_ speed: Float) {}
+  func setRepeatMode(_ mode: RepeatMode) {}
+  func setPitchCorrectionMode(_ mode: PitchCorrectionMode) {}
+
+  var currentMediaItemIndex: Int { -1 }
+  var currentPositionSeconds: TimeInterval { 0 }
+  var currentDurationSeconds: TimeInterval { 0 }
+  var bufferedPositionSeconds: TimeInterval { 0 }
+  var isPlaying: Bool { false }
+  var timeControlStatus: AVPlayer.TimeControlStatus { .paused }
+  var currentMediaItem: AVPlayerItem? { nil }
+  var allMediaItems: [AVPlayerItem] { [] }
+
+  /// No fade to schedule — this stub exercises the rest of the surface.
+  var isFadePendingOrActive: Bool { false }
+
+  /// Nothing attached — this stub exercises the rest of the surface.
+  var attachedQueueItemIds: [String] { [] }
+
+  var delegate: PlaybackEngineDelegate?
+}

package/ios/Tests/AudioTapProviderReplayGainTests.swift

@@ -96,29 +96,141 @@ final class AudioTapProviderReplayGainTests: XCTestCase {
     )
   }
 
-  func testComputeLinearGainEncoderDefaultPeakIsIgnored() {
-    // peak == 1.0 is the encoder-default sentinel; cap path skipped.
+  func testComputeLinearGainFullScalePeakCapsBoostAtUnity() {
+    // peak == 1.0 is digital full scale, so 1/peak == 1.0 and a +6 dB
+    // boost is capped back to unity. +6 dB, not -6 dB: at -6 dB the cap
+    // never binds and the row cannot discriminate. Mirrors Android's
+    // `peak equal to 1 caps the boost at unity`.
     let data = ReplayGainData(
-      trackGainDb: -6.0, trackPeak: 1.0,
+      trackGainDb: 6.0, trackPeak: 1.0,
       albumGainDb: nil, albumPeak: nil
     )
-    let raw = Float(pow(10.0, -6.0 / 20.0))
     XCTAssertEqual(
       AudioTapProvider.computeLinearGain(data: data, mode: .track),
-      raw, accuracy: 0.001
+      1.0, accuracy: 0.001
     )
   }
 
-  func testComputeLinearGainNearZeroPeakIsIgnored() {
-    // peak < 0.001 sentinel — also bypasses the cap.
+  func testComputeLinearGainUnusablePeakClampsBoostToUnity() {
+    // peak < 0.001 is an encoder zero — no usable peak, so the boost is
+    // clamped to unity rather than running uncapped.
     let data = ReplayGainData(
-      trackGainDb: -6.0, trackPeak: 0.0005,
+      trackGainDb: 6.0, trackPeak: 0.0005,
       albumGainDb: nil, albumPeak: nil
     )
-    let raw = Float(pow(10.0, -6.0 / 20.0))
     XCTAssertEqual(
       AudioTapProvider.computeLinearGain(data: data, mode: .track),
-      raw, accuracy: 0.001
+      1.0, accuracy: 0.001
+    )
+  }
+
+  // MARK: - Clip safety — min(10^(gain/20), 1/peak), unity cap with no peak
+
+  func testComputeLinearGainAttenuationIsUnaffectedByTheMissingPeakClamp() {
+    // -20 dB, no peak. A negative gain can never clip, so the unity
+    // clamp only ever binds on a boost.
+    let data = ReplayGainData(
+      trackGainDb: -20.0, trackPeak: nil,
+      albumGainDb: nil, albumPeak: nil
+    )
+    XCTAssertEqual(
+      AudioTapProvider.computeLinearGain(data: data, mode: .track),
+      0.100, accuracy: 0.001
+    )
+  }
+
+  func testComputeLinearGainWithNoPeakClampsBoostToUnity() {
+    // +6 dB, no peak. A peak cannot be derived from a gain, so boost is
+    // suppressed rather than run unprotected.
+    let data = ReplayGainData(
+      trackGainDb: 6.0, trackPeak: nil,
+      albumGainDb: nil, albumPeak: nil
+    )
+    XCTAssertEqual(
+      AudioTapProvider.computeLinearGain(data: data, mode: .track),
+      1.000, accuracy: 0.001
+    )
+  }
+
+  func testComputeLinearGainWithNoPeakLeavesZeroGainAtUnity() {
+    let data = ReplayGainData(
+      trackGainDb: 0.0, trackPeak: nil,
+      albumGainDb: nil, albumPeak: nil
+    )
+    XCTAssertEqual(
+      AudioTapProvider.computeLinearGain(data: data, mode: .track),
+      1.000, accuracy: 0.001
+    )
+  }
+
+  func testComputeLinearGainFullScalePeakDoesNotBindOnAttenuation() {
+    // -20 dB with peak 1.0: the cap is present at 1.0 but 0.1 is lower.
+    let data = ReplayGainData(
+      trackGainDb: -20.0, trackPeak: 1.0,
+      albumGainDb: nil, albumPeak: nil
+    )
+    XCTAssertEqual(
+      AudioTapProvider.computeLinearGain(data: data, mode: .track),
+      0.100, accuracy: 0.001
+    )
+  }
+
+  func testComputeLinearGainBoostSurvivesWhenThePeakCapSitsAboveIt() {
+    // +6 dB ~= 1.995, peak 0.5 -> cap 2.0. The cap does not bind.
+    let data = ReplayGainData(
+      trackGainDb: 6.0, trackPeak: 0.5,
+      albumGainDb: nil, albumPeak: nil
+    )
+    XCTAssertEqual(
+      AudioTapProvider.computeLinearGain(data: data, mode: .track),
+      1.995, accuracy: 0.001
+    )
+  }
+
+  func testComputeLinearGainBoostIsCappedByTheReciprocalOfThePeak() {
+    // +12 dB ~= 3.981, peak 0.5 -> cap 2.0. The cap wins.
+    let data = ReplayGainData(
+      trackGainDb: 12.0, trackPeak: 0.5,
+      albumGainDb: nil, albumPeak: nil
+    )
+    XCTAssertEqual(
+      AudioTapProvider.computeLinearGain(data: data, mode: .track),
+      2.000, accuracy: 0.001
+    )
+  }
+
+  func testComputeLinearGainAPeakAboveUnityCapsBoostBelowUnity() {
+    // +6 dB with a true peak of 1.16 -> cap 1/1.16 ~= 0.862, below unity.
+    let data = ReplayGainData(
+      trackGainDb: 6.0, trackPeak: 1.16,
+      albumGainDb: nil, albumPeak: nil
+    )
+    XCTAssertEqual(
+      AudioTapProvider.computeLinearGain(data: data, mode: .track),
+      0.862, accuracy: 0.001
+    )
+  }
+
+  func testComputeLinearGainClipSafetyIsMirroredInAlbumMode() {
+    // The whole cap applies to whichever pair the mode selects — applying
+    // it to the track pair only would pass every row above.
+    let noPeak = ReplayGainData(
+      trackGainDb: nil, trackPeak: nil,
+      albumGainDb: 6.0, albumPeak: nil
+    )
+    XCTAssertEqual(
+      AudioTapProvider.computeLinearGain(data: noPeak, mode: .album),
+      1.000, accuracy: 0.001,
+      "album mode with no album peak clamps boost to unity"
+    )
+    let fullScale = ReplayGainData(
+      trackGainDb: nil, trackPeak: nil,
+      albumGainDb: 6.0, albumPeak: 1.0
+    )
+    XCTAssertEqual(
+      AudioTapProvider.computeLinearGain(data: fullScale, mode: .album),
+      1.000, accuracy: 0.001,
+      "album mode with a full-scale album peak caps boost at unity"
     )
   }
 

package/ios/Tests/BitrateReresolveBudgetTests.swift

@@ -0,0 +1,71 @@
+import AVFoundation
+import XCTest
+@testable import QueuePlayer
+
+/// Access-log entries arrive several times a second for a stream; the
+/// bitrate re-resolve they trigger runs a bounded number of times per item,
+/// since a server that never declares a bitrate would otherwise have the
+/// extractor re-read the stream for the life of the track.
+final class BitrateReresolveBudgetTests: XCTestCase {
+
+  private var player: TrackPlayer!
+
+  override func setUp() async throws {
+    try await super.setUp()
+    player = TrackPlayer()
+  }
+
+  override func tearDown() async throws {
+    player = nil
+    try await super.tearDown()
+  }
+
+  func testReresolvesStopAtTheBudgetForOneItem() async throws {
+    let player = try XCTUnwrap(self.player)
+    let engine = ActiveItemEngineStub()
+    engine.item = AVPlayerItem(url: URL(fileURLWithPath: "/dev/null/a.mp3"))
+    await player.onPlayerQueue { player.engine = engine }
+    let before = await player.onPlayerQueueValue { player.nowPlayingFormatRequestGen }
+
+    for _ in 0 ..< (TrackPlayer.maxBitrateReresolvesPerItem + 3) {
+      await player.onPlayerQueue { player.reresolveNowPlayingFormatForBitrate() }
+      try await waitUntilSettled(player)
+    }
+
+    let launched = await player.onPlayerQueueValue { player.nowPlayingFormatRequestGen }
+    XCTAssertEqual(
+      Int(launched - before), TrackPlayer.maxBitrateReresolvesPerItem,
+      "every call past the budget is dropped")
+  }
+
+  /// The budget is per item: the next track starts with its own.
+  func testANewActiveItemGetsAFreshBudget() async throws {
+    let player = try XCTUnwrap(self.player)
+    let engine = ActiveItemEngineStub()
+    engine.item = AVPlayerItem(url: URL(fileURLWithPath: "/dev/null/a.mp3"))
+    await player.onPlayerQueue { player.engine = engine }
+    for _ in 0 ..< TrackPlayer.maxBitrateReresolvesPerItem {
+      await player.onPlayerQueue { player.reresolveNowPlayingFormatForBitrate() }
+      try await waitUntilSettled(player)
+    }
+    let spent = await player.onPlayerQueueValue { player.nowPlayingFormatRequestGen }
+
+    engine.item = AVPlayerItem(url: URL(fileURLWithPath: "/dev/null/b.mp3"))
+    await player.onPlayerQueue { player.reresolveNowPlayingFormatForBitrate() }
+    try await waitUntilSettled(player)
+
+    let afterSwitch = await player.onPlayerQueueValue { player.nowPlayingFormatRequestGen }
+    XCTAssertEqual(afterSwitch, spent + 1, "the new item's first re-resolve runs")
+  }
+
+  /// A launched re-resolve finishes on the player queue; the next call is
+  /// only meaningful once it has.
+  private func waitUntilSettled(_ player: TrackPlayer) async throws {
+    for _ in 0 ..< 100 {
+      let inFlight = await player.onPlayerQueueValue { player.bitrateReresolveInFlight }
+      if !inFlight { return }
+      try await Task.sleep(nanoseconds: 20_000_000)
+    }
+    XCTFail("the re-resolve did not settle")
+  }
+}

package/ios/Tests/CastMediaItemTranslationTests.swift

@@ -0,0 +1,72 @@
+import AVFoundation
+import MediaPlayer
+import XCTest
+@testable import QueuePlayer
+
+/// A cast receiver is handed the consumer's own media URL, never the local
+/// read-through server's.
+///
+/// Cast never touches an `AVPlayerItem`: it builds from `self.tracks`, and the
+/// receiver fetches the origin itself over the LAN. Read-through routing lives
+/// inside `AVQueueBuilder.makeItem` and never rewrites `self.tracks`.
+final class CastMediaItemTranslationTests: XCTestCase {
+
+  /// Configuring a real player writes the process-global
+  /// `MPNowPlayingInfoCenter` on main. Drain those writes and clear the centre
+  /// so they do not reach the next test class.
+  override func tearDown() {
+    let drained = expectation(description: "pending main-queue now-playing writes complete")
+    DispatchQueue.main.async { drained.fulfill() }
+    wait(for: [drained], timeout: 5.0)
+    MPNowPlayingInfoCenter.default().nowPlayingInfo = nil
+    super.tearDown()
+  }
+
+  private func track(url: String) -> TrackItem {
+    TrackItem(
+      id: "cast-1", url: url, title: "T", artist: nil, album: nil, duration: nil,
+      artworkUrl: nil, extras: nil,
+      replayGainTrackGain: nil, replayGainTrackPeak: nil,
+      replayGainAlbumGain: nil, replayGainAlbumPeak: nil)
+  }
+
+  func testAReceiverGetsTheConsumersRemoteURL() throws {
+    let item = try XCTUnwrap(
+      CastMediaItem.from(track: track(url: "https://example.com/song.mp3")))
+    XCTAssertEqual(item.url.absoluteString, "https://example.com/song.mp3")
+  }
+
+  /// Local content still goes to the cast server, which is a different server
+  /// on a different binding and is untouched by the read-through work.
+  func testALocalFileStillReachesCastAsAFileURL() throws {
+    let item = try XCTUnwrap(
+      CastMediaItem.from(track: track(url: "file:///var/mobile/song.mp3")))
+    XCTAssertTrue(item.url.isFileURL)
+  }
+
+  /// The routing decision on a configured player: the seated item addresses
+  /// the loopback server while the track the cast side builds from keeps the
+  /// consumer's URL.
+  func testRoutingRewritesTheSeatedItemAndNotTheTrack() async throws {
+    let player = TrackPlayer()
+    _ = try await player.configure(config: PlayerFixtures.config()).await()
+    let origin = "http://127.0.0.1:1/song.mp3"
+    _ = try await player.setQueue(tracks: [track(url: origin)], startAtIndex: 0).await()
+
+    let seatedItem = await player.onPlayerQueueValue { player.engine?.allMediaItems.first }
+    // `AVPlayerItem.asset` is main-actor isolated (`AVAsset` is not Sendable).
+    let seated = await MainActor.run { (seatedItem?.asset as? AVURLAsset)?.url }
+    let modelURL = await player.onPlayerQueueValue { player.tracks.first?.url }
+
+    XCTAssertEqual(seated?.host, "127.0.0.1", "the seated item reads through the loopback server")
+    XCTAssertNotEqual(seated?.port, 1, "on the server's own port, not the origin's")
+    XCTAssertEqual(modelURL, origin, "the track the cast side builds from is untouched")
+    XCTAssertEqual(
+      try XCTUnwrap(CastMediaItem.from(track: track(url: origin))).url.absoluteString, origin)
+
+    // Await destroy so its player-queue → main now-playing clear is enqueued
+    // before this test returns; `tearDown` then drains main and clears the
+    // centre so no stray write reaches the next test class.
+    _ = try await player.destroy().await()
+  }
+}

package/ios/Tests/CastNowPlayingControllerTests.swift

@@ -188,7 +188,7 @@ final class ControllableRemoteSession: CastSessionRemotePlayer {
   private var positionCb: ((Int64, Int64, Int64) -> Void)?
 
   /// Drive the receiver state the way a live session does: a non-idle report
-  /// latches `hasReportedState`. Set `lastState` directly to stage a state the
+  /// sets `hasReportedState`. Set `lastState` directly to stage a state the
   /// receiver has not reported yet.
   func fireState(_ state: RemotePlaybackStateKind) {
     lastState = state