react-native-queue-player 1.1.2 → 2.0.0

package/ios/TrackPlayer+Automotive.swift

@@ -0,0 +1,101 @@
+import NitroModules
+
+extension TrackPlayer {
+  // MARK: - Automotive / voice handler registration
+
+  /// Atomically replace the cached `BrowseSnapshot` on the
+  /// process-wide [CarPlayCoordinator]. The data provider posts a
+  /// `didUpdateNotification` on the main queue; an active CarPlay
+  /// scene observes the notification + rebuilds the root template
+  /// against the new snapshot. Push semantics — most-recent call
+  /// wins. Safe to call before a CarPlay scene attaches: the
+  /// snapshot is cached on the coordinator + the next scene reads
+  /// it directly at didConnect.
+  func setBrowseSnapshot(snapshot: BrowseSnapshot) throws {
+    CarPlayCoordinator.shared.dataProvider.setSnapshot(snapshot)
+  }
+
+  func onBrowseRequest(
+    callback: @escaping (_ parentId: String) -> Promise<Promise<[BrowseItem]>>
+  ) throws -> () -> Void {
+    return CarPlayCoordinator.shared.bridge.registerOnBrowseRequest(callback)
+  }
+
+  // `onSearchRequest` is Android-only — CarPlay audio-entitled apps
+  // cannot legally present `CPSearchTemplate` (per the CarPlay App
+  // Programming Guide template-by-category rules); pushing or
+  // presenting it raises NSInvalidArgumentException at runtime. Apple
+  // Music + Spotify both dropped CarPlay search in iOS 26; the
+  // canonical CarPlay search affordance for audio apps is Siri via
+  // SiriKit's `INPlayMediaIntent`, not an in-app search template.
+  //
+  // `onPlayFromSearchRequest` IS wired on iOS — it serves the
+  // SiriKit `INPlayMediaIntent` path: Siri parses "Hey Siri play X
+  // on MyApp" into a structured `INMediaSearch`, the lib's
+  // `PlayMediaIntentHandler` maps it to `MediaSearchRequest`, and
+  // dispatches into this callback via `CarPlayBridge`.
+  //
+  // For `onSearchRequest` we accept the consumer's registration on
+  // iOS to keep the TS API shape cross-platform; the callback is
+  // discarded (`_ = callback` consumes the value), and the returned
+  // disposer is a no-op so the consumer's bookkeeping stays sane.
+  func onSearchRequest(
+    callback: @escaping (_ query: String) -> Promise<Promise<[BrowseItem]>>
+  ) throws -> () -> Void {
+    _ = callback
+    return {}
+  }
+
+  func onPlayFromSearchRequest(
+    callback: @escaping (_ request: MediaSearchRequest) -> Promise<Promise<[TrackItem]>>
+  ) throws -> () -> Void {
+    return CarPlayCoordinator.shared.bridge.registerOnPlayFromSearchRequest(callback)
+  }
+
+  func onPlayFromIdRequest(
+    callback: @escaping (_ mediaId: String) -> Promise<Promise<[TrackItem]>>
+  ) throws -> () -> Void {
+    return CarPlayCoordinator.shared.bridge.registerOnPlayFromIdRequest(callback)
+  }
+
+  // Donation Hybrid method — fire-and-forget into Siri's vocabulary
+  // donation pipeline. Real impl lives in `ios/Siri/VoiceDonation.swift`.
+  // Uses `INVocabulary.setVocabularyStrings(_:of:)` to seed Siri's NLU
+  // with the consumer's artist + playlist names.
+  func donateVoiceVocabulary(vocabulary: VoiceVocabulary) throws {
+    // Opt-in only. `INVocabulary` raises an uncatchable Objective-C exception
+    // in a process without the `com.apple.developer.siri` entitlement, and
+    // iOS gives a process no way to read its own entitlements — so the
+    // consumer declaring the capability is the only signal the library can
+    // have that this is safe to touch.
+    guard self.voiceVocabularyDonationEnabled else { return }
+    VoiceDonation.donateVoiceVocabulary(vocabulary)
+  }
+
+  func onCarConnect(callback: @escaping () -> Void) throws -> () -> Void {
+    return CarPlayCoordinator.shared.bridge.registerOnCarConnect(callback)
+  }
+
+  // `onServiceReady` is an Android-only signal. iOS apps die fully
+  // under memory pressure (no separate service lifecycle), so there's
+  // no `service-reborn` scenario to surface here. The lib accepts the
+  // registration to keep the cross-platform API shape consistent and
+  // returns a no-op disposer; the callback is consumed (so it isn't
+  // retained) and never invoked. Consumers writing for both platforms
+  // register one handler; on iOS only `onCarConnect` carries the
+  // equivalent "automotive surface available" signal.
+  func onServiceReady(
+    callback: @escaping (_ reason: ServiceReadyReason) -> Void
+  ) throws -> () -> Void {
+    _ = callback
+    return {}
+  }
+
+  func onCarDisconnect(callback: @escaping () -> Void) throws -> () -> Void {
+    return CarPlayCoordinator.shared.bridge.registerOnCarDisconnect(callback)
+  }
+
+  func isCarConnected() throws -> Bool {
+    return CarPlayCoordinator.shared.isCarConnected
+  }
+}

