react-native-queue-player 1.2.0 → 2.0.1

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()
+  }
+}

package/ios/TrackPlayer+EngineDelegate.swift

@@ -0,0 +1,209 @@
+import AVFoundation
+import Foundation
+
+// MARK: - PlaybackEngineDelegate
+
+/// `CrossfadeEngine` fires these callbacks; `GaplessEngine`'s
+/// equivalent surface continues to flow through `self.player`'s
+/// KVO chain installed by `installGaplessObservers` /
+/// `installEventObservers`. Each delegate method therefore runs
+/// only when the active engine is `CrossfadeEngine` (per the
+/// `delegate = self` wiring in `applyEngineSwapForMode`).
+extension TrackPlayer: PlaybackEngineDelegate {
+  func engineStateMaybeChanged(
+    _ engine: PlaybackEngine, reason: StateChangeReason?
+  ) {
+    if let reason {
+      // Engine-supplied classified reason takes precedence over
+      // any prior staked reason — match the gapless KVO path
+      // where pendingStateChangeReason is overwritten by the
+      // newer staked reason.
+      self.pendingStateChangeReason = reason
+    }
+    // The leading leg's `timeControlStatus` drives `.buffering` (load /
+    // rebuffer) and `reachedQueueEnd` drives `.ended`.
+    let computed = PlayerStateDerivation.translate(
+      status: engine.timeControlStatus,
+      currentIndex: self.currentTrackIndex,
+      hasCurrentItem: engine.currentMediaItem != nil,
+      reachedQueueEnd: self.reachedQueueEnd
+    )
+    emitState(computed, reason: reasonForComputedState(computed))
+  }
+
+  func engineDidTransitionTrack(_ engine: PlaybackEngine) {
+    // Bring TrackPlayer's currentTrackIndex into sync with the
+    // engine's index — CrossfadeEngine.completeCrossfade
+    // increments engine.currentMediaItemIndex; on setItems / seek
+    // the engine's index is already aligned with the caller's
+    // resumeIndex.
+    //
+    // Crossfade post-swap echo: fade-start already fired
+    // `engineCrossfadeDidBegin` which dispatched the JS-facing
+    // track-change for the same incoming index. The
+    // `lastEmittedQueueItemId` dedup inside `dispatchTrackChange`
+    // turns the second call into a no-op. Capability + lookahead
+    // refresh still run unconditionally — both are idempotent and
+    // the second pass picks up any state that landed during the
+    // fade window.
+    // Resolve the engine's active item to a queue position by identity.
+    // An engine's own index counts within whatever slice it was handed, so
+    // it is not a queue position; `queueItemId` is, and it survives the
+    // item-replacement paths (cross-attach, cached-URL upgrade).
+    //
+    // Still skipped during a queue mutation: the mutation already computed
+    // the authoritative `currentTrackIndex` via QueueMutationArithmetic, and
+    // the engine is mid-rebuild. (CrossfadeEngine.setItems fires this
+    // delegate synchronously; GaplessEngine does not.)
+    if !self.isMutatingPlayerQueue,
+       let resolved = self.matchTrackIndex(forCurrentItem: engine.currentMediaItem) {
+      self.currentTrackIndex = resolved
+    }
+    let reason = self.pendingTrackChangeReason ?? .autoAdvance
+    self.pendingTrackChangeReason = nil
+    dispatchTrackChange(reason: reason)
+    self.recomputeCapabilities()
+    self.rescheduleLookahead()
+    // Extend the installed run as the playhead advances into it. Driven from
+    // the transition rather than from arming, which would force the build into
+    // the moment immediately before the ramp is scheduled.
+    //
+    // Not while a mutation is in flight: this delegate is fired synchronously
+    // from `CrossfadeEngine.setItems`, so topping up there would re-enter
+    // `setItems` from inside itself — and the mutation that raised the flag
+    // installs the run it wants anyway.
+    if !self.isMutatingPlayerQueue {
+      self.topUpWindow()
+    }
+    // Refresh the now-playing format for the new active item. The crossfade
+    // engine's `\.tracks` KVO is `.new`-only and a forward skip rebuilds the
+    // incoming leg as a fresh AVPlayerItem whose tracks key isn't auto-loaded
+    // (only playable/duration are), so engineActiveItemFormatChanged may never
+    // fire for it — without this, getNowPlayingFormat() stays nil after a
+    // skip to a cached track. The extractor loads the format asynchronously
+    // and the lastEmittedFormatItemId dedup makes a redundant call a no-op.
+    self.refreshNowPlayingFormatForActiveItem()
+  }
+
+  func engineCrossfadeDidBegin(_ engine: PlaybackEngine) {
+    // Fade-start: the standby leg is now audibly playing (volume 0
+    // ramping up). Flip JS-facing active track + lock-screen / Now
+    // Playing surface to the incoming track immediately so the
+    // user sees the new track's title/artwork the moment they
+    // start hearing it. The leading leg continues fading out for
+    // the configured `crossfadeDurationMs`; engine accessors
+    // already prefer the standby leg while `fadeInFlight` is true.
+    //
+    // Reason is hardcoded `.autoAdvance` — fade-start is always an
+    // auto-advance event; any user-driven transition (skipToNext /
+    // skipToIndex / setMediaItems) would have called
+    // `cancelFadeInternal` first, so a stashed
+    // `pendingTrackChangeReason` here is stale and should not
+    // re-attribute the fade.
+    // A queue mutation already computed the authoritative index; the
+    // rebuild's own fade-cancel must not walk it back to the outgoing leg.
+    guard !self.isMutatingPlayerQueue,
+          let incoming = self.matchTrackIndex(forCurrentItem: engine.currentMediaItem)
+    else { return }
+    self.currentTrackIndex = incoming
+    self.pendingTrackChangeReason = nil
+    dispatchTrackChange(reason: .autoAdvance)
+    self.recomputeCapabilities()
+    self.rescheduleLookahead()
+  }
+
+  func engineCrossfadeDidCancel(_ engine: PlaybackEngine) {
+    // Fade-cancelled mid-flight (pause / stop / focus loss /
+    // queue mutation). JS already received `onTrackChange(incoming,
+    // reason: .autoAdvance)` from the prior fade-start fire; the
+    // incoming track is no longer the active one. Revert
+    // `currentTrackIndex` to the leading-leg index and emit
+    // `onTrackChange(leading, reason: .crossfadeCancelled)` so
+    // consumer UI can rewind to the leading track.
+    // See `engineCrossfadeDidBegin` — a rebuild issued by a queue mutation
+    // cancels the in-flight fade, and that cancel must not clobber the
+    // index the mutation just computed.
+    guard !self.isMutatingPlayerQueue,
+          let reverted = self.matchTrackIndex(forCurrentItem: engine.currentMediaItem)
+    else { return }
+    self.currentTrackIndex = reverted
+    self.pendingTrackChangeReason = nil
+    dispatchTrackChange(reason: .crossfadeCancelled)
+    self.recomputeCapabilities()
+    self.rescheduleLookahead()
+  }
+
+  /// Apply whatever was held back while the fade ran.
+  ///
+  /// Fired for every end of a fade, which is the point: a cancel taken during
+  /// the arm window reverts nothing and so reports nothing else, and work
+  /// waiting on that fade would otherwise wait for one that is already over —
+  /// with the engine still holding a run the queue has retired.
+  func engineFadeDidSettle(_ engine: PlaybackEngine) {
+    _ = engine
+    self.flushDeferredEngineWork()
+  }
+
+  func engineBufferStateMaybeChanged(_ engine: PlaybackEngine) {
+    _ = engine
+    // Buffer surface only — no direct player-state emission. The crossfade
+    // leading leg's buffer-flag KVO lands here; recompute the discrete
+    // buffer-state and fully-buffered surfaces, exactly as the gapless item KVO
+    // does through `installBufferObservers` (the stall-recovery restart inside
+    // `recomputeBufferState` still applies here, as on gapless). Already on
+    // `playerQueue` (the engine's ownerQueue), so recompute synchronously — a
+    // second async hop would reorder against the recompute's change dedup.
+    self.recomputeBufferState()
+    self.recomputeFullyBuffered()
+  }
+
+  func engineActiveItemFormatChanged(_ engine: PlaybackEngine) {
+    _ = engine
+    self.refreshNowPlayingFormatForActiveItem()
+    // Streaming-item audioMix catch-up for the crossfade engine
+    // (which fires this delegate hook on its own KVO chain). The
+    // gapless engine has a parallel catch-up path through
+    // `dispatchItemStatus(.readyToPlay)`; both call into
+    // `refreshActiveItemMixes`, which is idempotent on items that
+    // already carry a tap, so a double-fire is harmless.
+    AudioTapProvider.shared.refreshActiveItemMixes()
+  }
+
+  func engineDidFailWithError(
+    _ engine: PlaybackEngine, error: Error, item: AVPlayerItem?
+  ) {
+    _ = engine
+    let underlying = error as NSError
+    // The item is forwarded, not dropped: without it `dispatchErrorOrRetry`
+    // synthesises a key that cannot appear in `queueItemIds`, and the
+    // automatic-retry branch requires a real `queueItemId`.
+    dispatchErrorOrRetry(
+      item: item,
+      underlying: underlying,
+      nativeDomainOverride: nil
+    )
+  }
+
+  func engineDidPlayItemToEnd(_ engine: PlaybackEngine) {
+    // CrossfadeEngine fires this on natural end-of-leading; the
+    // boundary signal that drives JS-facing track-change is
+    // engineDidTransitionTrack which fires immediately after.
+    //
+    // Under repeat-one the same track replays with no track-change (the
+    // queueItemId is unchanged, so dispatchTrackChange's dedup skips its
+    // reset). Each loop is a fresh playthrough, so re-arm the milestone
+    // tracker here for that case only.
+    if self.repeatModeState == .track {
+      self.milestoneTracker.reset()
+    }
+    _ = engine
+  }
+
+  func enginePlaybackEnded(_ engine: PlaybackEngine) {
+    _ = engine
+    // The engine reports that it drained; what that means for the queue —
+    // wrap, refill, or over — is decided above it, the same way for both
+    // engines.
+    applyEndVerdict()
+  }
+}

