react-native-queue-player 1.0.0

package/ios/MetadataReader.swift

@@ -0,0 +1,555 @@
+import Foundation
+
+/// Direct-bytes audio metadata reader for ReplayGain tags. Sniffs
+/// the container by leading magic bytes and dispatches to a format-
+/// specific parser. Reads the first 256 KB of the source — large
+/// enough to contain ID3v2 padding, FLAC metadata blocks, and the
+/// `moov` atom on most MP4 files. ReplayGain tags live near the
+/// start of every supported container so a bounded prefix read is
+/// always sufficient.
+///
+/// Why not `AVAsset.load(.metadata)`: every AVFoundation metadata
+/// load serialises through the demux pipeline; with many concurrent
+/// asset preparations, total wait runs to tens of seconds even for
+/// trivially-tagged local files. This module reads the container
+/// header directly without involving AVFoundation at all — sub-
+/// 100 ms per local file regardless of queue size.
+///
+/// Source-agnostic: `file://` reads via `FileHandle`, `http(s)://`
+/// reads via `URLSession` with a `Range: bytes=0-N` request. Same
+/// parsers handle both — only the byte-source shim differs.
+enum MetadataReader {
+
+  /// Default prefix read — large enough for ID3v2 padding, FLAC
+  /// metadata blocks, and the `moov` atom on standard MP4 files.
+  static let defaultPrefixBytes = 256 * 1024
+
+  /// Read the four `REPLAYGAIN_*` tags from a media URL. Returns
+  /// `nil` when the container is Opus (decoder-applied gain),
+  /// when none of the tags are present, or when the source can't
+  /// be read.
+  static func readReplayGainTags(
+    url: URL, urlSession: URLSession = .shared
+  ) async -> ReplayGainData? {
+    if isOpusContainer(url: url) { return nil }
+    guard let data = await fetchPrefixBytes(url: url, urlSession: urlSession) else { return nil }
+    return rgDataFromTags(parseTags(from: data))
+  }
+
+  // MARK: - Format dispatch
+
+  /// Sniff first bytes and route to the format-specific parser.
+  /// Returns a normalised `[upperKey: rawValue]` dict containing
+  /// every name/value pair the parser found (not just RG ones —
+  /// keeping the full set keeps the parser side reusable for
+  /// other tag categories later).
+  static func parseTags(from data: Data) -> [String: String] {
+    guard data.count >= 4 else { return [:] }
+    let b0 = data[0], b1 = data[1], b2 = data[2], b3 = data[3]
+    if b0 == 0x49 && b1 == 0x44 && b2 == 0x33 {
+      return parseID3v2(data)
+    }
+    if b0 == 0x66 && b1 == 0x4c && b2 == 0x61 && b3 == 0x43 {
+      return parseFLAC(data)
+    }
+    if data.count >= 8,
+       data[4] == 0x66 && data[5] == 0x74 && data[6] == 0x79 && data[7] == 0x70 {
+      return parseMP4(data)
+    }
+    return [:]
+  }
+
+  static func rgDataFromTags(_ tags: [String: String]) -> ReplayGainData? {
+    let upper = tags.reduce(into: [String: String]()) { d, kv in
+      d[kv.key.uppercased()] = kv.value
+    }
+    let trackGain = upper[ReplayGainExtractor.trackGainKey]
+      .flatMap { ReplayGainExtractor.parseGainDb($0) }
+    let trackPeak = upper[ReplayGainExtractor.trackPeakKey]
+      .flatMap { ReplayGainExtractor.parsePeak($0) }
+    let albumGain = upper[ReplayGainExtractor.albumGainKey]
+      .flatMap { ReplayGainExtractor.parseGainDb($0) }
+    let albumPeak = upper[ReplayGainExtractor.albumPeakKey]
+      .flatMap { ReplayGainExtractor.parsePeak($0) }
+    if trackGain == nil && trackPeak == nil
+       && albumGain == nil && albumPeak == nil {
+      return nil
+    }
+    return ReplayGainData(
+      trackGainDb: trackGain, trackPeak: trackPeak,
+      albumGainDb: albumGain, albumPeak: albumPeak
+    )
+  }
+
+  static func isOpusContainer(url: URL) -> Bool {
+    let ext = url.pathExtension.lowercased()
+    return ext == "opus" || ext == "ogg"
+  }
+
+  // MARK: - Byte fetch shim
+
+  /// File: `FileHandle` prefix read. HTTP/S: `URLSession` Range
+  /// request. Returns `nil` on read error or unsupported scheme.
+  static func fetchPrefixBytes(
+    url: URL, byteCount: Int = defaultPrefixBytes, urlSession: URLSession = .shared
+  ) async -> Data? {
+    if url.isFileURL {
+      do {
+        let handle = try FileHandle(forReadingFrom: url)
+        defer { try? handle.close() }
+        return handle.readData(ofLength: byteCount)
+      } catch {
+        return nil
+      }
+    }
+    guard let scheme = url.scheme?.lowercased(),
+          scheme == "http" || scheme == "https" else {
+      return nil
+    }
+    var req = URLRequest(url: url, timeoutInterval: 10)
+    req.setValue("bytes=0-\(byteCount - 1)", forHTTPHeaderField: "Range")
+    do {
+      let (data, response) = try await urlSession.data(for: req)
+      if let http = response as? HTTPURLResponse,
+         !(200...299).contains(http.statusCode) {
+        return nil
+      }
+      return data
+    } catch {
+      return nil
+    }
+  }
+
+  // MARK: - ID3v2 (MP3)
+
+  /// Parse ID3v2.2 / 2.3 / 2.4 TXXX (user-defined text) frames into
+  /// a `[description: value]` dict. Only TXXX is walked because RG
+  /// tags use that frame; standard text frames (TIT2 etc.) carry
+  /// title/artist/album which the player resolves via Now Playing
+  /// metadata, not this path.
+  ///
+  /// Tag-size, frame-size, and frame-id parsing follow the official
+  /// ID3v2 spec; v2.4 frames use syncsafe sizes, v2.2/2.3 use plain
+  /// big-endian. Unsynchronisation transformations (rare in modern
+  /// taggers) are not undone — empirical: foobar2000 / mp3tag emit
+  /// non-unsynchronised tags.
+  static func parseID3v2(_ data: Data) -> [String: String] {
+    guard data.count >= 10,
+          data[0] == 0x49, data[1] == 0x44, data[2] == 0x33 else {
+      return [:]
+    }
+    let majorVersion = data[3]
+    let flags = data[5]
+    let tagSize = Int(data[6] & 0x7f) << 21 |
+                  Int(data[7] & 0x7f) << 14 |
+                  Int(data[8] & 0x7f) << 7 |
+                  Int(data[9] & 0x7f)
+    let tagEnd = min(10 + tagSize, data.count)
+    var pos = 10
+
+    // Optional extended header (flag bit 0x40). v2.3 size is 4-byte
+    // BE excluding the 4 size bytes themselves; v2.4 is syncsafe and
+    // includes itself. Consumers + RG parsers don't care — skip past.
+    if flags & 0x40 != 0, pos + 4 <= tagEnd {
+      let extSize: Int
+      if majorVersion >= 4 {
+        extSize = Int(data[pos] & 0x7f) << 21 |
+                  Int(data[pos+1] & 0x7f) << 14 |
+                  Int(data[pos+2] & 0x7f) << 7 |
+                  Int(data[pos+3] & 0x7f)
+      } else {
+        extSize = Int(data[pos]) << 24 | Int(data[pos+1]) << 16 |
+                  Int(data[pos+2]) << 8 | Int(data[pos+3])
+        // v2.3 ext header size excludes itself.
+      }
+      pos += extSize + (majorVersion >= 4 ? 0 : 4)
+    }
+
+    // v2.2 used 3-byte frame IDs + 3-byte sizes. v2.3+ uses 4+4.
+    let frameIdLen = majorVersion <= 2 ? 3 : 4
+    let frameSizeLen = majorVersion <= 2 ? 3 : 4
+    let frameHeaderLen = frameIdLen + frameSizeLen + (majorVersion <= 2 ? 0 : 2)
+    let txxxId: String = majorVersion <= 2 ? "TXX" : "TXXX"
+
+    var result: [String: String] = [:]
+    while pos + frameHeaderLen <= tagEnd {
+      // Padding starts when frame ID is all zero.
+      if data[pos] == 0 { break }
+      let frameID = String(
+        data: data.subdata(in: pos..<(pos + frameIdLen)),
+        encoding: .isoLatin1
+      ) ?? ""
+      let sizePos = pos + frameIdLen
+      let frameSize: Int
+      if majorVersion >= 4 {
+        frameSize = Int(data[sizePos] & 0x7f) << 21 |
+                    Int(data[sizePos+1] & 0x7f) << 14 |
+                    Int(data[sizePos+2] & 0x7f) << 7 |
+                    Int(data[sizePos+3] & 0x7f)
+      } else if majorVersion == 3 {
+        frameSize = Int(data[sizePos]) << 24 | Int(data[sizePos+1]) << 16 |
+                    Int(data[sizePos+2]) << 8 | Int(data[sizePos+3])
+      } else {
+        frameSize = Int(data[sizePos]) << 16 | Int(data[sizePos+1]) << 8 |
+                    Int(data[sizePos+2])
+      }
+      let payloadStart = pos + frameHeaderLen
+      let payloadEnd = payloadStart + frameSize
+      if frameSize <= 0 || payloadEnd > tagEnd { break }
+      if frameID == txxxId,
+         let (desc, value) = parseTXXXFrame(
+            data.subdata(in: payloadStart..<payloadEnd)) {
+        result[desc] = value
+      }
+      pos = payloadEnd
+    }
+    return result
+  }
+
+  /// Decode a TXXX frame body into `(description, value)`. Encoding
+  /// byte at offset 0; description is null-terminated, value follows.
+  static func parseTXXXFrame(_ payload: Data) -> (String, String)? {
+    guard payload.count >= 2 else { return nil }
+    let encoding = payload[0]
+    let body = payload.subdata(in: 1..<payload.count)
+    switch encoding {
+    case 0:
+      return splitTXXXSingleNull(body, encoding: .isoLatin1)
+    case 3:
+      return splitTXXXSingleNull(body, encoding: .utf8)
+    case 1:
+      return splitTXXXDoubleNull(body)
+    case 2:
+      return splitTXXXDoubleNullFixed(body, encoding: .utf16BigEndian)
+    default:
+      return nil
+    }
+  }
+
+  static func splitTXXXSingleNull(
+    _ data: Data, encoding: String.Encoding
+  ) -> (String, String)? {
+    guard let nullIdx = data.firstIndex(of: 0) else { return nil }
+    let descBytes = data.subdata(in: data.startIndex..<nullIdx)
+    let valueStart = nullIdx + 1
+    let valueBytes = valueStart < data.endIndex
+      ? data.subdata(in: valueStart..<data.endIndex)
+      : Data()
+    guard let desc = String(data: descBytes, encoding: encoding),
+          let value = String(data: valueBytes, encoding: encoding) else {
+      return nil
+    }
+    return (stripBOM(desc), stripBOM(value))
+  }
+
+  /// Encoding-1 UTF-16 with per-string BOM. Description and value
+  /// each have their own BOM. Separator is `0x00 0x00` aligned on
+  /// a 16-bit boundary. Strips the leading BOM character (U+FEFF)
+  /// from the decoded result — Swift's `String(data:encoding:.utf16…)`
+  /// preserves the BOM byte-pair as a U+FEFF zero-width glyph when
+  /// the explicit endianness encoding is used, which would prevent
+  /// downstream `"REPLAYGAIN_*"` dictionary lookups from matching.
+  static func splitTXXXDoubleNull(_ data: Data) -> (String, String)? {
+    let bytes = [UInt8](data)
+    var i = 0
+    while i + 1 < bytes.count {
+      if bytes[i] == 0 && bytes[i + 1] == 0 && i % 2 == 0 {
+        let descBytes = Data(bytes[0..<i])
+        let valueBytes = (i + 2) < bytes.count
+          ? Data(bytes[(i + 2)..<bytes.count])
+          : Data()
+        let descEnc = detectUTF16Encoding(descBytes) ?? .utf16
+        let valueEnc = detectUTF16Encoding(valueBytes) ?? descEnc
+        guard let desc = String(data: descBytes, encoding: descEnc),
+              let value = String(data: valueBytes, encoding: valueEnc) else {
+          return nil
+        }
+        return (stripBOM(desc), stripBOM(value))
+      }
+      i += 1
+    }
+    return nil
+  }
+
+  /// Strip leading U+FEFF (UTF-16 BOM) and trim trailing null /
+  /// control characters from a decoded string. ID3v2 taggers
+  /// (foobar2000, mp3tag) commonly emit TXXX values with a trailing
+  /// `\0` even though the spec says the final field has no
+  /// terminator. Without this trim, downstream parsers
+  /// (`Double.init` for gain, dictionary key lookup for description)
+  /// fail on the embedded null character.
+  static func stripBOM(_ s: String) -> String {
+    var out = s
+    if out.first == "\u{FEFF}" {
+      out = String(out.dropFirst())
+    }
+    while let last = out.last, last == "\0" || last.isNewline
+       || last.unicodeScalars.first.map({ $0.value < 0x20 }) == true {
+      out = String(out.dropLast())
+    }
+    return out
+  }
+
+  static func splitTXXXDoubleNullFixed(
+    _ data: Data, encoding: String.Encoding
+  ) -> (String, String)? {
+    let bytes = [UInt8](data)
+    var i = 0
+    while i + 1 < bytes.count {
+      if bytes[i] == 0 && bytes[i + 1] == 0 && i % 2 == 0 {
+        let descBytes = Data(bytes[0..<i])
+        let valueBytes = (i + 2) < bytes.count
+          ? Data(bytes[(i + 2)..<bytes.count])
+          : Data()
+        guard let desc = String(data: descBytes, encoding: encoding),
+              let value = String(data: valueBytes, encoding: encoding) else {
+          return nil
+        }
+        return (stripBOM(desc), stripBOM(value))
+      }
+      i += 1
+    }
+    return nil
+  }
+
+  static func detectUTF16Encoding(_ data: Data) -> String.Encoding? {
+    guard data.count >= 2 else { return nil }
+    let b0 = data[data.startIndex]
+    let b1 = data[data.startIndex + 1]
+    if b0 == 0xFE && b1 == 0xFF { return .utf16BigEndian }
+    if b0 == 0xFF && b1 == 0xFE { return .utf16LittleEndian }
+    return nil
+  }
+
+  // MARK: - FLAC
+
+  /// FLAC STREAMINFO header values relevant to bitrate computation.
+  /// Reading these + the file's byte size gives an accurate average
+  /// encoded bitrate without involving AVFoundation.
+  struct FLACStreamInfo {
+    let sampleRate: Int      // Hz, 1..655350
+    let channelCount: Int    // 1..8
+    let bitsPerSample: Int   // 4..32
+    let totalSamples: Int64  // 0 = unknown
+  }
+
+  /// Parse a FLAC STREAMINFO block from a `fLaC`-prefixed buffer.
+  /// STREAMINFO is type 0 and is required by the FLAC spec to be the
+  /// FIRST metadata block. Returns nil when the buffer doesn't start
+  /// with the FLAC magic or the block layout is malformed.
+  ///
+  /// STREAMINFO body layout (34 bytes after the 4-byte block header):
+  /// - 16 bits: minBlockSize (samples)
+  /// - 16 bits: maxBlockSize
+  /// - 24 bits: minFrameSize (bytes)
+  /// - 24 bits: maxFrameSize
+  /// - 20 bits: sampleRate
+  /// -  3 bits: channels - 1
+  /// -  5 bits: bitsPerSample - 1
+  /// - 36 bits: totalSamples
+  /// - 128 bits: MD5
+  static func parseFLACStreamInfo(_ data: Data) -> FLACStreamInfo? {
+    guard data.count >= 4 + 4 + 34 else { return nil }
+    guard data[0] == 0x66, data[1] == 0x4c,
+          data[2] == 0x61, data[3] == 0x43 else { return nil }
+    let blockType = data[4] & 0x7f
+    guard blockType == 0 else { return nil }
+    let blockSize = Int(data[5]) << 16 | Int(data[6]) << 8 | Int(data[7])
+    guard blockSize >= 34, data.count >= 8 + blockSize else { return nil }
+    // STREAMINFO body starts at offset 8.
+    // Bits 64..83 (offset 10, 11, 12 in the body — i.e. data offsets
+    // 18, 19, 20): sampleRate (20 bits, big-endian).
+    let b18 = UInt64(data[18])
+    let b19 = UInt64(data[19])
+    let b20 = UInt64(data[20])
+    let sampleRate = Int((b18 << 12) | (b19 << 4) | (b20 >> 4))
+    let channels = Int((data[20] >> 1) & 0x07) + 1
+    let bitsPerSample = Int(((data[20] & 0x01) << 4) | (data[21] >> 4)) + 1
+    // totalSamples — 36 bits starting at byte 21 bit 4.
+    let t21 = Int64(data[21] & 0x0f)
+    let t22 = Int64(data[22])
+    let t23 = Int64(data[23])
+    let t24 = Int64(data[24])
+    let t25 = Int64(data[25])
+    let totalSamples =
+      (t21 << 32) | (t22 << 24) | (t23 << 16) | (t24 << 8) | t25
+    return FLACStreamInfo(
+      sampleRate: sampleRate,
+      channelCount: channels,
+      bitsPerSample: bitsPerSample,
+      totalSamples: totalSamples
+    )
+  }
+
+  /// Walk FLAC metadata blocks from the `fLaC` magic and return the
+  /// Vorbis-comment KEY=value dict from the first VORBIS_COMMENT
+  /// (block type 4). Stops at the last-block flag.
+  static func parseFLAC(_ data: Data) -> [String: String] {
+    guard data.count >= 8 else { return [:] }
+    guard data[0] == 0x66, data[1] == 0x4c,
+          data[2] == 0x61, data[3] == 0x43 else { return [:] }
+    var pos = 4
+    while pos + 4 <= data.count {
+      let header = data[pos]
+      let isLast = (header & 0x80) != 0
+      let blockType = header & 0x7f
+      let blockSize = Int(data[pos+1]) << 16 |
+                      Int(data[pos+2]) << 8 |
+                      Int(data[pos+3])
+      let blockStart = pos + 4
+      let blockEnd = blockStart + blockSize
+      if blockEnd > data.count { return [:] }
+      if blockType == 4 {
+        return parseVorbisComment(data.subdata(in: blockStart..<blockEnd))
+      }
+      if isLast { break }
+      pos = blockEnd
+    }
+    return [:]
+  }
+
+  /// Vorbis comment block layout: vendor-len (LE u32) + vendor +
+  /// count (LE u32) + count × (len LE u32, UTF-8 KEY=value).
+  static func parseVorbisComment(_ data: Data) -> [String: String] {
+    var pos = 0
+    func readU32LE() -> Int? {
+      guard pos + 4 <= data.count else { return nil }
+      let v = Int(data[pos]) |
+              (Int(data[pos+1]) << 8) |
+              (Int(data[pos+2]) << 16) |
+              (Int(data[pos+3]) << 24)
+      pos += 4
+      return v
+    }
+    guard let vendorLen = readU32LE(),
+          pos + vendorLen <= data.count else { return [:] }
+    pos += vendorLen
+    guard let count = readU32LE() else { return [:] }
+    var result: [String: String] = [:]
+    for _ in 0..<count {
+      guard let len = readU32LE(),
+            len >= 0,
+            pos + len <= data.count else { break }
+      let bytes = data.subdata(in: pos..<(pos + len))
+      pos += len
+      guard let str = String(data: bytes, encoding: .utf8) else { continue }
+      if let eqIdx = str.firstIndex(of: "=") {
+        let key = String(str[..<eqIdx])
+        let value = String(str[str.index(after: eqIdx)...])
+        result[key] = value
+      }
+    }
+    return result
+  }
+
+  // MARK: - MP4 / M4A iTunes-style atoms
+
+  /// Walk the MP4 atom tree to `moov.udta.meta.ilst` and return the
+  /// freeform `----` atoms keyed by their `name` value. iTunes
+  /// stores ReplayGain in freeform atoms (mean=`com.apple.iTunes`,
+  /// name=`REPLAYGAIN_*`, data=UTF-8 value).
+  static func parseMP4(_ data: Data) -> [String: String] {
+    guard let ilst = findAtomPath(
+      data, path: ["moov", "udta", "meta", "ilst"]
+    ) else {
+      return [:]
+    }
+    var pos = 0
+    var result: [String: String] = [:]
+    while pos + 8 <= ilst.count {
+      let size = Int(ilst[pos]) << 24 | Int(ilst[pos+1]) << 16 |
+                 Int(ilst[pos+2]) << 8 | Int(ilst[pos+3])
+      let type = String(
+        data: ilst.subdata(in: (pos+4)..<(pos+8)),
+        encoding: .isoLatin1
+      ) ?? ""
+      if size < 8 || pos + size > ilst.count { break }
+      let body = ilst.subdata(in: (pos+8)..<(pos+size))
+      if type == "----" {
+        if let (name, value) = parseFreeformAtom(body) {
+          result[name] = value
+        }
+      }
+      pos += size
+    }
+    return result
+  }
+
+  /// A `----` (freeform) atom contains three child atoms:
+  /// `mean` (issuer, e.g. com.apple.iTunes), `name` (tag key), and
+  /// `data` (tag value). The first two share an 8-byte header
+  /// (size + type) plus a 4-byte version+flags before the UTF-8
+  /// payload. The `data` atom's payload is preceded by 4 bytes of
+  /// type indicator + 4 bytes of locale.
+  static func parseFreeformAtom(_ data: Data) -> (String, String)? {
+    var pos = 0
+    var name: String?
+    var value: String?
+    while pos + 8 <= data.count {
+      let size = Int(data[pos]) << 24 | Int(data[pos+1]) << 16 |
+                 Int(data[pos+2]) << 8 | Int(data[pos+3])
+      let type = String(
+        data: data.subdata(in: (pos+4)..<(pos+8)),
+        encoding: .isoLatin1
+      ) ?? ""
+      if size < 8 || pos + size > data.count { break }
+      let body = data.subdata(in: (pos+8)..<(pos+size))
+      switch type {
+      case "name":
+        if body.count > 4 {
+          name = String(
+            data: body.subdata(in: 4..<body.count),
+            encoding: .utf8
+          )
+        }
+      case "data":
+        if body.count > 8 {
+          value = String(
+            data: body.subdata(in: 8..<body.count),
+            encoding: .utf8
+          )
+        }
+      default:
+        break
+      }
+      pos += size
+    }
+    if let name = name, let value = value {
+      return (name, value)
+    }
+    return nil
+  }
+
+  /// Walk an atom tree by name path. The `meta` atom in iTunes-
+  /// style MP4 carries a 4-byte version+flags prefix before its
+  /// children — the only path-walk quirk worth handling.
+  static func findAtomPath(_ data: Data, path: [String]) -> Data? {
+    var current = data
+    for name in path {
+      guard var body = findAtom(in: current, type: name) else { return nil }
+      if name == "meta" && body.count >= 4 {
+        body = body.subdata(in: 4..<body.count)
+      }
+      current = body
+    }
+    return current
+  }
+
+  static func findAtom(in data: Data, type: String) -> Data? {
+    var pos = 0
+    while pos + 8 <= data.count {
+      let size = Int(data[pos]) << 24 | Int(data[pos+1]) << 16 |
+                 Int(data[pos+2]) << 8 | Int(data[pos+3])
+      let typeStr = String(
+        data: data.subdata(in: (pos+4)..<(pos+8)),
+        encoding: .isoLatin1
+      ) ?? ""
+      if size < 8 || pos + size > data.count { return nil }
+      if typeStr == type {
+        return data.subdata(in: (pos+8)..<(pos+size))
+      }
+      pos += size
+    }
+    return nil
+  }
+}

