react-native-queue-player 1.0.0

package/ios/NowPlayingFormatExtractor.swift

@@ -0,0 +1,362 @@
+import AVFoundation
+import AudioToolbox
+import CoreMedia
+import NitroModules
+
+/// Resolves the active item's runtime audio format from AVFoundation. Pure
+/// function — no shared state. Caller owns invocation cadence + emit dedup.
+///
+/// Codec maps from the audio track's `CMAudioFormatDescription` ASBD; container
+/// maps from the asset URL's path extension (HLS detected as `.m3u8`). Bitrate
+/// is read from `AVAssetTrack.estimatedDataRate` (bits/sec) when AVFoundation
+/// reports a non-zero value; for MP3 assets the value is unreliable at
+/// `.readyToPlay` so a codec-gated fallback chain takes over: Core Audio's MP3
+/// frame parser (`kAudioFilePropertyBitRate`) for `file://` and AVPlayerItem
+/// access-log telemetry for `http(s)://`. Each field falls back to its `null`
+/// sentinel when no signal is available.
+enum NowPlayingFormatExtractor {
+
+  /// Extract the format snapshot for `item`. Returns `nil` only when the asset
+  /// has no audio track at all; otherwise every field is best-effort with
+  /// per-field null fallback. May suspend while AVAsset properties load.
+  ///
+  /// Track pick: prefers the player's currently-enabled
+  /// AVPlayerItemTrack (matches what's actually decoding for HLS
+  /// multi-rendition assets) and falls back to the asset's first
+  /// audio AVAssetTrack when no enabled item-track is found.
+  static func extract(item: AVPlayerItem) async -> NowPlayingFormat? {
+    // `AVPlayerItem.asset` is a MainActor-isolated property under
+    // strict concurrency. Hop to main for the read; the remainder of
+    // this function works against the captured asset reference.
+    let asset: AVAsset = await MainActor.run { item.asset }
+    let tracks: [AVAssetTrack]
+    do {
+      tracks = try await asset.load(.tracks)
+    } catch {
+      return nil
+    }
+    let audioTrack = pickAudioAssetTrack(item: item, assetTracks: tracks)
+    guard let audioTrack = audioTrack else { return nil }
+
+    var formatDescriptions: [CMFormatDescription] = []
+    var estimatedDataRate: Float = 0
+    var descriptionsFailed = false
+    var rateFailed = false
+    do {
+      formatDescriptions = try await audioTrack.load(.formatDescriptions)
+    } catch {
+      descriptionsFailed = true
+    }
+    do {
+      estimatedDataRate = try await audioTrack.load(.estimatedDataRate)
+    } catch {
+      rateFailed = true
+    }
+    // If BOTH loads failed there's no signal worth emitting — return
+    // nil so the consumer can distinguish "extractor ran but couldn't
+    // read" from "asset has no audio track" cleanly. A single-load
+    // failure still produces a partial snapshot via per-field null.
+    if descriptionsFailed && rateFailed { return nil }
+
+    var codec: AudioCodec = .unknown
+    var sampleRate: Double? = nil
+    var channelCount: Double? = nil
+    var bitsPerChannel: Double? = nil
+
+    if let desc = formatDescriptions.first,
+       let asbdPtr = CMAudioFormatDescriptionGetStreamBasicDescription(desc) {
+      let asbd = asbdPtr.pointee
+      codec = mapCodec(formatID: asbd.mFormatID)
+      if asbd.mSampleRate > 0 { sampleRate = asbd.mSampleRate }
+      if asbd.mChannelsPerFrame > 0 { channelCount = Double(asbd.mChannelsPerFrame) }
+      if asbd.mBitsPerChannel > 0 { bitsPerChannel = Double(asbd.mBitsPerChannel) }
+    }
+
+    let url = (asset as? AVURLAsset)?.url
+    let container = mapContainer(url: url)
+    let mimeType = mapMimeType(codec: codec)
+    var bitrate: Double? = estimatedDataRate > 0 ? Double(estimatedDataRate) : nil
+    // Fallback chain when AVFoundation didn't surface a bitrate:
+    //
+    // 1. Local MP3 file://: Core Audio's frame parser
+    //    (`kAudioFilePropertyBitRate`) — reliable for CBR, average
+    //    for VBR-with-Xing. MP3-specific because the local-file
+    //    AudioFile API needs the format hint up-front.
+    // 2. Streaming http(s):// of any codec: `StreamingBitrateProbe`
+    //    issues a Range:0-65535 fetch and parses via Core Audio's
+    //    `AudioFileStream` (codec-agnostic). Apple does not expose
+    //    a reliable bitrate field for progressive streams via
+    //    AVFoundation; the probe fills the gap.
+    // 3. HLS or any other streaming source the probe couldn't
+    //    parse: `event.averageAudioBitrate` / `event.indicatedBitrate`
+    //    from the AVPlayer access log — surfaces a real value for
+    //    HLS variants whose playlist declares BANDWIDTH.
+    if bitrate == nil, let url = url {
+      if url.isFileURL {
+        // Local file: try Core Audio's `AudioFile`-based reader
+        // first when the codec is MP3 (cheapest path: no parse,
+        // single property read). Falls back to the
+        // `AudioFileStream` packet-derived probe for codecs
+        // without a dedicated reader OR when AudioFile returned
+        // 0 (some transcoded MP3s — the lookahead cache's
+        // Subsonic-served files exhibit this).
+        if codec == .mp3 {
+          bitrate = await readLocalMP3Bitrate(url: url)
+        }
+        if bitrate == nil, codec == .flac {
+          bitrate = await readLocalFLACBitrate(url: url)
+        }
+        if bitrate == nil {
+          bitrate = await StreamingBitrateProbe.bitrate(forUrl: url)
+        }
+      } else if let scheme = url.scheme?.lowercased(),
+                scheme == "http" || scheme == "https" {
+        bitrate = await StreamingBitrateProbe.bitrate(forUrl: url)
+        if bitrate == nil, codec == .mp3 {
+          bitrate = readStreamingMP3Bitrate(item: item)
+        }
+      }
+    }
+
+    // Read duration from the asset, not the AVPlayerItem. AVPlayerItem
+    // mirrors `asset.duration` but the mirror is racy: a freshly-built
+    // item against a `file://` AVURLAsset can briefly report
+    // `kCMTimeIndefinite` even after `automaticallyLoadedAssetKeys`
+    // resolves on the asset. The asset is the canonical source — and
+    // because the AVPlayerItem here was constructed with `"duration"`
+    // in `automaticallyLoadedAssetKeys`, the value is already loaded;
+    // this `load(.duration)` call is a property read, not a fetch.
+    let assetDuration: CMTime
+    do {
+      assetDuration = try await asset.load(.duration)
+    } catch {
+      assetDuration = .indefinite
+    }
+    let durationSec: Double? = {
+      guard assetDuration.isValid, !assetDuration.isIndefinite else { return nil }
+      let secs = assetDuration.seconds
+      return secs.isFinite ? secs : nil
+    }()
+
+    // ReplayGain fields read from `AudioTapProvider`'s per-item
+    // cache. The provider's `audioMix(for:)` path kicks off async
+    // metadata extraction at item construction; by the time the JS
+    // side asks for `getNowPlayingFormat()` the data is typically
+    // already cached. Items that haven't seen the tap path
+    // (`AudioMixProvider` not wired, HLS bypass, track-less item)
+    // surface all fields as null + `replayGainActive = false`.
+    let rgData = AudioTapProvider.shared.replayGainDataForItem(item)
+    let rgActive = AudioTapProvider.shared.replayGainActiveForItem(item)
+
+    return NowPlayingFormat(
+      codec: codec,
+      container: container,
+      mimeType: mimeType.map { .second($0) } ?? .first(.null),
+      sampleRate: sampleRate.map { .second($0) } ?? .first(.null),
+      channelCount: channelCount.map { .second($0) } ?? .first(.null),
+      bitrate: bitrate.map { .second($0) } ?? .first(.null),
+      durationSec: durationSec.map { .second($0) } ?? .first(.null),
+      replayGainTrackDb: rgData?.trackGainDb.map { .second($0) } ?? .first(.null),
+      replayGainTrackPeak: rgData?.trackPeak.map { .second($0) } ?? .first(.null),
+      replayGainAlbumDb: rgData?.albumGainDb.map { .second($0) } ?? .first(.null),
+      replayGainAlbumPeak: rgData?.albumPeak.map { .second($0) } ?? .first(.null),
+      replayGainActive: rgActive,
+      ios: NowPlayingFormatIosExtras(
+        bitsPerChannel: bitsPerChannel.map { .second($0) } ?? .first(.null)
+      ),
+      android: nil
+    )
+  }
+
+  /// Pick the AVAssetTrack the player is actually decoding. Iterates
+  /// the AVPlayerItem's `tracks` (each wraps an AVAssetTrack with an
+  /// `isEnabled` flag) and prefers the first enabled audio track.
+  /// Falls back to the asset's first audio AVAssetTrack when nothing
+  /// is enabled (e.g. a fresh item before the player has selected
+  /// renditions on an HLS playlist).
+  static func pickAudioAssetTrack(
+    item: AVPlayerItem, assetTracks: [AVAssetTrack]
+  ) -> AVAssetTrack? {
+    for itemTrack in item.tracks where itemTrack.isEnabled {
+      if let assetTrack = itemTrack.assetTrack, assetTrack.mediaType == .audio {
+        return assetTrack
+      }
+    }
+    return assetTracks.first(where: { $0.mediaType == .audio })
+  }
+
+  static func mapCodec(formatID: AudioFormatID) -> AudioCodec {
+    switch formatID {
+    case kAudioFormatMPEG4AAC,
+         kAudioFormatMPEG4AAC_HE,
+         kAudioFormatMPEG4AAC_HE_V2,
+         kAudioFormatMPEG4AAC_LD,
+         kAudioFormatMPEG4AAC_ELD,
+         kAudioFormatMPEG4AAC_ELD_V2,
+         kAudioFormatMPEG4AAC_ELD_SBR,
+         kAudioFormatMPEG4AAC_Spatial:
+      return .aac
+    case kAudioFormatMPEGLayer3:
+      return .mp3
+    case kAudioFormatFLAC:
+      return .flac
+    case kAudioFormatAppleLossless:
+      return .alac
+    case kAudioFormatOpus:
+      return .opus
+    case kAudioFormatLinearPCM:
+      return .pcm
+    default:
+      return .unknown
+    }
+  }
+
+  static func mapContainer(url: URL?) -> AudioContainer {
+    guard let url = url else { return .unknown }
+    let ext = url.pathExtension.lowercased()
+    switch ext {
+    case "mp3": return .mp3
+    case "m4a", "m4b", "m4r", "mp4": return .mp4
+    case "flac": return .flac
+    case "ogg", "opus": return .ogg
+    case "wav", "wave": return .wav
+    case "aac": return .aacAdts
+    case "m3u8": return .hls
+    default: return .unknown
+    }
+  }
+
+  static func mapMimeType(codec: AudioCodec) -> String? {
+    switch codec {
+    case .aac: return "audio/mp4a-latm"
+    case .mp3: return "audio/mpeg"
+    case .flac: return "audio/flac"
+    case .alac: return "audio/alac"
+    case .opus: return "audio/opus"
+    case .pcm: return "audio/L16"
+    case .unknown: return nil
+    }
+  }
+
+  /// Read the average bitrate of a local MP3 by parsing frame headers
+  /// via Core Audio's `kAudioFilePropertyBitRate`. Synchronous file I/O
+  /// — typically sub-millisecond on a CBR file, scales with VBR XING/LAME
+  /// header presence. Wrapped in a detached utility-priority Task so the
+  /// extractor's async caller doesn't block the main actor on cold-cache
+  /// disk reads.
+  ///
+  /// Internally double-checks the file is actually MP3 by reading the
+  /// resolved `kAudioFilePropertyDataFormat` ASBD's format ID after open.
+  /// The `kAudioFileMP3Type` argument to `AudioFileOpenURL` is a
+  /// non-restrictive hint — Core Audio's content sniffing can succeed-
+  /// open files that aren't MP3 (e.g. an .m4a/AAC fixture). The
+  /// `mFormatID == kAudioFormatMPEGLayer3` ASBD check is the actual
+  /// safety net that ensures we only return a bitrate read from MP3
+  /// frames. Returns `nil` on open failure, format mismatch, property-
+  /// read failure, or a zero/negative reported value.
+  static func readLocalMP3Bitrate(url: URL) async -> Double? {
+    return await Task.detached(priority: .utility) { () -> Double? in
+      var fileID: AudioFileID?
+      let openStatus = AudioFileOpenURL(
+        url as CFURL, .readPermission, kAudioFileMP3Type, &fileID
+      )
+      guard openStatus == noErr, let fileID = fileID else { return nil }
+      defer { AudioFileClose(fileID) }
+
+      var asbd = AudioStreamBasicDescription()
+      var asbdSize = UInt32(MemoryLayout<AudioStreamBasicDescription>.size)
+      let formatStatus = AudioFileGetProperty(
+        fileID, kAudioFilePropertyDataFormat, &asbdSize, &asbd
+      )
+      guard formatStatus == noErr,
+            asbd.mFormatID == kAudioFormatMPEGLayer3 else { return nil }
+
+      var bitRate: UInt32 = 0
+      var size = UInt32(MemoryLayout<UInt32>.size)
+      let propStatus = AudioFileGetProperty(
+        fileID, kAudioFilePropertyBitRate, &size, &bitRate
+      )
+      guard propStatus == noErr, bitRate > 0 else { return nil }
+      return Double(bitRate)
+    }.value
+  }
+
+  /// Read the average bitrate of a local FLAC by parsing STREAMINFO
+  /// (`totalSamples`, `sampleRate`) and dividing the file's byte
+  /// size by the resulting duration. AudioFileStream's packet-derived
+  /// probe (`StreamingBitrateProbe`) doesn't yield a bitrate for FLAC
+  /// because the FLAC parser there doesn't model variable-frame
+  /// containers — STREAMINFO is the cheaper, more reliable path.
+  ///
+  /// `(file_size_bytes - metadata_overhead) * 8 / duration_seconds` is
+  /// the textbook formula; metadata overhead is tiny (~kilobytes) for
+  /// typical music FLACs in the tens-of-megabytes range, so we use
+  /// the full file size and accept a sub-1% high read on average. The
+  /// alternative (subtracting the position of the first audio frame
+  /// from the file size) requires walking every metadata block to
+  /// find the audio offset, more code for negligible accuracy gain.
+  ///
+  /// Returns nil when STREAMINFO can't be parsed or the file size /
+  /// duration math doesn't produce a finite positive value.
+  static func readLocalFLACBitrate(url: URL) async -> Double? {
+    return await Task.detached(priority: .utility) { () -> Double? in
+      // STREAMINFO sits in the first ~50 bytes after `fLaC`. A small
+      // prefix read is plenty.
+      let header: Data
+      do {
+        let handle = try FileHandle(forReadingFrom: url)
+        defer { try? handle.close() }
+        header = handle.readData(ofLength: 256)
+      } catch {
+        return nil
+      }
+      guard let info = MetadataReader.parseFLACStreamInfo(header) else {
+        return nil
+      }
+      guard info.sampleRate > 0, info.totalSamples > 0 else { return nil }
+      // `attributesOfItem` is preferred over `URLResourceKey` for
+      // file:// URLs that have a path — sub-millisecond stat call.
+      let attrs: [FileAttributeKey: Any]
+      do {
+        attrs = try FileManager.default.attributesOfItem(atPath: url.path)
+      } catch {
+        return nil
+      }
+      guard let size = (attrs[.size] as? NSNumber)?.int64Value else {
+        return nil
+      }
+      let durationSec = Double(info.totalSamples) / Double(info.sampleRate)
+      guard durationSec > 0 else { return nil }
+      let bitsPerSecond = Double(size) * 8.0 / durationSec
+      return bitsPerSecond.isFinite && bitsPerSecond > 0 ? bitsPerSecond : nil
+    }.value
+  }
+
+  /// Read the active streaming bitrate from the AVPlayerItem's access
+  /// log. Prefers `event.averageAudioBitrate` (audio stream's declared
+  /// average), then `event.indicatedBitrate` (HLS playlist's BANDWIDTH
+  /// for the active variant). Returns `nil` when no access-log event
+  /// has landed yet or neither declared field is populated.
+  ///
+  /// Why declared-only: `event.observedBitrate` and the
+  /// `numberOfBytesTransferred / transferDuration` derivation both
+  /// measure NETWORK throughput — bytes/sec on the wire — not the
+  /// encoded media bitrate. A 192 kbps progressive MP3 buffered in
+  /// 0.3s over a fast LAN reports observedBitrate ≈ 50 Mbps, which
+  /// would surface to consumers as "MP3 · 50000 kbps" — wrong by two
+  /// orders of magnitude. Returning nil so the caller renders "?
+  /// kbps" is the honest answer when the server didn't declare.
+  ///
+  /// Threading: invoked from the `extract(item:)` async pipeline (off
+  /// main); `AVPlayerItem.accessLog()` returns a snapshot and is
+  /// safe to call from any thread, matching the off-main usage in
+  /// `TrackPlayer.swift`'s DEBUG access-log timeline logger.
+  static func readStreamingMP3Bitrate(item: AVPlayerItem) -> Double? {
+    guard let event = item.accessLog()?.events.last else { return nil }
+    let avgAudio: Double = event.averageAudioBitrate
+    if avgAudio.isFinite, avgAudio > 0 { return avgAudio }
+    let indicated: Double = event.indicatedBitrate
+    if indicated.isFinite, indicated > 0 { return indicated }
+    return nil
+  }
+}

