react-native-queue-player 1.2.0 → 2.0.1

package/ios/ReplayGainExtractor.swift

@@ -1,20 +1,20 @@
 import Foundation
 
-/// Read the four ReplayGain tags from a media URL via direct byte
-/// parsing (`MetadataReader`) and parse the raw string values into
-/// `ReplayGainData`.
+/// The ReplayGain value layer: the four tag names, the numeric
+/// acceptance rules, the string parsers that feed them, and the
+/// assembly of a `ReplayGainData` from a name/value dictionary.
 ///
-/// Tag-format coverage matches `MetadataReader`:
-/// - MP3 ID3v2.2 / 2.3 / 2.4 TXXX (user-defined text) frames
-/// - FLAC Vorbis comments
-/// - MP4 / M4A iTunes-style freeform `----` atoms
-/// - Opus containers return `nil` (decoder-applied gain would
-///   double-correct under tag-applied RG)
+/// Deliberately source-agnostic. Names arrive from
+/// `AssetReplayGainReader`, which derives them from whatever shape
+/// the container gave AVFoundation (ID3 `TXXX` info fields, Vorbis
+/// comment keys, M4A freeform reverse-DNS keys); values arrive as the
+/// raw strings those tags carry. Every entry point lands on the same
+/// `acceptGainDb` / `acceptPeak` pair so one rule governs all of them.
 ///
 /// Parser tolerance follows NOTES.md §25 — `" dB"` suffix optional,
 /// `+/-` prefix optional, U+2212 minus sign normalised, period
