react-native-queue-player 1.1.2 → 2.0.0

package/ios/Tests/MetadataReaderTests.swift

@@ -1,603 +0,0 @@
-import XCTest
-@testable import QueuePlayer
-
-/// Byte-level unit tests for `MetadataReader`'s container parsers.
-/// Builds synthetic ID3v2 / FLAC / MP4 byte sequences in-memory and
-/// verifies tag extraction surfaces the expected `[key: value]` map.
-final class MetadataReaderTests: XCTestCase {
-
-  // MARK: - ID3v2 TXXX
-
-  func testID3v23ExtractsSingleTXXXReplayGainTrackGain() {
-    // ID3v2.3 with one TXXX frame:
-    //   description="REPLAYGAIN_TRACK_GAIN", value="-7.85 dB"
-    let data = makeID3v23(frames: [
-      .txxx(description: "REPLAYGAIN_TRACK_GAIN", value: "-7.85 dB")
-    ])
-    let tags = MetadataReader.parseID3v2(data)
-    XCTAssertEqual(tags["REPLAYGAIN_TRACK_GAIN"], "-7.85 dB")
-  }
-
-  func testID3v23ExtractsAllFourReplayGainTags() {
-    let data = makeID3v23(frames: [
-      .txxx(description: "REPLAYGAIN_TRACK_GAIN", value: "-7.85 dB"),
-      .txxx(description: "REPLAYGAIN_TRACK_PEAK", value: "1.160082"),
-      .txxx(description: "REPLAYGAIN_ALBUM_GAIN", value: "-6.05 dB"),
-      .txxx(description: "REPLAYGAIN_ALBUM_PEAK", value: "1.160082"),
-    ])
-    let tags = MetadataReader.parseID3v2(data)
-    XCTAssertEqual(tags["REPLAYGAIN_TRACK_GAIN"], "-7.85 dB")
-    XCTAssertEqual(tags["REPLAYGAIN_TRACK_PEAK"], "1.160082")
-    XCTAssertEqual(tags["REPLAYGAIN_ALBUM_GAIN"], "-6.05 dB")
-    XCTAssertEqual(tags["REPLAYGAIN_ALBUM_PEAK"], "1.160082")
-  }
-
-  func testID3v24ExtractsTXXXReplayGainTags() {
-    // v2.4 syncsafe frame size — verify the 28-bit decode path.
-    let data = makeID3v24(frames: [
-      .txxx(description: "REPLAYGAIN_TRACK_GAIN", value: "-7.85 dB"),
-    ])
-    let tags = MetadataReader.parseID3v2(data)
-    XCTAssertEqual(tags["REPLAYGAIN_TRACK_GAIN"], "-7.85 dB")
-  }
-
-  func testID3v23ReturnsEmptyForNonReplayGainTags() {
-    let data = makeID3v23(frames: [
-      .txxx(description: "TITLE", value: "A Song"),
-      .txxx(description: "ARTIST", value: "Some Band"),
-    ])
-    let tags = MetadataReader.parseID3v2(data)
-    // Parser returns ALL TXXX descriptions; consumer filters for RG.
-    // Confirm RG keys absent + non-RG present.
-    XCTAssertNil(tags["REPLAYGAIN_TRACK_GAIN"])
-    XCTAssertEqual(tags["TITLE"], "A Song")
-  }
-
-  func testID3v23ReturnsEmptyOnNonID3Bytes() {
-    let data = Data([0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00])
-    let tags = MetadataReader.parseID3v2(data)
-    XCTAssertTrue(tags.isEmpty)
-  }
-
-  /// foobar2000 emits TXXX values with a trailing `\0` even though
-  /// the spec leaves the final field unterminated. Decoded values
-  /// must be trimmed of the trailing null so downstream `Double.init`
-  /// parses the gain string cleanly.
-  func testID3v23TXXXWithEncodingZeroAndTrailingNullValue() {
-    // encoding=0 ISO-8859-1, description "REPLAYGAIN_TRACK_GAIN" + 00,
-    // value "-7.85 dB" + trailing 00 (foobar2000-style).
-    var payload = Data([0x00])
-    payload.append("REPLAYGAIN_TRACK_GAIN".data(using: .isoLatin1)!)
-    payload.append(0x00)
-    payload.append("-7.85 dB".data(using: .isoLatin1)!)
-    payload.append(0x00)
-    var tag = Data()
-    tag.append("TXXX".data(using: .ascii)!)
-    tag.append(beUInt32(UInt32(payload.count)))
-    tag.append(Data([0x00, 0x00]))
-    tag.append(payload)
-    var full = Data()
-    full.append("ID3".data(using: .ascii)!)
-    full.append(0x03) // major version
-    full.append(0x00) // minor
-    full.append(0x00) // flags
-    full.append(syncsafeUInt32(UInt32(tag.count)))
-    full.append(tag)
-    let tags = MetadataReader.parseID3v2(full)
-    XCTAssertEqual(tags["REPLAYGAIN_TRACK_GAIN"], "-7.85 dB",
-      "trailing-null TXXX value should round-trip clean — no \\0 in decoded value")
-    let rg = MetadataReader.rgDataFromTags(tags)
-    XCTAssertNotNil(rg)
-    XCTAssertEqual(rg?.trackGainDb, -7.85)
-  }
-
-  /// foobar2000 + most ID3v2.3 taggers write TXXX with encoding=01
-  /// (UTF-16 with BOM). Description and value each carry their own
-  /// `0xFF 0xFE` BOM. Decoded strings must NOT retain the BOM as a
-  /// leading U+FEFF — that would prevent `REPLAYGAIN_*` lookups.
-  func testID3v23TXXXWithUTF16BOMStripsBOMFromDescriptionAndValue() {
-    let payload = utf16BOMTXXXFramePayload(
-      description: "REPLAYGAIN_TRACK_GAIN",
-      value: "-7.85 dB"
-    )
-    var tag = Data()
-    tag.append("TXXX".data(using: .ascii)!)
-    tag.append(beUInt32(UInt32(payload.count)))
-    tag.append(Data([0x00, 0x00]))
-    tag.append(payload)
-    var full = Data()
-    full.append("ID3".data(using: .ascii)!)
-    full.append(0x03) // major version
-    full.append(0x00) // minor
-    full.append(0x00) // flags
-    full.append(syncsafeUInt32(UInt32(tag.count)))
-    full.append(tag)
-    let tags = MetadataReader.parseID3v2(full)
-    XCTAssertEqual(tags["REPLAYGAIN_TRACK_GAIN"], "-7.85 dB",
-      "BOM-prefixed UTF-16 description should map to bare REPLAYGAIN_TRACK_GAIN key")
-  }
-
-  // MARK: - FLAC Vorbis comments
-
-  func testFLACExtractsVorbisReplayGainTags() {
-    let data = makeFLAC(comments: [
-      "REPLAYGAIN_TRACK_GAIN=4.43 dB",
-      "REPLAYGAIN_TRACK_PEAK=0.621351",
-      "REPLAYGAIN_ALBUM_GAIN=0.30 dB",
-      "REPLAYGAIN_ALBUM_PEAK=0.923366",
-    ])
-    let tags = MetadataReader.parseFLAC(data)
-    XCTAssertEqual(tags["REPLAYGAIN_TRACK_GAIN"], "4.43 dB")
-    XCTAssertEqual(tags["REPLAYGAIN_TRACK_PEAK"], "0.621351")
-    XCTAssertEqual(tags["REPLAYGAIN_ALBUM_GAIN"], "0.30 dB")
-    XCTAssertEqual(tags["REPLAYGAIN_ALBUM_PEAK"], "0.923366")
-  }
-
-  func testFLACReturnsEmptyOnNonFLACBytes() {
-    let data = Data([0x00, 0x01, 0x02, 0x03])
-    let tags = MetadataReader.parseFLAC(data)
-    XCTAssertTrue(tags.isEmpty)
-  }
-
-  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(MetadataReader.parseFLACStreamInfo(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(MetadataReader.parseFLACStreamInfo(info))
-    XCTAssertEqual(parsed.sampleRate, 96000)
-    XCTAssertEqual(parsed.bitsPerSample, 24)
-    XCTAssertEqual(parsed.totalSamples, 9_876_543)
-  }
-
-  func testFLACStreamInfoReturnsNilOnNonFLACBytes() {
-    XCTAssertNil(MetadataReader.parseFLACStreamInfo(
-      Data([0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00])
-    ))
-  }
-
-  func testFLACSkipsStreamInfoAndReachesVorbisComment() {
-    // STREAMINFO (type 0, 34 bytes), then VORBIS_COMMENT (type 4).
-    // Verify the block walker advances past the first block.
-    let data = makeFLAC(
-      includeStreamInfo: true,
-      comments: ["REPLAYGAIN_TRACK_GAIN=-1.00 dB"]
-    )
-    let tags = MetadataReader.parseFLAC(data)
-    XCTAssertEqual(tags["REPLAYGAIN_TRACK_GAIN"], "-1.00 dB")
-  }
-
-  // MARK: - MP4 freeform iTunes-style atoms
-
-  func testMP4ExtractsFreeformReplayGainTags() {
-    let data = makeMP4(freeformTags: [
-      "REPLAYGAIN_TRACK_GAIN": "-3.21 dB",
-      "REPLAYGAIN_ALBUM_GAIN": "-2.10 dB",
-    ])
-    let tags = MetadataReader.parseMP4(data)
-    XCTAssertEqual(tags["REPLAYGAIN_TRACK_GAIN"], "-3.21 dB")
-    XCTAssertEqual(tags["REPLAYGAIN_ALBUM_GAIN"], "-2.10 dB")
-  }
-
-  func testMP4ReturnsEmptyWhenNoIlstAtom() {
-    // Just an ftyp atom with no moov.
-    var data = Data()
-    data.append(makeAtom(type: "ftyp", body: Data(repeating: 0, count: 16)))
-    let tags = MetadataReader.parseMP4(data)
-    XCTAssertTrue(tags.isEmpty)
-  }
-
-  // MARK: - Format dispatch (parseTags)
-
-  func testParseTagsDispatchesByMagicBytes() {
-    let mp3 = makeID3v23(frames: [
-      .txxx(description: "REPLAYGAIN_TRACK_GAIN", value: "-1.0 dB")
-    ])
-    XCTAssertEqual(
-      MetadataReader.parseTags(from: mp3)["REPLAYGAIN_TRACK_GAIN"], "-1.0 dB"
-    )
-
-    let flac = makeFLAC(comments: ["REPLAYGAIN_TRACK_GAIN=-2.0 dB"])
-    XCTAssertEqual(
-      MetadataReader.parseTags(from: flac)["REPLAYGAIN_TRACK_GAIN"], "-2.0 dB"
-    )
-
-    let mp4 = makeMP4(freeformTags: ["REPLAYGAIN_TRACK_GAIN": "-3.0 dB"])
-    XCTAssertEqual(
-      MetadataReader.parseTags(from: mp4)["REPLAYGAIN_TRACK_GAIN"], "-3.0 dB"
-    )
-  }
-
-  // MARK: - rgDataFromTags integration
-
-  func testRgDataFromTagsParsesAllFourFields() throws {
-    let data = try XCTUnwrap(MetadataReader.rgDataFromTags([
-      "REPLAYGAIN_TRACK_GAIN": "-12.0 dB",
-      "REPLAYGAIN_TRACK_PEAK": "0.95",
-      "REPLAYGAIN_ALBUM_GAIN": "-8.0 dB",
-      "REPLAYGAIN_ALBUM_PEAK": "0.90",
-    ]))
-    XCTAssertEqual(try XCTUnwrap(data.trackGainDb), -12.0, accuracy: 0.001)
-    XCTAssertEqual(try XCTUnwrap(data.trackPeak), 0.95, accuracy: 0.001)
-    XCTAssertEqual(try XCTUnwrap(data.albumGainDb), -8.0, accuracy: 0.001)
-    XCTAssertEqual(try XCTUnwrap(data.albumPeak), 0.90, accuracy: 0.001)
-  }
-
-  func testRgDataFromTagsAcceptsLowercaseKeys() throws {
-    let data = try XCTUnwrap(MetadataReader.rgDataFromTags([
-      "replaygain_track_gain": "-6.5 dB",
-    ]))
-    XCTAssertEqual(try XCTUnwrap(data.trackGainDb), -6.5, accuracy: 0.001)
-  }
-
-  func testRgDataFromTagsReturnsNilForEmptyDict() {
-    XCTAssertNil(MetadataReader.rgDataFromTags([:]))
-  }
-
-  func testRgDataFromTagsReturnsNilWhenAllValuesUnparseable() {
-    XCTAssertNil(MetadataReader.rgDataFromTags([
-      "REPLAYGAIN_TRACK_GAIN": "garbage",
-      "REPLAYGAIN_TRACK_PEAK": "1.0",  // encoder default → rejected
-    ]))
-  }
-
-  // MARK: - Opus container guard
-
-  func testIsOpusContainerRecognisesOpusExtension() {
-    XCTAssertTrue(
-      MetadataReader.isOpusContainer(
-        url: URL(string: "https://example.test/track.opus")!
-      )
-    )
-    XCTAssertTrue(
-      MetadataReader.isOpusContainer(
-        url: URL(string: "https://example.test/track.ogg")!
-      )
-    )
-  }
-
-  func testIsOpusContainerReturnsFalseForOtherFormats() {
-    XCTAssertFalse(
-      MetadataReader.isOpusContainer(
-        url: URL(string: "https://example.test/track.mp3")!
-      )
-    )
-    XCTAssertFalse(
-      MetadataReader.isOpusContainer(
-        url: URL(string: "https://example.test/track.m4a")!
-      )
-    )
-    XCTAssertFalse(
-      MetadataReader.isOpusContainer(
-        url: URL(string: "https://example.test/track.flac")!
-      )
-    )
-  }
-
-  // MARK: - End-to-end with file bytes
-
-  func testReadReplayGainTagsFromTempFileMP3() async throws {
-    let bytes = makeID3v23(frames: [
-      .txxx(description: "REPLAYGAIN_TRACK_GAIN", value: "-7.85 dB"),
-      .txxx(description: "REPLAYGAIN_TRACK_PEAK", value: "1.160082"),
-    ])
-    let url = try writeTempFile(bytes: bytes, suffix: ".mp3")
-    defer { try? FileManager.default.removeItem(at: url) }
-    let result = await MetadataReader.readReplayGainTags(url: url)
-    let data = try XCTUnwrap(result)
-    XCTAssertEqual(try XCTUnwrap(data.trackGainDb), -7.85, accuracy: 0.001)
-    XCTAssertEqual(try XCTUnwrap(data.trackPeak), 1.160082, accuracy: 0.001)
-    XCTAssertNil(data.albumGainDb)
-    XCTAssertNil(data.albumPeak)
-  }
-
-  func testReadReplayGainTagsFromTempFileFLAC() async throws {
-    let bytes = makeFLAC(comments: [
-      "REPLAYGAIN_TRACK_GAIN=4.43 dB",
-      "REPLAYGAIN_ALBUM_GAIN=0.30 dB",
-    ])
-    let url = try writeTempFile(bytes: bytes, suffix: ".flac")
-    defer { try? FileManager.default.removeItem(at: url) }
-    let result = await MetadataReader.readReplayGainTags(url: url)
-    let data = try XCTUnwrap(result)
-    XCTAssertEqual(try XCTUnwrap(data.trackGainDb), 4.43, accuracy: 0.001)
-    XCTAssertEqual(try XCTUnwrap(data.albumGainDb), 0.30, accuracy: 0.001)
-  }
-
-  func testReadReplayGainTagsReturnsNilForOpusURL() async {
-    let url = URL(string: "https://example.test/track.opus")!
-    let result = await MetadataReader.readReplayGainTags(url: url)
-    XCTAssertNil(result)
-  }
-
-  func testReadReplayGainTagsCompletesSubSecond() async throws {
-    // Latency budget: a local-file extract has no excuse to be slow.
-    // ID3v2 / FLAC / MP4 metadata sits at file start; the parser
-    // walks ≤256 KB of bytes in pure Swift. 100 ms is generous on
-    // any host; missing this budget is a regression.
-    let bytes = makeID3v23(frames: [
-      .txxx(description: "REPLAYGAIN_TRACK_GAIN", value: "-7.85 dB"),
-    ])
-    let url = try writeTempFile(bytes: bytes, suffix: ".mp3")
-    defer { try? FileManager.default.removeItem(at: url) }
-    let started = Date()
-    _ = await MetadataReader.readReplayGainTags(url: url)
-    let elapsed = Date().timeIntervalSince(started)
-    XCTAssertLessThan(elapsed, 0.1,
-      "extract took \(elapsed)s for a small local file — should be <100 ms")
-  }
-
-  // MARK: - Test helpers — byte-level fixture builders
-
-  private func writeTempFile(bytes: Data, suffix: String) throws -> URL {
-    let url = FileManager.default.temporaryDirectory
-      .appendingPathComponent(UUID().uuidString + suffix)
-    try bytes.write(to: url)
-    return url
-  }
-
-  private enum Frame {
-    case txxx(description: String, value: String)
-  }
-
-  /// Build a TXXX frame body with encoding=01 (UTF-16 with BOM).
-  /// Description gets `0xFF 0xFE` BOM + UTF-16LE encoded chars + `00 00`
-  /// terminator. Value follows with its own BOM + chars (no trailing
-  /// terminator).
-  private func utf16BOMTXXXFramePayload(
-    description: String,
-    value: String
-  ) -> Data {
-    var payload = Data([0x01]) // encoding byte: UTF-16 with BOM
-    payload.append(contentsOf: [0xFF, 0xFE])
-    payload.append(description.data(using: .utf16LittleEndian) ?? Data())
-    payload.append(contentsOf: [0x00, 0x00]) // null terminator
-    payload.append(contentsOf: [0xFF, 0xFE])
-    payload.append(value.data(using: .utf16LittleEndian) ?? Data())
-    return payload
-  }
-
-  /// Build an ID3v2.3 tag containing the given TXXX frames.
-  /// Returns the tag bytes only — no MP3 audio frames follow.
-  private func makeID3v23(frames: [Frame]) -> Data {
-    return makeID3v2(majorVersion: 3, frames: frames)
-  }
-
-  /// Build an ID3v2.4 tag containing the given TXXX frames.
-  private func makeID3v24(frames: [Frame]) -> Data {
-    return makeID3v2(majorVersion: 4, frames: frames)
-  }
-
-  private func makeID3v2(majorVersion: UInt8, frames: [Frame]) -> Data {
-    var frameBlock = Data()
-    for frame in frames {
-      switch frame {
-      case .txxx(let desc, let value):
-        // TXXX payload: encoding (0x03 UTF-8) + description + 0x00 + value
-        var payload = Data([0x03])
-        payload.append(desc.data(using: .utf8) ?? Data())
-        payload.append(0x00)
-        payload.append(value.data(using: .utf8) ?? Data())
-        // Frame header: 4-byte ID, 4-byte size, 2-byte flags.
-        frameBlock.append("TXXX".data(using: .ascii)!)
-        if majorVersion >= 4 {
-          frameBlock.append(syncsafeUInt32(UInt32(payload.count)))
-        } else {
-          frameBlock.append(beUInt32(UInt32(payload.count)))
-        }
-        frameBlock.append(Data([0x00, 0x00]))
-        frameBlock.append(payload)
-      }
-    }
-    var tag = Data()
-    tag.append("ID3".data(using: .ascii)!)
-    tag.append(majorVersion)
-    tag.append(0x00)  // minor version
-    tag.append(0x00)  // flags
-    tag.append(syncsafeUInt32(UInt32(frameBlock.count)))
-    tag.append(frameBlock)
-    return tag
-  }
-
-  /// 28-bit syncsafe encode (used by ID3v2 tag size + v2.4 frame size).
-  private func syncsafeUInt32(_ v: UInt32) -> Data {
-    return Data([
-      UInt8((v >> 21) & 0x7f),
-      UInt8((v >> 14) & 0x7f),
-      UInt8((v >> 7) & 0x7f),
-      UInt8(v & 0x7f),
-    ])
-  }
-
-  private func beUInt32(_ v: UInt32) -> Data {
-    return Data([
-      UInt8((v >> 24) & 0xff),
-      UInt8((v >> 16) & 0xff),
-      UInt8((v >> 8) & 0xff),
-      UInt8(v & 0xff),
-    ])
-  }
-
-  private func leUInt32(_ v: UInt32) -> Data {
-    return Data([
-      UInt8(v & 0xff),
-      UInt8((v >> 8) & 0xff),
-      UInt8((v >> 16) & 0xff),
-      UInt8((v >> 24) & 0xff),
-    ])
-  }
-
-  /// Build a minimal FLAC stream — `fLaC` magic + optional STREAMINFO
-  /// + VORBIS_COMMENT block. The VORBIS_COMMENT is marked last when
-  /// it's the only block (or the last block if STREAMINFO precedes).
-  private func makeFLAC(
-    includeStreamInfo: Bool = false,
-    comments: [String]
-  ) -> Data {
-    var data = Data()
-    data.append("fLaC".data(using: .ascii)!)
-    if includeStreamInfo {
-      // STREAMINFO is type 0, 34-byte body. Not last (VORBIS_COMMENT
-      // follows). Body content doesn't matter for the parser test.
-      data.append(0x00)
-      data.append(beUInt24(34))
-      data.append(Data(repeating: 0, count: 34))
-    }
-    // Build VORBIS_COMMENT block body.
-    var body = Data()
-    let vendor = "test-vendor".data(using: .utf8)!
-    body.append(leUInt32(UInt32(vendor.count)))
-    body.append(vendor)
-    body.append(leUInt32(UInt32(comments.count)))
-    for c in comments {
-      let bytes = c.data(using: .utf8)!
-      body.append(leUInt32(UInt32(bytes.count)))
-      body.append(bytes)
-    }
-    // Header: last-block flag (0x80) + type (4)
-    data.append(0x84)
-    data.append(beUInt24(UInt32(body.count)))
-    data.append(body)
-    return data
-  }
-
-  /// Build a FLAC header with only a STREAMINFO block (last-block
-  /// flag set), populated with the given values. Layout per FLAC
-  /// spec — 16+16+24+24 bits of block sizes are zeroed; the bits
-  /// the parser actually reads (sampleRate, channels, bitsPerSample,
-  /// totalSamples) are packed in.
-  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),
-    ])
-  }
-
-  /// Wrap a body in an MP4 atom (`size` BE u32 + 4-byte type + body).
-  private func makeAtom(type: String, body: Data) -> Data {
-    var data = Data()
-    let total = UInt32(8 + body.count)
-    data.append(beUInt32(total))
-    data.append(type.data(using: .ascii)!)
-    data.append(body)
-    return data
-  }
-
-  /// Build a minimal MP4 with `moov.udta.meta.ilst` containing
-  /// freeform `----` atoms for each (key, value) pair.
-  private func makeMP4(freeformTags: [String: String]) -> Data {
-    // Build ilst body — sequence of `----` atoms.
-    var ilstBody = Data()
-    for (key, value) in freeformTags {
-      var freeformBody = Data()
-      // mean atom: 4-byte version+flags + UTF-8 issuer.
-      var meanInner = Data([0x00, 0x00, 0x00, 0x00])
-      meanInner.append("com.apple.iTunes".data(using: .utf8)!)
-      freeformBody.append(makeAtom(type: "mean", body: meanInner))
-      // name atom: 4-byte version+flags + UTF-8 key.
-      var nameInner = Data([0x00, 0x00, 0x00, 0x00])
-      nameInner.append(key.data(using: .utf8)!)
-      freeformBody.append(makeAtom(type: "name", body: nameInner))
-      // data atom: 4-byte type indicator (1=UTF-8) + 4-byte locale + value.
-      var dataInner = Data([0x00, 0x00, 0x00, 0x01, 0x00, 0x00, 0x00, 0x00])
-      dataInner.append(value.data(using: .utf8)!)
-      freeformBody.append(makeAtom(type: "data", body: dataInner))
-      ilstBody.append(makeAtom(type: "----", body: freeformBody))
-    }
-    let ilst = makeAtom(type: "ilst", body: ilstBody)
-    // meta atom: 4-byte version+flags prefix + ilst.
-    var metaBody = Data([0x00, 0x00, 0x00, 0x00])
-    metaBody.append(ilst)
-    let meta = makeAtom(type: "meta", body: metaBody)
-    let udta = makeAtom(type: "udta", body: meta)
-    let moov = makeAtom(type: "moov", body: udta)
-    // ftyp box at the start.
-    let ftyp = makeAtom(type: "ftyp", body: Data([
-      0x4d, 0x34, 0x41, 0x20,  // M4A_
-      0x00, 0x00, 0x00, 0x00,  // minor version
-      0x4d, 0x34, 0x41, 0x20,  // compatible brand
-    ]))
-    var data = Data()
-    data.append(ftyp)
-    data.append(moov)
-    return data
-  }
-
-  // MARK: - Remote fetch uses the injected session (no real network)
-
-  func testFetchPrefixBytesUsesInjectedSessionForRemoteUrl() async {
-    let config = URLSessionConfiguration.ephemeral
-    config.protocolClasses = [StubURLProtocol.self]
-    let session = URLSession(configuration: config)
-    StubURLProtocol.reset()
-    defer { StubURLProtocol.reset() }
-    // `.test` is a reserved non-resolvable TLD — if the read ever hit the
-    // real network instead of the injected session it would fail with
-    // -1003 and never reach the stub.
-    let url = URL(string: "https://example.test/meta.mp3")!
-    let blob = Data("ID3-mock-prefix-bytes".utf8)
-    StubURLProtocol.stub(url: url, data: blob, statusCode: 200)
-
-    let bytes = await MetadataReader.fetchPrefixBytes(url: url, urlSession: session)
-
-    XCTAssertEqual(bytes, blob, "remote prefix read must resolve via the injected session")
-    XCTAssertEqual(
-      StubURLProtocol.requestCount(for: url), 1,
-      "must fetch through the injected session, never URLSession.shared")
-  }
-}