package/ios/TrackPlayer+Cache.swift

@@ -0,0 +1,232 @@
+import Foundation
+import NitroModules
+
+extension TrackPlayer {
+  // MARK: - Lookahead cache — runtime config + status surface
+  func setLookaheadCache(config: LookaheadCacheConfig) throws -> Promise<Void> {
+    return enqueueThrowing {
+      try self.applyLookaheadConfig(config)
+    }
+  }
+
+  func getLookaheadCacheStatus() throws -> Promise<CacheStatus> {
+    // The snapshot counts fully-cached entries, which is a filesystem check
+    // per entry — the Promise keeps that work off the calling JS thread.
+    return enqueueValue { self.buildCacheStatusSnapshot() }
+  }
+
+  func clearLookaheadCache() throws -> Promise<Void> {
+    return enqueue {
+      // Cancel any in-flight prefetch + drop everything on disk.
+      // We deliberately do NOT call rescheduleLookahead() here —
+      // an immediate refill makes `clearLookaheadCache` impossible
+      // to observe at zero from JS, and "clear" semantically means
+      // "wipe and stop" (the consumer can re-trigger prefetch by
+      // calling setLookaheadCache, skipToIndex, or setQueue again).
+      self.lookaheadCachePrefetcher?.cancel()
+      self.lookaheadCache?.clear()
+      self.emitCacheStatus()
+    }
+  }
+
+  func onCacheStatusChange(callback: @escaping (_ status: CacheStatus) -> Void) throws -> () -> Void {
+    // ListenerRegistry.add is internally serialized, so a JS consumer
+    // that does
+    //   const unsub = onCacheStatusChange(cb)
+    //   await setLookaheadCache(cfg)
+    // is guaranteed to see the post-config-change emit (the
+    // setLookaheadCache call synchronously crosses the bridge after
+    // the listener is in the registry).
+    let id = cacheStatusListeners.add(callback)
+    // Deliver the current status once. Otherwise a settings screen shows its
+    // placeholder until the next prefetch completes — which never happens for a
+    // fully-cached queue or a consumer running with prefetch off.
+    playerQueue.async { [weak self] in
+      guard let self else { return }
+      guard self.cacheStatusListeners.contains(id: id) else { return }
+      callback(self.buildCacheStatusSnapshot())
+    }
+    return { [weak self] in self?.cacheStatusListeners.remove(id: id) }
+  }
+
+  /// Apply a runtime config update. All three runtime dimensions are
+  /// live (no configure() needed):
+  /// - `enabled` toggle: build/teardown the prefetcher against the cache
+  /// - `lookaheadCount` change: live update on the prefetcher
+  /// - `allowsCellularAccess` toggle: live on the cache, applied per request
+  ///
+  /// Cache SIZE + eviction policy are NOT runtime dimensions — they are fixed
+  /// at `configure()` from `PlayerConfig` (kept consistent with Android, whose
+  /// SimpleCache is immutable after construction).
+  internal func applyLookaheadConfig(_ config: LookaheadCacheConfig) throws {
+    let previous = self.lookaheadConfig
+    self.lookaheadConfig = config
+
+    let enableChanged = config.enabled != previous.enabled
+    let countChanged = config.lookaheadCount != previous.lookaheadCount
+
+    if enableChanged {
+      rebuildCacheStack(config: config)
+    } else if config.enabled {
+      applyLiveConfigUpdates(config: config, countChanged: countChanged)
+    }
+
+    // The cache applies this per request, so it lands whether or not the
+    // branches above ran. When there is no cache yet the stored config is what
+    // the next construction reads.
+    lookaheadCache?.allowsCellularAccess = config.allowsCellularAccess ?? true
+
+    emitCacheStatus()
+  }
+
+  /// Configure-time cache disk budget in MB — `PlayerConfig.lookaheadCacheMaxSizeMb`
+  /// or the 100 MB default. Fixed at cache construction; reported read-only via
+  /// `getLookaheadCacheStatus().maxSizeMb`.
+  internal func configuredCacheMaxSizeMb() -> Double {
+    self.config.lookaheadCacheMaxSizeMb
+      ?? Double(LookaheadCache.DEFAULT_MAX_SIZE_BYTES) / Double(LookaheadCache.BYTES_PER_MB)
+  }
+
+  /// Configure-time cache eviction policy — `PlayerConfig.lookaheadCacheEvictionPolicy`
+  /// or `.lru`. Fixed at cache construction; a change at `configure()` clears the
+  /// cache and rebuilds under the new policy (see `configure`).
+  internal func configuredEvictionPolicy() -> EvictionPolicy {
+    self.config.lookaheadCacheEvictionPolicy ?? .lru
+  }
+
+  /// Bring up the server that reads through `cache`. Called from both sites
+  /// that build a cache — `configure()` and the runtime `setLookaheadCache`
+  /// — because a cache without a server is one nothing ever reads from. A
+  /// server already reading through this same cache instance is kept, its
+  /// headers refreshed: replacing it would change the port seated items
+  /// address. Blocks for the bind (milliseconds) so every item built after
+  /// this call routes; an item built before the bind is bound to its origin.
+  internal func startReadThroughServer(for cache: LookaheadCache) {
+    if let existing = readThroughServer, readThroughServerCache === cache {
+      existing.setHeaders(
+        AVQueueBuilder.mergedHeaders(
+          headers: self.config.httpHeaders, userAgent: self.config.userAgent))
+      return
+    }
+    readThroughServer?.stop()
+    let server = ReadThroughServer(
+      cachedFileForOrigin: { [weak cache] sourceURL in
+        cache?.cachedURL(forUrl: sourceURL)
+      },
+      onFirstDiskHit: { [weak cache] sourceURL in
+        cache?.touch(url: sourceURL)
+      }
+    )
+    server.setHeaders(
+      AVQueueBuilder.mergedHeaders(
+        headers: self.config.httpHeaders, userAgent: self.config.userAgent))
+    server.start()
+    if !server.waitUntilBound() {
+      NSLog("[QueuePlayer] read-through server did not bind; remote tracks play from their origin")
+    }
+    self.readThroughServer = server
+    self.readThroughServerCache = cache
+  }
+
+  /// Quiesce or re-arm the cache, prefetcher and read-through server
+  /// when the `enabled` flag flipped. Disable cancels in-flight prefetch
+  /// and quiesces the cache (URLSession STAYS alive — it is only invalidated
+  /// by full `destroy`); the server stays up too, serving seated items from
+  /// the origin while the cache answers nothing, and `routingServer` binds
+  /// new items to their origin. Enable rebuilds the prefetcher (or constructs
+  /// the pair from scratch on first enable), keeps the server and reschedules.
+  ///
+  /// Keeping the cache instance + URLSession alive across disable
+  /// avoids `Task created in a session that has been invalidated`
+  /// (Obj-C exception, uncatchable in Swift's `do-catch`) when a
+  /// prefetcher Task survived disable + tried to download against
+  /// a freshly-invalidated session before the dispatch barrier saw
+  /// the cancellation.
+  private func rebuildCacheStack(config: LookaheadCacheConfig) {
+    if !config.enabled {
+      lookaheadCachePrefetcher?.tearDown()
+      lookaheadCachePrefetcher = nil
+      lookaheadCache?.disable()
+      return
+    }
+    if lookaheadCache == nil {
+      // Size is fixed at construction from the configure-time budget.
+      lookaheadCache = LookaheadCache(
+        maxSizeBytes: LookaheadCache.maxBytes(forMb: configuredCacheMaxSizeMb()),
+        evictionPolicy: configuredEvictionPolicy(),
+        allowsCellularAccess: config.allowsCellularAccess ?? true
+      )
+    } else {
+      lookaheadCache?.enable()
+    }
+    guard let cache = lookaheadCache else { return }
+    // The cache is built here as well as at `configure()`, and a cache with no
+    // server is a cache nothing reads: every item would bind its origin and
+    // route past it. Whatever builds the cache brings the server with it.
+    startReadThroughServer(for: cache)
+    let prefetcher = LookaheadCachePrefetcher(
+      cache: cache,
+      confinedTo: self.playerQueue,
+      configHeaders: self.config.httpHeaders,
+      configUserAgent: self.config.userAgent
+    )
+    prefetcher.defaultLookaheadCount = InputGuards.validLookaheadCount(config.lookaheadCount)
+    prefetcher.onTrackProcessed = { [weak self] in self?.emitCacheStatus() }
+    lookaheadCachePrefetcher = prefetcher
+    rescheduleLookahead()
+  }
+
+  /// Apply in-place config updates when the cache stack already exists
+  /// (no enable-flag change). Only `lookaheadCount` reaches here — it updates
+  /// the prefetcher's default + reschedules. `allowsCellularAccess` is set on
+  /// the cache by the caller, and cache size is configure-time.
+  private func applyLiveConfigUpdates(
+    config: LookaheadCacheConfig, countChanged: Bool
+  ) {
+    if countChanged {
+      lookaheadCachePrefetcher?.defaultLookaheadCount =
+        InputGuards.validLookaheadCount(config.lookaheadCount)
+      rescheduleLookahead()
+    }
+  }
+
+  /// Build a [CacheStatus] snapshot from current cache + prefetcher
+  /// state. Synchronous — the caller is already on the queue that serialises
+  /// player state.
+  internal func buildCacheStatusSnapshot() -> CacheStatus {
+    // `currentlyDownloadingUrl` is prefetcher state confined to `playerQueue`,
+    // so it is read here and handed to the builder as a value.
+    return buildCacheStatusSnapshot(
+      inFlightUrl: lookaheadCachePrefetcher?.currentlyDownloadingUrl)
+  }
+
+  /// [CacheStatus] from cache + config state plus the caller-supplied
+  /// in-flight prefetch URL. Reads no prefetcher state of its own.
+  internal func buildCacheStatusSnapshot(inFlightUrl: String?) -> CacheStatus {
+    let cache = self.lookaheadCache
+    let currentBytes = cache?.currentSizeBytes() ?? 0
+    // Queue-agnostic: count fully-cached entries in the cache itself,
+    // not the intersection with `self.tracks`. Mirrors the semantics
+    // of `currentSizeBytes` (total cache disk usage) and the
+    // prefetcher's `currentlyDownloadingUrl` (active downloads) — all
+    // three reflect cache state independent of any current queue.
+    // Per-track local/stream/cache attribution for the active queue
+    // is exposed via `getCurrentTrackSource()`.
+    let fullyCached = cache?.fullyCachedCount() ?? 0
+    return CacheStatus(
+      enabled: lookaheadConfig.enabled,
+      currentSizeMb: Double(currentBytes) / Double(LookaheadCache.BYTES_PER_MB),
+      maxSizeMb: configuredCacheMaxSizeMb(),
+      tracksFullyCached: Double(fullyCached),
+      currentlyCaching: inFlightUrl.map { [$0] } ?? []
+    )
+  }
+
+  /// Fire the cache-status callback with a fresh snapshot. Caller
+  /// must already be on the queue that serialises player state.
+  internal func emitCacheStatus() {
+    guard !cacheStatusListeners.isEmpty else { return }
+    let snapshot = buildCacheStatusSnapshot()
+    cacheStatusListeners.forEach { $0(snapshot) }
+  }
+}

