react-native-queue-player 1.1.2 → 2.0.0

package/ios/Tests/EqualizerAudioMixProviderTests.swift

@@ -29,6 +29,33 @@ final class AudioTapProviderTests: XCTestCase {
     )
   }
 
+  func testConsumerWantingTapGetsAWorkingMixForALoadedLocalAsset() async throws {
+    let provider = AudioTapProvider()
+    provider.register(makeConsumer(wantsTap: { true }))
+
+    let url = try requireFixture(name: "silence-cbr-128", ext: "mp3")
+    let asset = AVURLAsset(url: url)
+    // The mix keys its input parameters to an `AVAssetTrack`, so the tracks
+    // key has to be loaded before there is anything to key them to.
+    let tracks = try await asset.load(.tracks)
+    let item = AVPlayerItem(asset: asset)
+
+    let mix = try XCTUnwrap(
+      provider.audioMix(for: item),
+      "a registered consumer wanting the tap must receive a mix")
+    let params = try XCTUnwrap(
+      mix.inputParameters.first as? AVMutableAudioMixInputParameters,
+      "the mix must carry input parameters for the asset's audio track")
+    XCTAssertNotNil(
+      params.audioTapProcessor,
+      "the input parameters must carry the processing tap — a mix without one "
+        + "silently drops ReplayGain, the equalizer and the visualizer")
+
+    let audioTrackID = try XCTUnwrap(
+      tracks.first { $0.mediaType == .audio }?.trackID)
+    XCTAssertEqual(params.trackID, audioTrackID)
+  }
+
   func testNoConsumersWantingTapReturnsNilEvenForLocalAssets() {
     let provider = AudioTapProvider()
     XCTAssertFalse(provider.isEnabledSnapshot())
@@ -106,4 +133,23 @@ final class AudioTapProviderTests: XCTestCase {
     _ = provider.audioMix(for: item)
     XCTAssertEqual(1, fires, "unregistered consumer must not see further events")
   }
+
+  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"
+    )
+  }
+
 }

package/ios/Tests/EqualizerHybridTests.swift

