react-native-queue-player 1.0.0

package/ios/Tests/MetadataReaderTests.swift

@@ -0,0 +1,605 @@
+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.
+/// End-to-end "extract from a real media file" coverage lives in
+/// the auto-suite `replaygain.ts`.
+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/MilestoneTrackerTests.swift

@@ -0,0 +1,76 @@
+import XCTest
+@testable import QueuePlayer
+
+/// Unit tests for `MilestoneTracker` — the pure 25/50/75/90% crossing
+/// logic behind `onPlaybackMilestone`. Native wiring (progress tick,
+/// seek, track-change reset) is covered by the `playback-milestones`
+/// demo suite.
+final class MilestoneTrackerTests: XCTestCase {
+
+  /// 200s track, ticks every ~10s of media time.
+  private func play(_ t: inout MilestoneTracker, to seconds: Double, duration: Double = 200) -> [Int] {
+    t.tick(durationSec: duration, positionSec: seconds)
+  }
+
+  func testForwardPlaythroughFiresEachOnceInOrder() {
+    var t = MilestoneTracker()
+    var fired: [Int] = []
+    // Walk 0 -> 100% in 5% steps.
+    for pct in stride(from: 0, through: 100, by: 5) {
+      fired += play(&t, to: Double(pct) * 2) // 200s track => pct*2 seconds
+    }
+    XCTAssertEqual(fired, [25, 50, 75, 90])
+  }
+
+  func testFirstTickEstablishesBaselineAndDoesNotFire() {
+    var t = MilestoneTracker()
+    // First observation is already past 25/50 — a mid-track start.
+    XCTAssertEqual(t.tick(durationSec: 200, positionSec: 120), []) // 60%
+    // Only thresholds ahead of the start fire.
+    XCTAssertEqual(t.tick(durationSec: 200, positionSec: 152), [75])
+    XCTAssertEqual(t.tick(durationSec: 200, positionSec: 184), [90])
+  }
+
+  func testSeekPastThresholdsSuppressesThem() {
+    var t = MilestoneTracker()
+    _ = t.tick(durationSec: 200, positionSec: 10) // baseline 5%
+    // Seek straight to 80% — 25/50/75 are jumped, not played.
+    t.seek(durationSec: 200, positionSec: 160)
+    XCTAssertEqual(t.tick(durationSec: 200, positionSec: 164), []) // 82%
+    XCTAssertEqual(t.tick(durationSec: 200, positionSec: 182), [90]) // only 90 fires
+  }
+
+  func testEachThresholdFiresOnlyOncePerPlaythrough() {
+    var t = MilestoneTracker()
+    _ = t.tick(durationSec: 200, positionSec: 0)
+    XCTAssertEqual(t.tick(durationSec: 200, positionSec: 120), [25, 50]) // 60%
+    // Seek back to 10% and replay forward — already-fired thresholds
+    // do not re-fire.
+    t.seek(durationSec: 200, positionSec: 20)
+    XCTAssertEqual(t.tick(durationSec: 200, positionSec: 160), [75]) // 80%, 25/50 stay fired
+  }
+
+  func testResetReArmsForANewPlaythrough() {
+    var t = MilestoneTracker()
+    _ = t.tick(durationSec: 200, positionSec: 0)
+    XCTAssertEqual(t.tick(durationSec: 200, positionSec: 200), [25, 50, 75, 90])
+    t.reset()
+    _ = t.tick(durationSec: 200, positionSec: 0)
+    XCTAssertEqual(t.tick(durationSec: 200, positionSec: 200), [25, 50, 75, 90])
+  }
+
+  func testUnknownDurationFiresNothing() {
+    var t = MilestoneTracker()
+    XCTAssertEqual(t.tick(durationSec: 0, positionSec: 30), [])
+    XCTAssertEqual(t.tick(durationSec: 0, positionSec: 9999), [])
+    // Once a duration is known, milestones resume from the current point.
+    XCTAssertEqual(t.tick(durationSec: 200, positionSec: 100), []) // baseline 50%
+    XCTAssertEqual(t.tick(durationSec: 200, positionSec: 152), [75])
+  }
+
+  func testThresholdExactlyOnTickFires() {
+    var t = MilestoneTracker()
+    _ = t.tick(durationSec: 200, positionSec: 0)
+    XCTAssertEqual(t.tick(durationSec: 200, positionSec: 100), [25, 50]) // exactly 50%
+  }
+}