package/ios/NowPlayingInfo.swift

@@ -0,0 +1,190 @@
+import Foundation
+import MediaPlayer
+
+/// Owns the process-wide `MPNowPlayingInfoCenter.default().nowPlayingInfo`
+/// dictionary that drives the iOS lock-screen, control-center, CarPlay,
+/// AirPlay, and Apple Watch surfaces.
+///
+/// Emits on:
+/// - track change (full refresh — title/artist/album/duration/artwork +
+///   position + rate).
+/// - state change (position + rate only).
+/// - seek completion (position + rate only).
+/// - 10s periodic tick (position + rate only — bounds extrapolation drift).
+///
+/// The system interpolates the scrubber between emits using
+/// `MPNowPlayingInfoPropertyElapsedPlaybackTime` +
+/// `MPNowPlayingInfoPropertyPlaybackRate`. The periodic tick keeps that
+/// interpolation honest across long-running playback, rate changes, and
+/// background-thread suspensions.
+///
+/// Threading: every public method MUST be called from the main thread.
+/// Callers in `TrackPlayer` either run inside `onMain {}` or are invoked
+/// from KVO bodies that have already async-hopped to main.
+final class NowPlayingInfo {
+
+  /// Snapshot of player state at emit time. The provider closure is
+  /// responsible for reading every field within the same main-thread
+  /// tick — divergent values (elapsed taken at t0, rate at t0+Δ) show
+  /// up on the lock-screen scrubber as jitter.
+  struct Snapshot {
+    let track: TrackItem?
+    /// Current playback position in seconds. NaN / ±Inf coerce to 0.
+    let elapsedSeconds: Double
+    /// Total duration in seconds. NaN / ±Inf / ≤0 → omit (signals
+    /// live-stream / unknown to the system).
+    let durationSeconds: Double
+    /// `AVPlayer.rate`. 0 paused, 1 playing at speed, etc.
+    let rate: Float
+  }
+
+  /// Provider read on every emit. Owner sets it during `configure()`
+  /// and clears it during `destroy()`.
+  var snapshotProvider: (() -> Snapshot)?
+
+  private var periodicTimer: Timer?
+  private var cachedPlaceholderArtwork: MPMediaItemArtwork?
+  /// Subscription to the global cast active-session router. When a
+  /// remote session is active, `CastNowPlayingController` owns the
+  /// lockscreen surface and this writer becomes a no-op — every
+  /// public method short-circuits without mutating
+  /// `MPNowPlayingInfoCenter`. Re-engaged on session deactivate.
+  private var castActive: Bool = false
+  private var castRouterDisposer: (() -> Void)?
+
+  init() {
+    castRouterDisposer = PlaybackStateRouter.shared.addActiveChangeListener {
+      [weak self] session in
+      self?.castActive = (session != nil)
+    }
+  }
+
+  deinit {
+    castRouterDisposer?()
+  }
+
+  /// Full refresh — metadata + position + rate. Call on track-change.
+  /// A nil snapshot or a snapshot with `track == nil` (queue empty /
+  /// pre-first-track) clears the dictionary so the lock-screen /
+  /// control-center surface goes away.
+  func refreshAll() {
+    if castActive { return }
+    guard let snapshot = snapshotProvider?(), snapshot.track != nil else {
+      MPNowPlayingInfoCenter.default().nowPlayingInfo = nil
+      return
+    }
+    var info: [String: Any] = [:]
+    applyMetadata(snapshot.track, into: &info)
+    if snapshot.durationSeconds.isFinite && snapshot.durationSeconds > 0 {
+      info[MPMediaItemPropertyPlaybackDuration] = snapshot.durationSeconds
+    }
+    info[MPNowPlayingInfoPropertyMediaType] =
+      MPNowPlayingInfoMediaType.audio.rawValue
+    info[MPMediaItemPropertyArtwork] = placeholderArtwork()
+    applyPositionAndRate(snapshot, into: &info)
+    MPNowPlayingInfoCenter.default().nowPlayingInfo = info
+  }
+
+  /// Replace the artwork in the current dictionary with the resolver-
+  /// supplied image. No-op when the dictionary is nil (track ended,
+  /// queue cleared, destroyed) — refuses to resurrect the surface from
+  /// an artwork-only payload.
+  ///
+  /// `boundsSize: image.size` and `requestHandler` returning the
+  /// image unchanged matches the canonical SwiftAudioEx /
+  /// react-native-track-player pattern (and Substreamer's real-car
+  /// behaviour). The system handles size negotiation; over-engineering
+  /// the handler (forced 1024² canvas + aspect-fit render) was tested
+  /// and found to make no difference on the standalone CarPlay
+  /// Simulator's main-art region.
+  func applyArtwork(_ image: UIImage) {
+    if castActive { return }
+    guard var info = MPNowPlayingInfoCenter.default().nowPlayingInfo else { return }
+    info[MPMediaItemPropertyArtwork] = MPMediaItemArtwork(boundsSize: image.size) { _ in image }
+    MPNowPlayingInfoCenter.default().nowPlayingInfo = info
+  }
+
+  /// Position + rate only. Leaves track metadata + artwork untouched.
+  /// Call on state-change, seek-completion, periodic tick. No-op when
+  /// there's no current track (queue empty) or when the dictionary
+  /// hasn't been populated yet — refusing to resurrect the surface
+  /// from a partial position-only payload.
+  ///
+  /// Also re-publishes [MPMediaItemPropertyPlaybackDuration] when the
+  /// snapshot has a finite duration. The initial [refreshAll] on track
+  /// change runs before the AVURLAsset has loaded its duration, so the
+  /// progress bar / scrub UI on the lock screen + CarPlay Now Playing
+  /// surface stays absent until this method's late re-publish lands
+  /// (typically ~100-500ms after play starts, via the state-change
+  /// dispatch in [TrackPlayer]).
+  func refreshPositionAndRate() {
+    if castActive { return }
+    guard let snapshot = snapshotProvider?(), snapshot.track != nil else { return }
+    guard var info = MPNowPlayingInfoCenter.default().nowPlayingInfo else { return }
+    applyPositionAndRate(snapshot, into: &info)
+    if snapshot.durationSeconds.isFinite && snapshot.durationSeconds > 0 {
+      info[MPMediaItemPropertyPlaybackDuration] = snapshot.durationSeconds
+    }
+    MPNowPlayingInfoCenter.default().nowPlayingInfo = info
+  }
+
+  /// Stops the periodic timer and clears the dictionary. Call on
+  /// `destroy()` before the audio session deactivates.
+  func clear() {
+    stopPeriodicTimer()
+    MPNowPlayingInfoCenter.default().nowPlayingInfo = nil
+  }
+
+  /// Schedule the 10s periodic refresh on the main run loop. Idempotent.
+  /// `tolerance = 1.0` lets the OS coalesce with other timers without
+  /// affecting scrubber accuracy (the system extrapolates from elapsed
+  /// + rate between emits). The closure short-circuits when the player
+  /// is paused — elapsed is unchanged and rate is already 0, so the
+  /// write would be pure noise.
+  func startPeriodicTimer() {
+    stopPeriodicTimer()
+    let timer = Timer(timeInterval: 10, repeats: true) { [weak self] _ in
+      guard let self,
+            let snapshot = self.snapshotProvider?(),
+            snapshot.rate != 0 else { return }
+      self.refreshPositionAndRate()
+    }
+    timer.tolerance = 1.0
+    RunLoop.main.add(timer, forMode: .common)
+    periodicTimer = timer
+  }
+
+  func stopPeriodicTimer() {
+    periodicTimer?.invalidate()
+    periodicTimer = nil
+  }
+
+  /// Empty-string-coerce title / artist / album. CarPlay drops the
+  /// rendered surface when an expected String property is missing —
+  /// always set the keys, even when the consumer-supplied TrackItem
+  /// has nothing populated.
+  private func applyMetadata(_ track: TrackItem?, into info: inout [String: Any]) {
+    info[MPMediaItemPropertyTitle] = track?.title ?? ""
+    info[MPMediaItemPropertyArtist] = track?.artist ?? ""
+    info[MPMediaItemPropertyAlbumTitle] = track?.album ?? ""
+  }
+
+  private func applyPositionAndRate(_ snapshot: Snapshot, into info: inout [String: Any]) {
+    let elapsed = snapshot.elapsedSeconds.isFinite ? max(0, snapshot.elapsedSeconds) : 0
+    let rate = snapshot.rate.isFinite ? Double(snapshot.rate) : 0
+    info[MPNowPlayingInfoPropertyElapsedPlaybackTime] = elapsed
+    info[MPNowPlayingInfoPropertyPlaybackRate] = rate
+  }
+
+  /// Lazy MPMediaItemArtwork wrapper around the bundled placeholder
+  /// UIImage. Built once per process; the closure that the system
+  /// invokes for size requests just returns the same image (the system
+  /// handles its own scaling).
+  private func placeholderArtwork() -> MPMediaItemArtwork {
+    if let cached = cachedPlaceholderArtwork { return cached }
+    let image = PlaceholderArtwork.image
+    let mp = MPMediaItemArtwork(boundsSize: image.size) { _ in image }
+    cachedPlaceholderArtwork = mp
+    return mp
+  }
+}