@@ -257,7 +257,6 @@ private final class RecordingEngineStub: PlaybackEngine {
   var refreshCount: Int = 0
   var onRefresh: (() -> Void)?
 
-  func prepare(items: [AVPlayerItem], startIndex: Int, startPositionSeconds: TimeInterval) async {}
   func release() {}
   func setItems(_ items: [AVPlayerItem], startIndex: Int, startPositionSeconds: TimeInterval) {}
   @discardableResult
@@ -295,7 +294,11 @@ private final class RecordingEngineStub: PlaybackEngine {
     onRefresh?()
   }
 
-  func handoff(to nextEngine: PlaybackEngine, atTrackBoundary: Bool) async {}
+  /// 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/FLACStreamInfoTests.swift

@@ -0,0 +1,88 @@
+import XCTest
+@testable import QueuePlayer
+
+/// The FLAC STREAMINFO parse, the only source of a local FLAC bitrate.
+final class FLACStreamInfoTests: XCTestCase {
+
+
+  func testFLACStreamInfoExtractsSampleRateAndTotalSamples() throws {
+    // Build a STREAMINFO-only FLAC header.
+    // sampleRate=44100, channels=2, bitsPerSample=16, totalSamples=1234567
+    let info = makeFLACStreamInfo(
+      sampleRate: 44100,
+      channels: 2,
+      bitsPerSample: 16,
+      totalSamples: 1_234_567
+    )
+    let parsed = try XCTUnwrap(FLACStreamInfo.parse(info))
+    XCTAssertEqual(parsed.sampleRate, 44100)
+    XCTAssertEqual(parsed.channelCount, 2)
+    XCTAssertEqual(parsed.bitsPerSample, 16)
+    XCTAssertEqual(parsed.totalSamples, 1_234_567)
+  }
+
+  func testFLACStreamInfoHighSampleRate() throws {
+    // foobar2000 + some lossless masters use 96 kHz / 24-bit. Verify
+    // the 20-bit sampleRate field isn't truncated.
+    let info = makeFLACStreamInfo(
+      sampleRate: 96000,
+      channels: 2,
+      bitsPerSample: 24,
+      totalSamples: 9_876_543
+    )
+    let parsed = try XCTUnwrap(FLACStreamInfo.parse(info))
+    XCTAssertEqual(parsed.sampleRate, 96000)
+    XCTAssertEqual(parsed.bitsPerSample, 24)
+    XCTAssertEqual(parsed.totalSamples, 9_876_543)
+  }
+
+  func testFLACStreamInfoReturnsNilOnNonFLACBytes() {
+    XCTAssertNil(FLACStreamInfo.parse(
+      Data([0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00])
+    ))
+  }
+
+  // MARK: - Test helpers — byte-level fixture builders
+
+  private func makeFLACStreamInfo(
+    sampleRate: UInt32,
+    channels: Int,
+    bitsPerSample: Int,
+    totalSamples: Int64
+  ) -> Data {
+    var data = Data()
+    data.append("fLaC".data(using: .ascii)!)
+    // Block header: last-block flag (0x80) + type 0 (STREAMINFO) +
+    // 24-bit size = 34 bytes.
+    data.append(0x80)
+    data.append(beUInt24(34))
+    // Body. 34 bytes total.
+    var body = Data(repeating: 0, count: 34)
+    // minBlockSize, maxBlockSize, minFrameSize, maxFrameSize: bytes
+    // 0..9, leave zero. Bytes 10..12 contain the 20-bit sampleRate
+    // followed by 3-bit channels-1 and 5-bit bitsPerSample-1 split
+    // across bytes 12..13. totalSamples is 36 bits at bytes 13..17.
+    let sr = UInt32(sampleRate) & 0x000FFFFF
+    let chMinusOne = UInt8((channels - 1) & 0x07)
+    let bpsMinusOne = UInt8((bitsPerSample - 1) & 0x1F)
+    body[10] = UInt8((sr >> 12) & 0xFF)
+    body[11] = UInt8((sr >> 4) & 0xFF)
+    body[12] = UInt8(((sr & 0x0F) << 4) | (UInt32(chMinusOne) << 1) | UInt32(bpsMinusOne >> 4))
+    body[13] = UInt8(((bpsMinusOne & 0x0F) << 4) | UInt8((totalSamples >> 32) & 0x0F))
+    body[14] = UInt8((totalSamples >> 24) & 0xFF)
+    body[15] = UInt8((totalSamples >> 16) & 0xFF)
+    body[16] = UInt8((totalSamples >> 8) & 0xFF)
+    body[17] = UInt8(totalSamples & 0xFF)
+    // Bytes 18..33: MD5, leave zero.
+    data.append(body)
+    return data
+  }
+
+  private func beUInt24(_ v: UInt32) -> Data {
+    return Data([
+      UInt8((v >> 16) & 0xff),
+      UInt8((v >> 8) & 0xff),
+      UInt8(v & 0xff),
+    ])
+  }
+}

package/ios/Tests/GaplessEngineLifecycleTests.swift

@@ -173,12 +173,12 @@ final class GaplessEngineLifecycleTests: XCTestCase {
 
 private final class NoopDelegate: PlaybackEngineDelegate {
   func engineStateMaybeChanged(_ engine: PlaybackEngine, reason: StateChangeReason?) {}
-  func engineIsPlayingChanged(_ engine: PlaybackEngine, isPlaying: Bool) {}
   func engineDidTransitionTrack(_ engine: PlaybackEngine) {}
   func engineActiveItemFormatChanged(_ engine: PlaybackEngine) {}
-  func engineDidFailWithError(_ engine: PlaybackEngine, error: Error) {}
+  func engineDidFailWithError(
+    _ engine: PlaybackEngine, error: Error, item: AVPlayerItem?) {}
   func engineDidPlayItemToEnd(_ engine: PlaybackEngine) {}
   func enginePlaybackEnded(_ engine: PlaybackEngine) {}
-  func engineCrossfadeDidBegin(_ engine: PlaybackEngine, incomingIndex: Int) {}
-  func engineCrossfadeDidCancel(_ engine: PlaybackEngine, revertedIndex: Int) {}
+  func engineCrossfadeDidBegin(_ engine: PlaybackEngine) {}
+  func engineCrossfadeDidCancel(_ engine: PlaybackEngine) {}
 }

package/ios/Tests/InputGuardsTests.swift

@@ -8,8 +8,49 @@ import XCTest
 /// are covered without a live AVPlayer or AudioSession.
 final class InputGuardsTests: XCTestCase {
 
+  /// A finite value too large for `Int64` is as fatal as an infinite one once
+  /// it is scaled to milliseconds, so the guard bounds magnitude, not just
+  /// finiteness.
+  func testSeekPositionIsBoundedToAConvertibleMagnitude() throws {
+    let huge = try XCTUnwrap(InputGuards.sanitisedSeekPosition(1e300))
+    XCTAssertLessThan(huge * 1000.0, Double(Int64.max))
+    let negative = try XCTUnwrap(InputGuards.sanitisedSeekPosition(-1e300))
+    XCTAssertGreaterThan(negative * 1000.0, Double(Int64.min))
+  }
+
+  func testSeekPositionPassesOrdinaryValuesThrough() {
+    XCTAssertEqual(InputGuards.sanitisedSeekPosition(42.5), 42.5)
+    XCTAssertNil(InputGuards.sanitisedSeekPosition(.nan))
+    XCTAssertNil(InputGuards.sanitisedSeekPosition(.infinity))
+  }
+
+  /// The conversion has to be bounded in `Double` space; `Int(_:)` traps on a
+  /// finite value larger than `Int` before any clamp on the result can apply.
+  func testLookaheadCountIsBoundedBeforeConversion() {
+    XCTAssertEqual(InputGuards.validLookaheadCount(.infinity), 10_000)
+    XCTAssertEqual(InputGuards.validLookaheadCount(1e300), 10_000)
+    XCTAssertEqual(InputGuards.validLookaheadCount(.nan), 0)
+    XCTAssertEqual(InputGuards.validLookaheadCount(-5), 0)
+    XCTAssertEqual(InputGuards.validLookaheadCount(7), 7)
+  }
+
   // MARK: - validQueueIndex
 
+  /// A finite value past what `Int` holds means "append", the same as any
+  /// other position past the end; converting it first would trap.
+  func testInsertPositionClampsAMagnitudeIntCannotHold() {
+    XCTAssertEqual(InputGuards.insertPosition(1e300, count: 5), 5)
+    XCTAssertEqual(InputGuards.insertPosition(-1e300, count: 5), 0)
+  }
+
+  func testInsertPositionPassesOrdinaryValuesThroughAndDropsNonFinite() {
+    XCTAssertEqual(InputGuards.insertPosition(2, count: 5), 2)
+    XCTAssertEqual(InputGuards.insertPosition(7, count: 5), 5)
+    XCTAssertNil(InputGuards.insertPosition(nil, count: 5))
+    XCTAssertNil(InputGuards.insertPosition(.nan, count: 5))
+    XCTAssertNil(InputGuards.insertPosition(.infinity, count: 5))
+  }
+
   func testValidQueueIndexReturnsIntForInRangeValue() {
     XCTAssertEqual(InputGuards.validQueueIndex(0, count: 5), 0)
     XCTAssertEqual(InputGuards.validQueueIndex(2, count: 5), 2)

package/ios/Tests/InterruptionIntentTests.swift

@@ -0,0 +1,77 @@
+import XCTest
+@testable import QueuePlayer
+
+/// `isInterrupted` disables retries, window refills and network recovery
+/// while the system holds the session. The system does not always deliver
+/// the interruption's end, so the flag has user-side exits too.
+final class InterruptionIntentTests: XCTestCase {
+
+  private var player: TrackPlayer!
+
+  override func setUp() async throws {
+    try await super.setUp()
+    player = TrackPlayer()
+    _ = try await player.configure(config: PlayerFixtures.config()).await()
+    _ = try await player.setQueue(
+      tracks: PlayerFixtures.localTracks(count: 2, for: self), startAtIndex: 0
+    ).await()
+  }
+
+  override func tearDown() async throws {
+    if let player {
+      _ = try await player.destroy().await()
+    }
+    player = nil
+    try await super.tearDown()
+  }
+
+  /// An explicit play is the user ending the interruption from their side.
+  func testAnExplicitPlayEndsTheInterruption() async throws {
+    let player = try XCTUnwrap(self.player)
+    await player.onPlayerQueue { player.isInterrupted = true }
+
+    _ = try await player.play().await()
+
+    let interrupted = await player.onPlayerQueueValue { player.isInterrupted }
+    XCTAssertFalse(interrupted)
+  }
+
+  /// At the end of the queue play() does nothing: the engine is not asked to
+  /// play and the intent is not recorded, so a track a later skip seats waits
+  /// for its own play().
+  func testPlayAtTheEndOfTheQueueRestartsNothing() async throws {
+    let player = try XCTUnwrap(self.player)
+    let engine = ActiveItemEngineStub()
+    await player.onPlayerQueue {
+      player.engine = engine
+      player.reachedQueueEnd = true
+      player.wantsToPlay = false
+    }
+
+    _ = try await player.play().await()
+
+    XCTAssertEqual(engine.playCalls, 0, "the parked engine is left alone")
+    let state = await player.onPlayerQueueValue { (player.wantsToPlay, player.reachedQueueEnd) }
+    XCTAssertFalse(state.0, "no intent is recorded for a queue that is over")
+    XCTAssertTrue(state.1)
+  }
+
+  /// Nothing about the torn-down session survives into the next configure.
+  func testDestroyClearsTheInterruptionAndRecoveryFlags() async throws {
+    let player = try XCTUnwrap(self.player)
+    await player.onPlayerQueue {
+      player.isInterrupted = true
+      player.isRecoveringFromStall = true
+      player.engineReconcileDeferred = true
+    }
+
+    _ = try await player.destroy().await()
+
+    let flags = await player.onPlayerQueueValue {
+      (player.isInterrupted, player.isRecoveringFromStall, player.engineReconcileDeferred)
+    }
+    XCTAssertFalse(flags.0)
+    XCTAssertFalse(flags.1)
+    XCTAssertFalse(flags.2)
+  }
+}

package/ios/Tests/LookaheadCacheCellularAccessTests.swift

@@ -0,0 +1,185 @@
+import XCTest
+@testable import QueuePlayer
+
+/// Prefetch requests carry `allowsCellularAccess`, and `setLookaheadCache`
+/// changes it live — the cache instance and everything it holds on disk stay
+/// as they are.
+final class LookaheadCacheCellularAccessTests: XCTestCase {
+
+  private var tempDir: URL!
+  private var session: URLSession!
+
+  override func setUp() {
+    super.setUp()
+    tempDir = FileManager.default.temporaryDirectory
+      .appendingPathComponent("CellularAccess-\(UUID().uuidString)", isDirectory: true)
+    let config = URLSessionConfiguration.ephemeral
+    config.protocolClasses = [StubURLProtocol.self] + (config.protocolClasses ?? [])
+    session = URLSession(configuration: config)
+    StubURLProtocol.reset()
+  }
+
+  override func tearDown() {
+    session?.invalidateAndCancel()
+    try? FileManager.default.removeItem(at: tempDir)
+    StubURLProtocol.reset()
+    super.tearDown()
+  }
+
+  // MARK: - The request carries the policy
+
+  func testAPrefetchRequestIsAllowedOverCellularByDefault() async throws {
+    let cache = makeCache()
+    let url = URL(string: "https://example.com/default.m4a")!
+    StubURLProtocol.stub(url: url, data: Data("payload".utf8), statusCode: 200)
+
+    try await cache.download(track: makeTrack(id: "t", url: url.absoluteString), headers: nil)
+
+    XCTAssertEqual(StubURLProtocol.lastRequest(for: url)?.allowsCellularAccess, true)
+  }
+
+  func testAPrefetchRequestRefusesCellularWhenTheCacheIsToldTo() async throws {
+    let cache = makeCache(allowsCellularAccess: false)
+    let url = URL(string: "https://example.com/denied.m4a")!
+    StubURLProtocol.stub(url: url, data: Data("payload".utf8), statusCode: 200)
+
+    try await cache.download(track: makeTrack(id: "t", url: url.absoluteString), headers: nil)
+
+    XCTAssertEqual(StubURLProtocol.lastRequest(for: url)?.allowsCellularAccess, false)
+  }
+
+  func testTheNextRequestPicksUpAChangedPolicy() async throws {
+    let cache = makeCache()
+    let first = URL(string: "https://example.com/before.m4a")!
+    let second = URL(string: "https://example.com/after.m4a")!
+    StubURLProtocol.stub(url: first, data: Data("a".utf8), statusCode: 200)
+    StubURLProtocol.stub(url: second, data: Data("b".utf8), statusCode: 200)
+    try await cache.download(track: makeTrack(id: "a", url: first.absoluteString), headers: nil)
+
+    cache.allowsCellularAccess = false
+    try await cache.download(track: makeTrack(id: "b", url: second.absoluteString), headers: nil)
+
+    XCTAssertEqual(StubURLProtocol.lastRequest(for: first)?.allowsCellularAccess, true)
+    XCTAssertEqual(StubURLProtocol.lastRequest(for: second)?.allowsCellularAccess, false)
+  }
+
+  // MARK: - The runtime switch
+
+  /// `applyLookaheadConfig` is player-queue confined — the prefetcher asserts
+  /// it — so the tests reach it the way `setLookaheadCache` does.
+  private func apply(
+    _ player: TrackPlayer, enabled: Bool, count: Double, cellular: Bool?
+  ) throws {
+    var caught: Error?
+    player.playerQueue.sync {
+      do {
+        try player.applyLookaheadConfig(
+          LookaheadCacheConfig(
+            enabled: enabled, lookaheadCount: count, allowsCellularAccess: cellular))
+      } catch {
+        caught = error
+      }
+    }
+    if let caught { throw caught }
+  }
+
+  /// `enabled` starts true, so the cache only exists once the flag has been
+  /// cycled — the construction path a consumer hits at `configure()`.
+  private func playerWithCache() throws -> TrackPlayer {
+    let player = TrackPlayer()
+    try apply(player, enabled: false, count: 1, cellular: true)
+    try apply(player, enabled: true, count: 1, cellular: true)
+    return player
+  }
+
+  func testTurningCellularOffKeepsTheCacheAndOnlyChangesThePolicy() throws {
+    let player = try playerWithCache()
+    defer { _ = try? player.destroy() }
+    let cache = try XCTUnwrap(player.lookaheadCache)
+    XCTAssertTrue(cache.allowsCellularAccess)
+
+    try apply(player, enabled: true, count: 1, cellular: false)
+
+    XCTAssertTrue(cache === player.lookaheadCache, "nothing is rebuilt — the policy is live")
+    XCTAssertFalse(cache.allowsCellularAccess)
+  }
+
+  func testTurningCellularBackOnRestoresIt() throws {
+    let player = try playerWithCache()
+    defer { _ = try? player.destroy() }
+    try apply(player, enabled: true, count: 1, cellular: false)
+
+    try apply(player, enabled: true, count: 1, cellular: true)
+
+    XCTAssertTrue(try XCTUnwrap(player.lookaheadCache).allowsCellularAccess)
+  }
+
+  /// The cache is constructed lazily, so a policy set while it does not exist
+  /// has to reach the instance the next construction produces.
+  func testACacheBuiltAfterThePolicyWasSetHonoursIt() throws {
+    let player = TrackPlayer()
+    defer { _ = try? player.destroy() }
+    try apply(player, enabled: false, count: 1, cellular: false)
+    XCTAssertNil(player.lookaheadCache, "precondition: nothing built yet")
+
+    try apply(player, enabled: true, count: 1, cellular: false)
+
+    XCTAssertFalse(try XCTUnwrap(player.lookaheadCache).allowsCellularAccess)
+  }
+
+  /// An omitted `allowsCellularAccess` reads as permitted, so a consumer that
+  /// never sets it is not silently cut off from prefetching.
+  func testOmittingTheFlagLeavesCellularPermitted() throws {
+    let player = TrackPlayer()
+    defer { _ = try? player.destroy() }
+    try apply(player, enabled: false, count: 1, cellular: nil)
+    try apply(player, enabled: true, count: 1, cellular: nil)
+
+    XCTAssertTrue(try XCTUnwrap(player.lookaheadCache).allowsCellularAccess)
+  }
+
+  /// `configure()` builds the cache itself rather than going through
+  /// `applyLookaheadConfig`, so it has to read the stored policy too.
+  func testConfigureBuildsTheCacheUnderTheStoredPolicy() async throws {
+    let player = TrackPlayer()
+    // Prefetch stays enabled — configure only builds the cache when it is —
+    // and with no cache yet the policy lives in the stored config alone.
+    try apply(player, enabled: true, count: 1, cellular: false)
+    XCTAssertNil(player.lookaheadCache, "precondition: configure does the building")
+
+    _ = try await player.configure(config: Self.playerConfig()).await()
+    defer { _ = try? player.destroy() }
+
+    let cache = try XCTUnwrap(player.lookaheadCache)
+    XCTAssertFalse(cache.allowsCellularAccess)
+  }
+
+  private static func playerConfig() -> PlayerConfig {
+    return PlayerConfig(
+      httpHeaders: nil, userAgent: nil, placeholderArtworkUri: nil,
+      autoRetries: nil, retryBackoffMs: nil, networkTimeoutMs: nil,
+      audioContentType: nil, audioCategoryOptions: nil,
+      voiceVocabularyDonationEnabled: nil,
+      visualizationEnabled: nil, clampSeekToBuffered: nil,
+      skipToPreviousBehavior: nil, lookaheadCacheMaxSizeMb: nil,
+      lookaheadCacheEvictionPolicy: nil, progressUpdateIntervalMs: nil,
+      backgroundProgressUpdateIntervalMs: nil
+    )
+  }
+
+  private func makeTrack(id: String, url: String) -> TrackItem {
+    return TrackItem(
+      id: id, url: url, title: nil, artist: nil, album: nil,
+      duration: nil, artworkUrl: nil, extras: nil,
+      replayGainTrackGain: nil, replayGainTrackPeak: nil,
+      replayGainAlbumGain: nil, replayGainAlbumPeak: nil
+    )
+  }
+
+  private func makeCache(allowsCellularAccess: Bool = true) -> LookaheadCache {
+    LookaheadCache(
+      directory: tempDir, maxSizeBytes: 10 * 1024 * 1024, urlSession: session,
+      allowsCellularAccess: allowsCellularAccess
+    )
+  }
+}