package/ios/Tests/PlaybackEngineProtocolTests.swift

@@ -1,92 +0,0 @@
-import AVFoundation
-import XCTest
-@testable import QueuePlayer
-
-/// Type-check coverage for `PlaybackEngine` + `PlaybackEngineDelegate`
-/// + `AudioMixProvider`. The protocols have no runtime; this suite
-/// exercises the type surface so a regression that drops a method
-/// or rotates a parameter shape surfaces immediately. Goes away once
-/// the real `GaplessEngine` impl pins the type surface from a
-/// runtime perspective.
-final class PlaybackEngineProtocolTests: XCTestCase {
-
-  func testProtocolSurfaceCompiles() {
-    let stub = NoopPlaybackEngine()
-    XCTAssertEqual(stub.currentMediaItemIndex, -1)
-    XCTAssertEqual(stub.currentPositionSeconds, 0)
-    XCTAssertEqual(stub.currentDurationSeconds, 0)
-    XCTAssertEqual(stub.bufferedPositionSeconds, 0)
-    XCTAssertFalse(stub.isPlaying)
-    XCTAssertNil(stub.currentMediaItem)
-    XCTAssertEqual(stub.allMediaItems.count, 0)
-  }
-
-  func testDelegateSurfaceCompiles() {
-    let delegate = NoopDelegate()
-    let stub = NoopPlaybackEngine()
-    stub.delegate = delegate
-    XCTAssertTrue(stub.delegate === delegate)
-  }
-
-  func testAudioMixProviderRegistration() {
-    let stub = NoopPlaybackEngine()
-    let provider = NoopMixProvider()
-    stub.setAudioMixProvider(provider)
-    stub.refreshAllItemMixes()
-    stub.setAudioMixProvider(nil)
-  }
-}
-
-private final class NoopPlaybackEngine: PlaybackEngine {
-  func prepare(items: [AVPlayerItem], startIndex: Int, startPositionSeconds: TimeInterval) async {}
-  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] { [] }
-
-  func setAudioMixProvider(_ provider: AudioMixProvider?) {}
-  func refreshAllItemMixes() {}
-
-  func handoff(to nextEngine: PlaybackEngine, atTrackBoundary: Bool) async {}
-
-  var delegate: PlaybackEngineDelegate?
-}
-
-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 engineDidPlayItemToEnd(_ engine: PlaybackEngine) {}
-  func enginePlaybackEnded(_ engine: PlaybackEngine) {}
-  func engineCrossfadeDidBegin(_ engine: PlaybackEngine, incomingIndex: Int) {}
-  func engineCrossfadeDidCancel(_ engine: PlaybackEngine, revertedIndex: Int) {}
-}
-
-private final class NoopMixProvider: AudioMixProvider {
-  func audioMix(for item: AVPlayerItem) -> AVAudioMix? { nil }
-}