package/ios/TrackPlayer+Config.swift

@@ -0,0 +1,291 @@
+import Foundation
+import NitroModules
+
+extension TrackPlayer {
+  // MARK: - Playback configuration — some stubs, some lifecycle-adjacent
+
+  func setPlaybackMode(mode: PlaybackMode) throws -> Promise<Void> {
+    return enqueueThrowing {
+      let (newState, effect) = try self.playbackModeStateMachine.setRequested(
+        state: self.playbackModeState,
+        requested: mode
+      )
+      self.playbackModeState = newState
+      switch effect {
+      case .noOp:
+        break
+      case .immediateSwap:
+        self.applyEngineSwapForMode(newState.active)
+      }
+    }
+  }
+
+  func getPlaybackMode() throws -> PlaybackMode {
+    // Lock-guarded, so this answers without hopping. A `playerQueue.sync` here
+    // parks the JS thread behind whatever the queue is running, which can be a
+    // full queue rebuild.
+    return self.playbackModeState.active
+  }
+
+  /// Build a fresh engine of the requested kind and swap it in
+  /// place of the active engine. The new engine starts empty; the
+  /// canonical queue model is re-installed via the engine surface
+  /// so playback continues from the current track / position.
+  ///
+  /// JS-facing event sources differ per engine. GaplessEngine ties
+  /// `self.player` to the underlying `AVQueuePlayer` and the KVO
+  /// chain installed by `installGaplessObservers` /
+  /// `installEventObservers` carries onTrackChange / onStateChange
+  /// / onError. CrossfadeEngine sets `self.player` to nil and
+  /// fires `PlaybackEngineDelegate` callbacks that this class
+  /// implements (extension at the end of the file); the delegate
+  /// is wired below. Both engines surface progress through
+  /// `emitProgressIfSubscribed`, polymorphic over self.player vs
+  /// engine state.
+  internal func applyEngineSwapForMode(_ active: PlaybackMode) {
+    let oldEngine = self.engine
+    // Capture pre-swap state — the engine swap releases the old
+    // engine; reading `newEngine.currentPositionSeconds` /
+    // `isPlaying` after would always return 0 / false. The
+    // wasPlaying capture is what carries playback continuity
+    // across the immediate engine swap.
+    let resumePosition = oldEngine?.currentPositionSeconds ?? 0
+    let resumeIndex = self.currentTrackIndex
+    // The transport's intent, not the old engine's audible state: a leg that
+    // is buffering, or mid-crossfade with its outgoing item finished, reports
+    // not-playing while the consumer is very much still playing. Swapping on
+    // that reading silently pauses them.
+    let wasPlaying = self.wantsToPlay
+    // Anything held back from the old engine goes with it: the new one is
+    // installed from the queue model, which already carries every mutation.
+    self.engineReconcileDeferred = false
+
+    let newEngine: PlaybackEngine
+    switch active.kind {
+    case .gapless:
+      newEngine = GaplessEngine()
+    case .crossfade:
+      // PlaybackModeStateMachine.requireValid guarantees this is
+      // non-nil + within [1000, 12000] when `kind == .crossfade`.
+      // Fail loud rather than silently degrading to 0 (which would
+      // route through CrossfadeEngine's hard-cut path + skip
+      // engineCrossfadeDidBegin entirely).
+      guard let durationMs = active.crossfadeDurationMs else {
+        preconditionFailure("PlaybackMode(crossfade) missing crossfadeDurationMs at engine construction")
+      }
+      let durationSeconds = durationMs / 1000.0
+      newEngine = CrossfadeEngine(
+        crossfadeDurationSeconds: durationSeconds, confinedTo: self.playerQueue)
+    }
+
+    self.engine = newEngine
+    // GaplessEngine path: keep the established self.player KVO
+    // chain (currentItem / timeControlStatus / item.status) as
+    // the canonical event source. CrossfadeEngine path:
+    // self.player stays nil; the engine fires PlaybackEngineDelegate
+    // callbacks for track-change / state-change / format-ready /
+    // failed / play-to-end / queue-end and progress is sourced
+    // from the engine via a timer-driven fallback.
+    if let gapless = newEngine as? GaplessEngine {
+      self.player = gapless.player
+      self.gaplessFlipArmed = true
+      self.installGaplessObservers(on: gapless.player)
+      self.installEventObservers(on: gapless.player)
+      self.stopProgressFallbackTimer()
+      // Gapless does not need the engine delegate — the underlying
+      // self.player KVO chain is the canonical event source.
+      newEngine.delegate = nil
+    } else {
+      self.tearDownGaplessObservers()
+      self.tearDownEventObservers()
+      self.player = nil
+      newEngine.delegate = self
+      self.startProgressFallbackTimer()
+    }
+
+    // Re-wire the shared audio-tap provider to the new engine's
+    // audio-mix provider slot.
+    AudioTapProvider.shared.wireToPlaybackEngine(newEngine)
+
+    // Re-apply canonical config to the freshly-built engine BEFORE the
+    // queue install / play — it starts at engine defaults (repeat off,
+    // volume 1, speed 1), so without this a gapless↔crossfade swap
+    // silently drops the user's settings.
+    newEngine.setRepeatMode(self.repeatModeState)
+    newEngine.setVolume(self.volumeState)
+    // Carry the user's speed into the new engine. When resuming playback,
+    // apply it live via `setPlaybackSpeed` (sets `AVPlayer.rate`) BEFORE
+    // `setItems` — GaplessEngine.setItems captures the player's rate to
+    // restore it across the queue rebuild, so a speed applied after
+    // setItems/play() would be clobbered by that async restore. When
+    // paused, seed it only (no rate write, so the engine stays paused);
+    // play() applies it on the next resume.
+    if wasPlaying {
+      newEngine.setPlaybackSpeed(self.playbackSpeedState)
+    } else {
+      newEngine.seedPlaybackSpeed(self.playbackSpeedState)
+    }
+    newEngine.setPitchCorrectionMode(self.pitchCorrectionModeState)
+
+    // Re-install the queue on the new engine — the same window every other
+    // install uses, not the whole queue: a crossfade engine holds every item
+    // it is given, and a long queue would put every track's asset load
+    // through the read-through server at once. `topUpWindow` extends it.
+    if resumeIndex >= 0, resumeIndex < self.tracks.count {
+      let positions = QueueWindowArithmetic.slice(
+        currentIndex: resumeIndex,
+        trackCount: self.tracks.count,
+        trail: self.engineTrail,
+        wraps: false
+      )
+      let sliceIds = positions.map { self.queueItemIds[$0] }
+      let items = AVQueueBuilder.buildPlayerItems(
+        tracks: positions.map { self.tracks[$0] },
+        queueItemIds: sliceIds,
+        config: self.config,
+        server: self.routingServer
+      )
+      // Seated the way every other install is; with nothing playable at or
+      // after the current position the new engine stays empty rather than
+      // replaying the trail.
+      let currentId = self.queueItemIds[resumeIndex]
+      if let startIndex = Self.seatIndex(in: items, sliceIds: sliceIds, currentId: currentId) {
+        // The playhead carries across only onto the track that was playing;
+        // any other seat is a track change and starts at zero.
+        let position = items[startIndex].queueItemId == currentId ? resumePosition : 0
+        newEngine.setItems(
+          items,
+          startIndex: startIndex,
+          startPositionSeconds: position
+        )
+        // Honour pre-swap playing state so a mid-play setPlaybackMode keeps
+        // playing on the new engine — through `beginPlayback`, which every
+        // path that starts playback goes through, and not while the session
+        // is interrupted.
+        if wasPlaying, !self.isInterrupted {
+          self.beginPlayback()
+        }
+      }
+    }
+
+    // Whatever was seated above, the engine being replaced goes: its items
+    // stop loading and its observers come down.
+    oldEngine?.release()
+  }
+
+  func setPlaybackSpeed(rate: Double) throws -> Promise<Void> {
+    return enqueue {
+      // Clamp to a 0.25 floor: rate=0 on AVPlayer is functionally equivalent
+      // to pause(), which would surprise consumers calling
+      // `setPlaybackSpeed(0)` for a slow-down effect. Cross-platform contract
+      // documented in TrackPlayer.nitro.ts. A value that is not a number
+      // leaves the current rate alone.
+      guard !rate.isNaN else { return }
+      let safeRate = Float(max(0.25, min(rate, 32)))
+      self.playbackSpeedState = safeRate
+      // Apply to the LIVE rate only when the user wants playback (already
+      // playing, OR buffering toward play). On a paused/idle engine writing
+      // `AVPlayer.rate` starts it (rate > 0 == "play"), so with no play intent
+      // seed the speed instead (no rate write); `play()` applies it on the next
+      // resume. This keeps a persisted speed applied at app start — before a
+      // restored `setQueue` — from auto-starting a paused queue. `wantsToPlay`
+      // (not just `isPlaying`) covers the buffering-toward-play window so a
+      // speed change there still applies live.
+      if self.wantsToPlay || self.engine?.isPlaying == true {
+        self.engine?.setPlaybackSpeed(safeRate)
+      } else {
+        self.engine?.seedPlaybackSpeed(safeRate)
+      }
+    }
+  }
+  func setPitchCorrectionMode(mode: PitchCorrectionMode) throws -> Promise<Void> {
+    return enqueue {
+      self.pitchCorrectionModeState = mode
+      self.engine?.setPitchCorrectionMode(mode)
+    }
+  }
+  func getPitchCorrectionMode() throws -> PitchCorrectionMode {
+    // Lock-guarded — see `getPlaybackMode`.
+    return self.pitchCorrectionModeState
+  }
+  func setVolume(volume: Double) throws -> Promise<Void> {
+    return enqueue {
+      // Clamped to the documented range before either branch, so the cast and
+      // local paths cannot diverge on the same input, and a value that is not
+      // a number cannot poison the stored level that `getVolume` and the
+      // sleep-timer fade read back.
+      guard !volume.isNaN else { return }
+      let level = Float(max(0, min(1, volume)))
+      if CastTransportRouter.routeSetVolume(value: Double(level)) { return }
+      self.volumeState = level
+      self.engine?.setVolume(level)
+    }
+  }
+
+  func setRepeatMode(mode: RepeatMode) throws -> Promise<Void> {
+    return enqueue {
+      self.repeatModeState = mode
+      // Forward to the active engine. The CrossfadeEngine needs the
+      // mode to suppress its look-ahead fade + loop the current item
+      // under `.track` (AVPlayer has no native repeat); GaplessEngine
+      // treats it as a no-op (repeat-track replay lives in
+      // handlePlayerItemDidPlayToEndTime).
+      self.engine?.setRepeatMode(mode)
+      // Both canSkipNext and canSkipPrevious depend on repeat mode
+      // (e.g. at idx 0 / last index, OFF↔QUEUE flips the boolean
+      // because QUEUE wraps). Recompute is cheap; dedup keeps the
+      // listener silent when the (prev, next) tuple is unchanged.
+      // The installed run is forward-only, so a repeat-mode change does not
+      // alter which positions it holds and there is nothing to reconcile. That
+      // stops being true the moment the run carries the wrap target, and the
+      // reconcile has to come back with it.
+      self.recomputeCapabilities()
+    }
+  }
+
+  func setRemoteControls(options: RemoteControlOptions) throws -> Promise<Void> {
+    return enqueue {
+      // Guard nonsensical negatives (a negative forward interval would seek
+      // backward) and values too large to convert to milliseconds. Out-of-range
+      // is clamped rather than rejected.
+      let fwd = InputGuards.sanitisedSeekPosition(options.forwardJumpInterval)
+        .map { max(0, $0) } ?? 0
+      let back = InputGuards.sanitisedSeekPosition(options.backwardJumpInterval)
+        .map { max(0, $0) } ?? 0
+      self.remoteSkipMode = options.skipMode
+      self.remoteForwardInterval = fwd
+      self.remoteBackwardInterval = back
+      self.remoteCommands.setRemoteControls(
+        mode: options.skipMode,
+        forwardInterval: fwd,
+        backwardInterval: back)
+      // Re-apply the cached grey-out: switching to track mode re-enables
+      // next/prev, which must reflect the queue-boundary capability
+      // (setSkipCapability is otherwise only called on queue/repeat change,
+      // and no-ops in interval mode).
+      self.remoteCommands.setSkipCapability(
+        canSkipNext: self.cachedSkipCapability.canSkipNext,
+        canSkipPrevious: self.cachedSkipCapability.canSkipPrevious)
+    }
+  }
+
+  // ReplayGain mode — thin wrapper around `AudioTapProvider.shared`.
+  // The provider owns the per-item state set + recompute walk; this
+  // Hybrid surface is the JS-facing setter / getter only.
+  func setReplayGainMode(mode: ReplayGainMode) throws -> Promise<Void> {
+    return enqueue {
+      AudioTapProvider.shared.setReplayGainMode(mode)
+      // Re-emit the active item's NowPlayingFormat so
+      // `onNowPlayingFormatChange` subscribers (e.g. the
+      // `useNowPlayingFormat` hook) observe the new `replayGainActive`
+      // flag without waiting for the next track change. Mirrors the
+      // Android path's `refreshNowPlayingFormatForActiveItem` call from
+      // its own `setReplayGainMode`.
+      guard let item = self.activeMediaItem else { return }
+      self.emitCurrentNowPlayingFormat(for: item)
+    }
+  }
+  func getReplayGainMode() throws -> ReplayGainMode {
+    return AudioTapProvider.shared.getReplayGainMode()
+  }
+}