package/ios/MilestoneTracker.swift

@@ -0,0 +1,63 @@
+/// Tracks fixed playback-progress milestones (25/50/75/90%) for the
+/// current track playthrough. Pure + deterministic (no AVFoundation), so
+/// it unit-tests directly.
+///
+/// A threshold emits only when forward playback crosses it: `seek` moves
+/// the baseline WITHOUT emitting (so thresholds a seek jumps over are
+/// suppressed), the first `tick` only establishes the baseline (so a
+/// mid-track start doesn't back-fire), and each threshold emits at most
+/// once per playthrough. `reset` begins a new playthrough (track change /
+/// repeat-one loop). With no computable duration (<= 0) nothing fires.
+struct MilestoneTracker {
+  static let milestones: [Int] = [25, 50, 75, 90]
+
+  private var fired: Set<Int> = []
+  private var lastFraction: Double?
+
+  /// Begin a fresh playthrough.
+  mutating func reset() {
+    fired.removeAll()
+    lastFraction = nil
+  }
+
+  /// Move the baseline to a seek target and CONSUME (without emitting)
+  /// every threshold at/below it — those were jumped, not played, so they
+  /// must not fire this playthrough. Consuming into `fired` (rather than
+  /// only moving the baseline) makes the suppress robust against a
+  /// progress tick that observes the post-seek position around the same
+  /// time as the seek: a consumed threshold can never fire regardless of
+  /// tick/seek ordering.
+  mutating func seek(durationSec: Double, positionSec: Double) {
+    guard let frac = fraction(durationSec: durationSec, positionSec: positionSec) else {
+      lastFraction = nil
+      return
+    }
+    for m in MilestoneTracker.milestones where Double(m) / 100 <= frac {
+      fired.insert(m)
+    }
+    lastFraction = frac
+  }
+
+  /// Advance from a progress tick; returns the milestones crossed by
+  /// forward playback since the previous observation, ascending.
+  mutating func tick(durationSec: Double, positionSec: Double) -> [Int] {
+    guard let frac = fraction(durationSec: durationSec, positionSec: positionSec) else {
+      return []
+    }
+    guard let prev = lastFraction else {
+      lastFraction = frac
+      return []
+    }
+    let crossed = MilestoneTracker.milestones.filter { m in
+      !fired.contains(m) && prev < Double(m) / 100 && Double(m) / 100 <= frac
+    }
+    fired.formUnion(crossed)
+    lastFraction = frac
+    return crossed
+  }
+
+  private func fraction(durationSec: Double, positionSec: Double) -> Double? {
+    guard durationSec > 0 else { return nil }
+    return positionSec / durationSec
+  }
+}