package/ios/OutputRouteMonitor.swift

@@ -0,0 +1,125 @@
+import AVFoundation
+import Foundation
+
+/// Classifies the active `AVAudioSession` route and notifies its
+/// delegate when the route flips from "mixable" to "non-mixable".
+///
+/// "Non-mixable" routes are the ones that cannot reliably mix two
+/// simultaneously-playing `AVPlayer` instances (per Apple Developer
+/// Forum 105877 + 653606): AirPlay 2 and CarPlay. Bluetooth A2DP,
+/// AirPlay 1, headphones, built-in speaker, USB-DAC, HDMI all
+/// mix locally before the system's single-stream encode and are
+/// safe to drive with two players.
+///
+/// Used by `CrossfadeEngine` to cancel any in-flight equal-power
+/// fade the moment the user routes to a non-mixable destination
+/// (otherwise iOS arbitrarily silences one of the two players,
+/// producing a perceptible mid-fade audio jump). Per-boundary
+/// fade-vs-hard-cut decisions read [isCurrentRouteMixable]
+/// directly at track-boundary fire so the engine can degrade
+/// per-transition instead of swapping engines on every route
+/// change.
+///
+/// Threading: subscribes to `AVAudioSession.routeChangeNotification`
+/// on the main run loop. Re-evaluates one runloop tick after each
+/// notification because `currentRoute.outputs` lags the
+/// notification by one runloop turn on iOS.
+final class OutputRouteMonitor {
+
+  /// Route categories the monitor exposes to consumers.
+  enum OutputClass {
+    /// Local routes (built-in speaker / headphones / Bluetooth
+    /// A2DP / HDMI / USB-DAC / etc.) and AirPlay 1. The OS
+    /// mixes two simultaneously-playing players locally before
+    /// encoding the single output stream — dual-AVPlayer
+    /// crossfade is safe.
+    case localMixable
+    /// AirPlay 2 + CarPlay. iOS forces single-stream routing
+    /// once these engage and arbitrarily silences one of two
+    /// concurrently-playing players. Engines must degrade to
+    /// single-player playback for the duration.
+    case nonMixableRemote
+  }
+
+  /// Latest classification. Read at engine track-boundary fire
+  /// so per-transition fade-vs-cut decisions reflect the current
+  /// route without depending on a callback delivery deadline.
+  private(set) var currentClass: OutputClass = .localMixable
+
+  /// Convenience accessor — `true` outside AirPlay 2 / CarPlay.
+  var isCurrentRouteMixable: Bool {
+    currentClass == .localMixable
+  }
+
+  /// Fired the moment the route flips into [OutputClass.nonMixableRemote]
+  /// while a fade may be in flight. Engine wires this to its
+  /// `cancelFade()` path. NOT fired when the route flips back to
+  /// mixable — the next track-boundary picks up the new state
+  /// via `isCurrentRouteMixable`.
+  var onRouteBecameNonMixable: (() -> Void)?
+
+  private var observer: NSObjectProtocol?
+
+  /// Begin observing route changes. Idempotent — repeat calls
+  /// drop the prior observer first. Synthetically seeds
+  /// [currentClass] one runloop turn after registration so
+  /// `currentRoute.outputs` is fully populated when
+  /// [evaluate] reads it.
+  func start() {
+    stop()
+    let center = NotificationCenter.default
+    observer = center.addObserver(
+      forName: AVAudioSession.routeChangeNotification,
+      object: AVAudioSession.sharedInstance(),
+      queue: .main
+    ) { [weak self] _ in
+      // Defer one runloop turn — `AVAudioSession.currentRoute.outputs`
+      // can lag the notification by one turn, especially when
+      // AirPlay engagement crosses the system's policy boundary.
+      DispatchQueue.main.async { [weak self] in
+        self?.evaluate()
+      }
+    }
+    DispatchQueue.main.async { [weak self] in
+      self?.evaluate()
+    }
+  }
+
+  /// Stop observing. Safe to call when not started.
+  func stop() {
+    if let observer {
+      NotificationCenter.default.removeObserver(observer)
+    }
+    observer = nil
+  }
+
+  deinit {
+    if let observer {
+      NotificationCenter.default.removeObserver(observer)
+    }
+  }
+
+  /// Re-classify [currentClass] from the live route and fire the
+  /// non-mixable callback if the classification flipped to
+  /// non-mixable. Public for testing — production callers go
+  /// through [start].
+  func evaluate() {
+    let outputs = AVAudioSession.sharedInstance().currentRoute.outputs
+    let isNonMixable = outputs.contains { Self.isNonMixableOutput($0) }
+    let newClass: OutputClass = isNonMixable ? .nonMixableRemote : .localMixable
+    let flipped = newClass == .nonMixableRemote && currentClass == .localMixable
+    currentClass = newClass
+    if flipped {
+      onRouteBecameNonMixable?()
+    }
+  }
+
+  /// Pure classifier — exposed `static` so unit tests can drive
+  /// it with synthetic `AVAudioSessionPortDescription` arrays
+  /// without standing up a real audio session.
+  static func isNonMixableOutput(_ output: AVAudioSessionPortDescription) -> Bool {
+    let portType = output.portType
+    return portType == .airPlay
+      || portType == .carAudio
+  }
+}