package/ios/TrackPlayer+EventsAPI.swift

@@ -0,0 +1,111 @@
+import Foundation
+
+extension TrackPlayer {
+  // MARK: - Events — public registration surface
+  //
+  // Each event has a multi-listener `ListenerRegistry`. Each `onXxx`
+  // call appends a new entry; the returned closure removes that entry
+  // by stable id. ListenerRegistry's internal queue.sync makes
+  // add/remove safe against concurrent fire rounds — fire iterates a
+  // snapshot taken under the lock.
+
+  func onStateChange(
+    callback: @escaping (_ state: PlayerState, _ reason: StateChangeReason) -> Void
+  ) throws -> () -> Void {
+    let id = stateChangeListeners.add(callback)
+    return { [weak self] in self?.stateChangeListeners.remove(id: id) }
+  }
+
+  func onTrackChange(
+    callback: @escaping (_ track: TrackItem?, _ index: Double, _ reason: TrackChangeReason, _ transitionGapMs: Double?) -> Void
+  ) throws -> () -> Void {
+    let id = trackChangeListeners.add(callback)
+    return { [weak self] in self?.trackChangeListeners.remove(id: id) }
+  }
+
+  func onQueueChange(
+    callback: @escaping (_ delta: QueueChangeDelta, _ currentIndex: Double, _ reason: QueueChangeReason) -> Void
+  ) throws -> () -> Void {
+    let id = queueChangeListeners.add(callback)
+    return { [weak self] in self?.queueChangeListeners.remove(id: id) }
+  }
+
+  /// Emit a queue change as a description of what happened rather than a copy
+  /// of the queue. Callers pass only the fields their mutation defines; the
+  /// rest stay empty, and `revision` lets a subscriber notice a dropped event.
+  internal func emitQueueChange(
+    _ reason: QueueChangeReason,
+    inserted: [TrackItem] = [],
+    insertedAt: Int = -1,
+    removed: [Int] = [],
+    movedFrom: Int = -1,
+    movedTo: Int = -1,
+    order: [Int] = []
+  ) {
+    self.queueRevision += 1
+    let delta = QueueChangeDelta(
+      revision: Double(self.queueRevision),
+      length: Double(self.tracks.count),
+      inserted: inserted,
+      insertedAt: Double(insertedAt),
+      removed: removed.map(Double.init),
+      movedFrom: Double(movedFrom),
+      movedTo: Double(movedTo),
+      order: order.map(Double.init)
+    )
+    let index = Double(self.currentTrackIndex)
+    queueChangeListeners.forEach { $0(delta, index, reason) }
+  }
+
+  func onProgress(
+    callback: @escaping (_ progress: PlayerProgress) -> Void
+  ) throws -> () -> Void {
+    let id = progressListeners.add(callback)
+    return { [weak self] in self?.progressListeners.remove(id: id) }
+  }
+
+  func onPlaybackMilestone(
+    callback: @escaping (_ milestone: Double, _ trackIndex: Double) -> Void
+  ) throws -> () -> Void {
+    let id = milestoneListeners.add(callback)
+    return { [weak self] in self?.milestoneListeners.remove(id: id) }
+  }
+
+  func onError(callback: @escaping (_ error: PlaybackError) -> Void) throws -> () -> Void {
+    let id = errorListeners.add(callback)
+    return { [weak self] in self?.errorListeners.remove(id: id) }
+  }
+
+  func onQueueEnd(callback: @escaping () -> Void) throws -> () -> Void {
+    let id = queueEndListeners.add(callback)
+    return { [weak self] in self?.queueEndListeners.remove(id: id) }
+  }
+
+  /// Subscribe to skip-capability changes. Auto-fires the callback
+  /// once on registration with the current cached values (mirrors
+  /// Media3 `Player.Listener.onAvailableCommandsChanged`) so new
+  /// subscribers don't have to seed via the getters first. The
+  /// auto-fire hops to `playerQueue` so the cache read is on the
+  /// queue that writes it. Subsequent fires happen synchronously
+  /// from `recomputeCapabilities()`, also on `playerQueue`.
+  ///
+  /// **Dispose race guard:** the deferred fire checks the
+  /// subscriber is still registered (`contains(id:)`) before
+  /// invoking the callback. Strict-mode subscribe → dispose →
+  /// subscribe sequences fire the cleanup before the deferred fire
+  /// runs; without the guard, the auto-fire would call into an
+  /// already-unmounted React component's `setSnapshot`.
+  func onSkipCapabilityChange(
+    callback: @escaping (_ capability: SkipCapability) -> Void
+  ) throws -> () -> Void {
+    let id = skipCapabilityListeners.add(callback)
+    playerQueue.async { [weak self] in
+      guard let self else { return }
+      guard self.skipCapabilityListeners.contains(id: id) else { return }
+      callback(SkipCapability(
+        canSkipPrevious: self.cachedSkipCapability.canSkipPrevious,
+        canSkipNext: self.cachedSkipCapability.canSkipNext))
+    }
+    return { [weak self] in self?.skipCapabilityListeners.remove(id: id) }
+  }
+}