-/// decimal, whitespace tolerant, NaN/Inf rejected. Description
-/// match is case-insensitive.
+/// decimal, whitespace tolerant, NaN/Inf rejected. Name matching is
+/// case-insensitive.
 enum ReplayGainExtractor {
 
   // Tag descriptions matched (case-insensitive).
@@ -23,18 +23,66 @@ enum ReplayGainExtractor {
   static let albumGainKey = "REPLAYGAIN_ALBUM_GAIN"
   static let albumPeakKey = "REPLAYGAIN_ALBUM_PEAK"
 
-  /// Read the four ReplayGain tags from `url`. Returns `nil` if no
-  /// RG tag was found or the source can't be read. Sub-100 ms for
-  /// local files; ~50-300 ms for `http(s)://` (network-dependent).
-  static func extract(from url: URL) async -> ReplayGainData? {
-    return await MetadataReader.readReplayGainTags(url: url)
+  // MARK: - Tag assembly
+
+  /// Build a `ReplayGainData` from a `[name: rawValue]` dictionary.
+  /// Names are matched case-insensitively against the four constants
+  /// above; each value goes through the parser for its kind, so an
+  /// unparseable or out-of-band value lands as `nil` rather than
+  /// rejecting its siblings.
+  ///
+  /// Returns `nil` when none of the four names produced a usable
+  /// value — "this source carries no ReplayGain".
+  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[trackGainKey].flatMap { parseGainDb($0) }
+    let trackPeak = upper[trackPeakKey].flatMap { parsePeak($0) }
+    let albumGain = upper[albumGainKey].flatMap { parseGainDb($0) }
+    let albumPeak = upper[albumPeakKey].flatMap { parsePeak($0) }
+    if trackGain == nil && trackPeak == nil
+       && albumGain == nil && albumPeak == nil {
+      return nil
+    }
+    return ReplayGainData(
+      trackGainDb: trackGain, trackPeak: trackPeak,
+      albumGainDb: albumGain, albumPeak: albumPeak
+    )
+  }
+
+  // MARK: - Numeric acceptance
+
+  /// Shared numeric acceptance for a gain in dB, whatever entry point
+  /// it arrived through — a tag string via `parseGainDb` or a number
+  /// straight from the consumer. Rejects only non-finite values: a
+  /// gain carries no plausible range guard, unlike a peak, and clip
+  /// safety is the gain clamp's job rather than the acceptor's.
+  static func acceptGainDb(_ value: Double) -> Double? {
+    guard value.isFinite else { return nil }
+    return value
+  }
+
+  /// Shared numeric acceptance for a linear peak, whatever entry point
+  /// it arrived through — a tag string via `parsePeak` or a number
+  /// straight from the consumer. Accepts `0.001 ... 2.0` inclusive:
+  /// `1.0` is the spec's encoding of digital full scale and is a real
+  /// measurement, and values above it are ordinary true peaks. Rejects
+  /// non-finite values, anything below the encoder-zero floor and
+  /// anything above an implausible true peak.
+  static func acceptPeak(_ value: Double) -> Double? {
+    guard value.isFinite else { return nil }
+    guard value >= 0.001, value <= 2.0 else { return nil }
+    return value
   }
 
   // MARK: - Gain parsing
 
   /// Parse a `REPLAYGAIN_*_GAIN` string (e.g. `"-6.54 dB"`,
   /// `"+3.21"`, `"−1.0 dB"` with U+2212 minus) into a Double dB.
-  /// Returns `nil` for unparseable / NaN / Inf inputs.
+  /// Returns `nil` for unparseable input; the parsed number is then
+  /// put through `acceptGainDb`, so text handling is all this adds
+  /// over the numeric entry point.
   static func parseGainDb(_ rawInput: String) -> Double? {
     var trimmed = rawInput.trimmingCharacters(in: .whitespacesAndNewlines)
     guard !trimmed.isEmpty else { return nil }
@@ -62,21 +110,16 @@ enum ReplayGainExtractor {
     if trimmed.contains(",") { return nil }
 
     guard let value = Double(trimmed) else { return nil }
-    if !value.isFinite { return nil }
-    return value
+    return acceptGainDb(value)
   }
 
   /// Parse a `REPLAYGAIN_*_PEAK` string (linear, period decimal).
-  /// Returns `nil` for unparseable / NaN / Inf / out-of-range
-  /// values, or for the encoder-default sentinels (peak `< 0.001`
-  /// or peak exactly `1.0`, both signal the analyser didn't run).
+  /// Returns `nil` for unparseable input; the parsed number is then
+  /// put through `acceptPeak`, which holds the `0.001 ... 2.0`
+  /// acceptance band — a full-scale `1.0` included.
   static func parsePeak(_ rawInput: String) -> Double? {
     let trimmed = rawInput.trimmingCharacters(in: .whitespacesAndNewlines)
     guard let value = Double(trimmed) else { return nil }
-    if !value.isFinite { return nil }
-    if value > 2.0 { return nil }
-    if value < 0.001 { return nil }
-    if value == 1.0 { return nil }
-    return value
+    return acceptPeak(value)
   }
 }

package/ios/Siri/VoiceDonation.swift

@@ -15,19 +15,24 @@ import OSLog
 enum VoiceDonation {
   private static let logger = Logger(subsystem: "com.queueplayer.lib", category: "SiriDonation")
 
-  /// Proxy for "Siri is wired up in this build" — the lib's config
-  /// plugin (`react-native-queue-player/app.plugin.js`) sets
-  /// `NSSiriUsageDescription` in Info.plist whenever the consumer
-  /// opts in with `{ siri: true }`. Reading the key from `Bundle.main`
-  /// avoids touching `INVocabulary.shared()`, which raises an
-  /// `NSException` (Swift cannot catch this) when the
-  /// `com.apple.developer.siri` entitlement is missing.
-  private static var siriWiredUp: Bool {
+  /// Whether the host app has declared Siri support: the lib's config plugin
+  /// (`react-native-queue-player/app.plugin.js`) sets `NSSiriUsageDescription`
+  /// in Info.plist when the consumer opts in with `{ siri: true }`.
+  ///
+  /// The second of two gates, and the weaker one. `PlayerConfig`'s
+  /// `voiceVocabularyDonationEnabled` is the first: it is the consumer
+  /// asserting the `com.apple.developer.siri` entitlement is on the target,
+  /// which is the requirement `INVocabulary` actually checks — it throws
+  /// `NSInternalInconsistencyException` without it, and Swift cannot catch
+  /// that. iOS exposes no API for a process to read its own entitlements, so
+  /// no gate here can verify the assertion. This one catches the narrower
+  /// misconfiguration of opting in without the usage description.
+  private static var hostDeclaresSiri: Bool {
     return Bundle.main.object(forInfoDictionaryKey: "NSSiriUsageDescription") != nil
   }
 
   static func donateVoiceVocabulary(_ vocabulary: VoiceVocabulary) {
-    guard siriWiredUp else {
+    guard hostDeclaresSiri else {
       logger.info("Skipping vocabulary donation — Siri not configured (Info.plist missing NSSiriUsageDescription)")
       return
     }

package/ios/StreamingBitrateProbe.swift

@@ -1,14 +1,13 @@
 import AudioToolbox
 import Foundation
 
-/// One-shot streaming-source bitrate probe via Core Audio's
+/// One-shot local-file bitrate probe via Core Audio's
 /// `AudioFileStream`.
 ///
-/// **Why this exists.** AVPlayer's `AVAssetTrack.estimatedDataRate`
-/// is unreliable for progressive streaming MP3 (returns 0 even
-/// after `.readyToPlay`); the access-log fallback chain
-/// (`event.averageAudioBitrate` / `event.indicatedBitrate`) is
-/// HLS-oriented and routinely returns NaN/-1 for non-HLS sources.
+/// **Why this exists.** `AVAssetTrack.estimatedDataRate` returns 0
+/// for some local sources, and `AudioFile`'s
+/// `kAudioFilePropertyBitRate` returns 0 for some transcoded MP3s
+/// (some server-transcoded MP3s exhibit this).
 /// Core Audio's `AudioFileStreamOpen` parses the bitstream from
 /// raw bytes and surfaces format/packet info as soon as the first
 /// frame headers land — same approach SwiftAudioPlayer,
@@ -33,8 +32,8 @@ import Foundation
 /// mFramesPerPacket)`. For 192 kbps CBR this converges within
 /// ~1% after ~100 packets — well under our probe window.
 ///
-/// **Cost.** One `URLSession` Range:`bytes=0-262143` (~256 KB)
-/// GET per distinct streaming URL. The 256 KB window tolerates
+/// **Cost.** One 256 KB `FileHandle` read per distinct local URL,
+/// and no network request at all. The 256 KB window tolerates
 /// large ID3v2 tags (sometimes 32 KB+ for embedded album art)
 /// without starving the parser of audio frames. Parse runs
 /// synchronously on a detached utility-priority Task. In-memory
@@ -54,24 +53,23 @@ enum StreamingBitrateProbe {
     return c
   }()
 
-  /// 256 KB Range: enough to skip past large ID3v2 tags + still
+  /// 256 KB prefix: enough to skip past large ID3v2 tags + still
   /// gather enough MP3 frames to compute a stable average.
   private static let probeByteCount = 262_144
 
-  /// Resolve the encoded bitrate (bits/sec) of the audio at
-  /// `url`. Handles both `http(s)://` (URLSession Range fetch)
-  /// and `file://` (FileHandle prefix read) URLs uniformly via
-  /// the same AudioFileStream-based parse — the local-file
-  /// fallback is necessary because Core Audio's `AudioFile`
-  /// API's `kAudioFilePropertyBitRate` returns 0 for some
-  /// transcoded MP3s (e.g. Subsonic-served MP3s the lookahead
-  /// cache has downloaded).
+  /// Resolve the encoded bitrate (bits/sec) of the audio at a
+  /// `file://` `url` by reading its prefix with `FileHandle` and
+  /// running an AudioFileStream parse over it. Necessary because
+  /// Core Audio's `AudioFile` API's `kAudioFilePropertyBitRate`
+  /// returns 0 for some transcoded MP3s (e.g. server-transcoded MP3s
+  /// the lookahead cache has downloaded). The format extractor uses it as
+  /// the third-tier fallback for `file://` sources whose codec has no
+  /// dedicated reader.
   ///
-  /// Returns nil when the URL scheme is unsupported, the server
-  /// doesn't honour Range, the response/file is empty, the
-  /// parser can't identify the format, or no packets were
-  /// parsed in the probe window.
-  static func bitrate(forUrl url: URL, urlSession: URLSession = .shared) async -> Double? {
+  /// Returns nil for a non-`file://` URL, an empty or unreadable
+  /// file, a format the parser can't identify, or a probe window
+  /// that yielded no packets. Results are cached per URL string.
+  static func bitrate(forUrl url: URL) async -> Double? {
     let key = url.absoluteString
     if let cached = readCache(key) {
       #if DEBUG
@@ -79,15 +77,8 @@ enum StreamingBitrateProbe {
       #endif
       return cached
     }
-    let bps: Double?
-    if url.isFileURL {
-      bps = await fetchAndParseLocal(url: url)
-    } else if let scheme = url.scheme?.lowercased(),
-              scheme == "http" || scheme == "https" {
-      bps = await fetchAndParseRemote(url: url, urlSession: urlSession)
-    } else {
-      bps = nil
-    }
+    guard url.isFileURL else { return nil }
+    let bps = await fetchAndParseLocal(url: url)
     if let bps = bps {
       writeCache(key, bps)
     }
@@ -120,43 +111,6 @@ enum StreamingBitrateProbe {
     }
   }
 
-  /// Trade-off: this issues a parallel HTTP request to the same
-  /// URL AVPlayer is streaming from. On servers with low per-IP
-  /// connection caps (some self-hosted Subsonic / Navidrome) a
-  /// concurrent Range fetch can briefly compete for a connection
-  /// slot. In practice the probe completes in <100 ms and the
-  /// cache returns immediately for repeat hits, so the impact is
-  /// bounded. Worth knowing if the player ever stalls right after
-  /// a track change against a server with strict connection
-  /// limits — try a dedicated `URLSession` with
-  /// `httpMaximumConnectionsPerHost = 1` if it bites.
-  private static func fetchAndParseRemote(
-    url: URL, urlSession: URLSession = .shared
-  ) async -> Double? {
-    var req = URLRequest(url: url, timeoutInterval: 10)
-    req.setValue("bytes=0-\(probeByteCount - 1)", forHTTPHeaderField: "Range")
-    let data: Data
-    do {
-      let (responseData, response) = try await urlSession.data(for: req)
-      if let http = response as? HTTPURLResponse,
-         !((200...299).contains(http.statusCode)) {
-        #if DEBUG
-        NSLog("[RNQP-BITRATE-PROBE] non-2xx status=%d url=%@",
-              http.statusCode, url.absoluteString)
-        #endif
-        return nil
-      }
-      data = responseData
-    } catch {
-      #if DEBUG
-      NSLog("[RNQP-BITRATE-PROBE] fetch-failed err=%@ url=%@",
-            String(describing: error), url.absoluteString)
-      #endif
-      return nil
-    }
-    return await runParse(data: data, url: url, source: "remote")
-  }
-
   /// Read the first `probeByteCount` bytes of a local file via
   /// FileHandle and run the same AudioFileStream parse.
   /// FileHandle is preferred over `Data(contentsOf:)` because

package/ios/SuppliedReplayGain.swift

@@ -0,0 +1,83 @@
+import AVFoundation
+
+/// The consumer's ReplayGain claim over one queue entry, resolved once
+/// at queue-build time and carried on the `AVPlayerItem` it was built
+/// for.
+///
+/// The claim and the values it survived with are two separate facts, and
+/// keeping them separate is the whole point of this type. A `TrackItem`
+/// that supplies only an out-of-band peak has claimed its track just as
+/// firmly as one that supplies all four values, so collapsing the claim
+/// into "did any value survive acceptance" would hand that track back to
+/// the file's own tags. Presence claims the track; validity only decides
+/// what there is to apply.
+///
+/// The instance therefore exists whenever any of the four fields was
+/// present, and `data` is `nil` when none of those values survived
+/// `ReplayGainExtractor`'s acceptance rules — a track that owns its
+/// ReplayGain and plays at unity.
+final class SuppliedReplayGain {
+  /// The supplied values that passed acceptance. `nil` means the
+  /// consumer claimed this track and gave nothing usable.
+  let data: ReplayGainData?
+
+  private init(data: ReplayGainData?) {
+    self.data = data
+  }
+
+  /// Build the claim for [track], or `nil` when the consumer supplied
+  /// none of the four ReplayGain fields and the track is left on
+  /// whatever its file carries.
+  ///
+  /// Each present value goes through the same `acceptGainDb` /
+  /// `acceptPeak` pair the tag strings land on, so a supplied number and
+  /// a tagged number are held to one rule.
+  static func from(track: TrackItem) -> SuppliedReplayGain? {
+    guard track.replayGainTrackGain != nil
+      || track.replayGainTrackPeak != nil
+      || track.replayGainAlbumGain != nil
+      || track.replayGainAlbumPeak != nil
+    else {
+      return nil
+    }
+    let trackGain = track.replayGainTrackGain.flatMap { ReplayGainExtractor.acceptGainDb($0) }
+    let trackPeak = track.replayGainTrackPeak.flatMap { ReplayGainExtractor.acceptPeak($0) }
+    let albumGain = track.replayGainAlbumGain.flatMap { ReplayGainExtractor.acceptGainDb($0) }
+    let albumPeak = track.replayGainAlbumPeak.flatMap { ReplayGainExtractor.acceptPeak($0) }
+    if trackGain == nil && trackPeak == nil
+       && albumGain == nil && albumPeak == nil {
+      return SuppliedReplayGain(data: nil)
+    }
+    return SuppliedReplayGain(
+      data: ReplayGainData(
+        trackGainDb: trackGain, trackPeak: trackPeak,
+        albumGainDb: albumGain, albumPeak: albumPeak
+      )
+    )
+  }
+}
+
+private var suppliedReplayGainKey: UInt8 = 0
+
+extension AVPlayerItem {
+  /// The consumer's ReplayGain claim over the `TrackItem` this item was
+  /// built from. Stamped by `AVQueueBuilder.makeItem` at construction
+  /// and carried across by the crossfade engine's item rebuilds, the
+  /// same way `queueItemId` and `sourceURL` are.
+  ///
+  /// Stamped rather than looked up: the queue-mutating surface is
+  /// `setQueue` / `addToQueue` / `removeFromQueue` / `moveInQueue` /
+  /// `clearQueue`, and every one of them rebuilds or moves items, so
+  /// there is no in-place metadata edit that could leave a stamped value
+  /// describing a different track than the one playing.
+  ///
+  /// `nil` means the consumer supplied nothing and the item's ReplayGain
+  /// comes from whatever `AssetReplayGainReader` finds in the file.
+  var suppliedReplayGain: SuppliedReplayGain? {
+    get { objc_getAssociatedObject(self, &suppliedReplayGainKey) as? SuppliedReplayGain }
+    set {
+      objc_setAssociatedObject(
+        self, &suppliedReplayGainKey, newValue, .OBJC_ASSOCIATION_RETAIN_NONATOMIC)
+    }
+  }
+}