react-native-queue-player 1.0.0

package/android/src/main/java/com/margelo/nitro/queueplayer/PlaybackEngine.kt

@@ -0,0 +1,336 @@
+package com.margelo.nitro.queueplayer
+
+import androidx.media3.common.MediaItem
+import androidx.media3.common.PlaybackException
+import androidx.media3.common.util.UnstableApi
+import androidx.media3.exoplayer.ExoPlayer
+import androidx.media3.exoplayer.audio.TeeAudioProcessor
+
+/**
+ * Strategy abstraction over the audio output pipeline.
+ *
+ * Two concrete implementations:
+ *  - [GaplessEngine]: single ExoPlayer, native gapless via item chaining.
+ *  - [CrossfadeEngine]: dual ExoPlayer with equal-power gain ramping at
+ *    track boundaries.
+ *
+ * The engine owns the player instance(s), audio-thread effects, and
+ * track-boundary scheduling. The lib's [TrackPlayer] holds the canonical
+ * queue model + listener registries + system-side surfaces (NowPlaying,
+ * RemoteCommands, AudioSession) and routes transport / queue calls
+ * through whichever engine is active. Engine swap (gapless ↔ crossfade)
+ * is a `handoff` at the next track boundary.
+ *
+ * Threading: all methods are called on the service main looper unless
+ * noted. `suspend` methods are launched on the same dispatcher; the
+ * impl is responsible for any internal off-loop work (e.g. heavy
+ * lookahead-cache prefetch).
+ */
+interface PlaybackEngine {
+
+  /**
+   * Build the underlying player(s), apply [mediaItems] starting at
+   * [startIndex] / [startPositionMs], and wait for the underlying
+   * player(s) to reach a playable state.
+   *
+   * Empty [mediaItems] is allowed; the engine prepares an empty
+   * timeline and [currentMediaItemIndex] returns `-1` until items
+   * arrive via [setMediaItems] / [addMediaItems].
+   */
+  suspend fun prepare(
+    mediaItems: List<MediaItem>,
+    startIndex: Int,
+    startPositionMs: Long,
+  )
+
+  /**
+   * Release the underlying player(s) and stop all background work.
+   * After [release], no further methods are valid.
+   */
+  fun release()
+
+  // Queue mutation -- engine layer; TrackPlayer mirrors these against
+  // its canonical queue model. All of these run synchronously on the
+  // service main looper.
+
+  /**
+   * Replace the current queue with [items]. Empty list is allowed.
+   * Playback resumes at [startIndex] / [startPositionMs] when items
+   * are non-empty.
+   */
+  fun setMediaItems(items: List<MediaItem>, startIndex: Int, startPositionMs: Long)
+
+  /**
+   * Insert [items] before the existing item at [insertBefore]. An
+   * `insertBefore` equal to the current queue length appends.
+   */
+  fun addMediaItems(items: List<MediaItem>, insertBefore: Int)
+
+  /**
+   * Remove items at [indices]. Indices may be in any order; the impl
+   * sorts and removes from highest to lowest so positions before each
+   * removal stay stable.
+   */
+  fun removeMediaItems(indices: IntArray)
+
+  fun moveMediaItem(fromIndex: Int, toIndex: Int)
+
+  // Transport — synchronous on the service main looper.
+  fun play()
+  fun pause()
+  fun stop()
+  fun seekTo(index: Int, positionMs: Long)
+  fun skipToNext()
+  fun skipToPrevious()
+
+  // Config
+  fun setVolume(volume: Float)
+  fun setPlaybackSpeed(speed: Float)
+  fun setRepeatMode(mode: RepeatMode)
+  // Sets how pitch behaves when speed != 1.0 (none/voice/music). Drives
+  // the PlaybackParameters pitch field; non-local engines (AirPlay) no-op
+  // because the receiver owns rendering.
+  fun setPitchCorrectionMode(mode: PitchCorrectionMode)
+  // @C.WakeMode — applied to EVERY underlying player the engine owns
+  // (both crossfade legs), not just the audible one, so the standby /
+  // post-swap leg doesn't leak a network wake lock on an all-local queue.
+  fun setWakeMode(mode: Int)
+
+  // State
+
+  /**
+   * Current item index within the engine's queue. Returns `-1` when
+   * the queue is empty (matches the canonical sentinel in
+   * [TrackPlayer]). When non-empty, mirrors `Player.currentMediaItemIndex`.
+   */
+  val currentMediaItemIndex: Int
+  val currentPositionMs: Long
+  val currentDurationMs: Long
+  val bufferedPositionMs: Long
+  val isPlaying: Boolean
+  val currentMediaItem: MediaItem?
+
+  /**
+   * Snapshot of every queued [MediaItem]. Called rarely (engine swap,
+   * diagnostic dumps); impl may allocate. The canonical queue model
+   * lives on [TrackPlayer]; engines do not duplicate it for hot-path
+   * reads.
+   */
+  val allMediaItems: List<MediaItem>
+
+  /**
+   * Underlying ExoPlayer instance the service-level wiring
+   * (audio-focus listener, `MediaSession.setPlayer`) attaches
+   * to. `GaplessEngine` returns its single player; `CrossfadeEngine`
+   * returns the leading leg's player.
+   *
+   * Mid-fade role swap inside `CrossfadeEngine` flips which
+   * underlying player this getter returns, but the
+   * `MediaSession` currently bound by `PlaybackService.swapEngine`
+   * does NOT auto-rebind — `MediaSession.setPlayer` is invoked
+   * once per engine swap, not per fade midpoint. The
+   * `CrossfadeForwardingPlayer` wrapper exists to bridge that
+   * gap (re-target the bound delegate via `setPlayer` on every
+   * role swap); wiring lands when [PlaybackService] starts
+   * binding through the wrapper for crossfade engines.
+   */
+  val mediaSessionPlayer: ExoPlayer
+
+  /**
+   * Active audio session IDs.
+   *
+   * Gapless: 1 entry. Crossfade during the fade window: 2 entries
+   * (outgoing + incoming). Empty when the player is yet to allocate
+   * its first AudioTrack (`C.AUDIO_SESSION_ID_UNSET`).
+   */
+  fun currentAudioSessionIds(): IntArray
+
+  /**
+   * Subscribe to changes in [currentAudioSessionIds]. Listener fires
+   * on the service main looper. Returns a disposer.
+   */
+  fun addAudioSessionIdListener(listener: (IntArray) -> Unit): () -> Unit
+
+  /**
+   * Inject a [TeeAudioProcessor.AudioBufferSink] into the renderer
+   * chain. Used by the visualizer pipeline to receive raw PCM via
+   * `TeeAudioProcessor`.
+   *
+   * Multiple [attachAudioBufferSink] calls accumulate; each registered
+   * sink receives every PCM buffer until detached. Implementations
+   * fan out to ALL active players (1 for gapless, 2 during crossfade)
+   * so effects observe both streams during transition.
+   */
+  @UnstableApi
+  fun attachAudioBufferSink(sink: TeeAudioProcessor.AudioBufferSink)
+
+  @UnstableApi
+  fun detachAudioBufferSink(sink: TeeAudioProcessor.AudioBufferSink)
+
+  /**
+   * Snapshot the active item's cached [ReplayGainData], or `null`
+   * when no usable RG tags have been parsed yet. Surfaced by
+   * [NowPlayingFormatExtractor] to populate the four
+   * `replayGain*Db` / `replayGain*Peak` fields. Default returns
+   * `null` so engines without RG wiring (future stub variants)
+   * compile without a no-op override.
+   */
+  fun currentReplayGainData(): ReplayGainData? = null
+
+  /**
+   * `true` when the active item's cached [ReplayGainData] carries
+   * a tag for the current [ReplayGainConfig.getMode]. Surfaced by
+   * [NowPlayingFormatExtractor] as the `replayGainActive` flag.
+   * Default returns `false` so engines without RG wiring compile
+   * without a no-op override.
+   */
+  fun currentReplayGainActive(): Boolean = false
+
+  /**
+   * Hand playback off to [nextEngine] when the user changes
+   * `PlaybackMode`.
+   *
+   * Contract:
+   *  - The receiver inherits the donor's queue, current index, and
+   *    current position; the caller does NOT pre-call [prepare] on
+   *    [nextEngine].
+   *  - When [atTrackBoundary] is `true`, the donor plays the active
+   *    track to its natural end and the receiver starts playing the
+   *    NEXT queue position fresh.
+   *  - When [atTrackBoundary] is `false` (idle player or empty
+   *    queue), the swap is immediate; receiver picks up at the
+   *    inherited position.
+   *  - The donor's [release] is the caller's responsibility AFTER
+   *    the boundary fires; the engine itself does not self-release.
+   *  - The donor's listeners on [delegate] continue firing until
+   *    [release] runs; the caller swaps the delegate before that.
+   */
+  suspend fun handoff(to: PlaybackEngine, atTrackBoundary: Boolean)
+
+  /**
+   * Single delegate receiving state / track / progress / error /
+   * queue-end events. TrackPlayer is the canonical delegate; engines
+   * fire on the service main looper.
+   *
+   * Strong reference by design; the iOS counterpart uses a weak
+   * reference because the AVQueuePlayer-driven engine sits inside
+   * the same actor as TrackPlayer and Swift's reference graph would
+   * otherwise close (TrackPlayer → engine → delegate → TrackPlayer).
+   * On Android the engine lives inside [PlaybackService.serviceBinder]
+   * which is owned by the service lifecycle, not by TrackPlayer; the
+   * cycle is broken explicitly by [release] dropping `delegate` and
+   * by [TrackPlayer.tearDownEventObservers] dropping the binder.
+   *
+   * Threading: setter MUST be invoked on the service main looper to
+   * avoid a write-vs-fire race during [handoff].
+   */
+  var delegate: PlaybackEngineDelegate?
+}
+
+/**
+ * Engine → TrackPlayer event channel.
+ *
+ * Delivers raw Media3-flavored signals; the delegate (typically
+ * [TrackPlayer]) consults the canonical queue model + lib-internal
+ * pending-reason flags to compute the JS-facing event shape. The
+ * iOS counterpart fires structurally similar callbacks with
+ * AVFoundation-flavored parameters in `PlaybackEngine.swift`.
+ */
+interface PlaybackEngineDelegate {
+
+  /**
+   * Fires when the player's effective state may have changed
+   * (`playbackState` / `playWhenReady` / `isPlaying` transitioned).
+   * The delegate consults [engine] state, the canonical queue model,
+   * and lib-internal pending-reason flags to compute the emitted
+   * `PlayerState`.
+   *
+   * [playWhenReadyReason] carries Media3's
+   * `Player.PLAY_WHEN_READY_CHANGE_REASON_*` when the underlying
+   * signal was `onPlayWhenReadyChanged`, so the delegate can stamp
+   * a typed `StateChangeReason` (audio-focus loss, end-of-media,
+   * etc.) before [PlayerState] dedup runs. `null` when the signal
+   * came from `onPlaybackStateChanged` or `onIsPlayingChanged` —
+   * those paths don't carry a reason and the delegate should
+   * preserve any previously-stamped pending reason.
+   */
+  fun onStateMaybeChanged(engine: PlaybackEngine, playWhenReadyReason: Int? = null)
+
+  /**
+   * Fires on Media3 `Player.Listener.onIsPlayingChanged` with the
+   * post-change `isPlaying` value. Drives the DEBUG gapless-gap
+   * timing log on the playing-leg transition; production builds
+   * may treat this as a no-op (the same state is already reflected
+   * via [onStateMaybeChanged]).
+   */
+  fun onIsPlayingChanged(engine: PlaybackEngine, isPlaying: Boolean)
+
+  /**
+   * Fires on Media3 `Player.Listener.onMediaItemTransition`.
+   * [platformReason] is one of `Player.MEDIA_ITEM_TRANSITION_REASON_*`.
+   * The delegate translates against its own state machine
+   * (e.g. consuming a pending user-skip reason).
+   */
+  fun onTrackTransition(engine: PlaybackEngine, platformReason: Int)
+
+  /**
+   * Fires when the active item's audio tracks become populated and
+   * format details (codec / sample rate / channel count / bitrate)
+   * become available. Drives [TrackPlayer.refreshNowPlayingFormatForActiveItem].
+   * iOS counterpart fires on `AVPlayerItem.tracks` KVO.
+   */
+  fun onActiveItemFormatChanged(engine: PlaybackEngine)
+
+  /**
+   * Fires on Media3 `Player.Listener.onPlayerError`. The delegate
+   * maps [exception] via the lib's `PlaybackErrorMapping`.
+   */
+  fun onError(engine: PlaybackEngine, exception: PlaybackException)
+
+  /**
+   * Fires on Media3 `Player.STATE_ENDED`. The delegate consults the
+   * canonical queue model + repeat mode to decide whether this is
+   * queue-end (fires `queueEndListeners`) or a per-track end that
+   * should be ignored.
+   */
+  fun onPlaybackEnded(engine: PlaybackEngine)
+
+  /**
+   * Fires on Media3 `Player.Listener.onPositionDiscontinuity` with
+   * reason `DISCONTINUITY_REASON_AUTO_TRANSITION`. Lib-internal
+   * diagnostics only — drives gapless-gap timing logs in DEBUG
+   * builds.
+   */
+  fun onAutoTransitionDiscontinuity(engine: PlaybackEngine)
+
+  /**
+   * Fires when a crossfade begins ramping — i.e. the standby
+   * [ExoPlayer] has started playback at volume 0 and the leading
+   * leg's fade-out has begun. The delegate treats this as the
+   * canonical "active track changed" trigger and emits
+   * `onTrackChange` + repoints `MediaSessionCompat` to the
+   * incoming track. The subsequent `onTrackTransition` for the
+   * same incoming index is a structural Media3 echo and must be
+   * deduplicated.
+   *
+   * Crossfade-only — [GaplessEngine] never invokes this.
+   * [incomingIndex] is the global queue index of the fading-in
+   * track.
+   */
+  fun onCrossfadeBegin(engine: PlaybackEngine, incomingIndex: Int)
+
+  /**
+   * Fires when an in-flight crossfade is cancelled before
+   * `swapRoles` runs (pause / stop / audio-focus loss / queue
+   * mutation that invalidates the standby leg). The delegate
+   * reverts JS-facing state to the leading leg — emit
+   * `onTrackChange(reason: CROSSFADE_CANCELLED)` for the leading
+   * track + repoint `MediaSessionCompat` back. Pairs with
+   * [onCrossfadeBegin]: only fires when a `Begin` was fired
+   * earlier and the fade did not complete.
+   *
+   * Crossfade-only. [revertedIndex] is the leading-leg index
+   * that is now the active track.
+   */
+  fun onCrossfadeCancel(engine: PlaybackEngine, revertedIndex: Int)
+}

package/android/src/main/java/com/margelo/nitro/queueplayer/PlaybackErrorMapping.kt

@@ -0,0 +1,175 @@
+package com.margelo.nitro.queueplayer
+
+import androidx.annotation.VisibleForTesting
+import androidx.media3.common.PlaybackException
+import androidx.media3.common.util.UnstableApi
+
+/**
+ * Android-side mapping from raw Media3 [PlaybackException.errorCode]
+ * into the lib-standardized [PlaybackErrorCode] vocabulary. Pure
+ * `object`; no `TrackPlayer` instance state.
+ *
+ * Mirrors `PlaybackErrorMapping.swift` on the iOS side. Both
+ * implementations consult the standardized code (not the raw native
+ * code) to drive the transient/fatal classifier so the
+ * retry-eligibility contract is platform-agnostic.
+ */
+@UnstableApi
+internal object PlaybackErrorMapping {
+
+  /**
+   * Classify a Media3 [PlaybackException] into the lib-standardized
+   * code. Visible to JUnit unit tests.
+   */
+  @VisibleForTesting
+  fun classify(error: PlaybackException): PlaybackErrorCode = when (error.errorCode) {
+    PlaybackException.ERROR_CODE_IO_NETWORK_CONNECTION_TIMEOUT ->
+      PlaybackErrorCode.TIMEOUT
+    PlaybackException.ERROR_CODE_IO_NETWORK_CONNECTION_FAILED ->
+      // Media3 1.10's catch-all for non-timeout network failures
+      // (DNS, host unreachable, no internet). Later Media3 versions
+      // split ERROR_CODE_IO_DNS_FAILED out separately; using the
+      // 1.10-stable code keeps the build portable.
+      PlaybackErrorCode.NETWORK_UNREACHABLE
+    PlaybackException.ERROR_CODE_IO_READ_POSITION_OUT_OF_RANGE,
+    PlaybackException.ERROR_CODE_IO_UNSPECIFIED ->
+      PlaybackErrorCode.CONNECTION_LOST
+    PlaybackException.ERROR_CODE_IO_BAD_HTTP_STATUS ->
+      // Media3 stuffs the HTTP status into PlaybackException.errorCode
+      // additionally — but the field is private; nativeCode in the
+      // PlaybackError shape carries it via the rich-shape builder.
+      PlaybackErrorCode.HTTP_ERROR
+    PlaybackException.ERROR_CODE_IO_NO_PERMISSION ->
+      PlaybackErrorCode.AUTH_ERROR
+    PlaybackException.ERROR_CODE_IO_CLEARTEXT_NOT_PERMITTED ->
+      PlaybackErrorCode.CLEARTEXT_NOT_PERMITTED
+    PlaybackException.ERROR_CODE_IO_FILE_NOT_FOUND,
+    PlaybackException.ERROR_CODE_IO_INVALID_HTTP_CONTENT_TYPE ->
+      PlaybackErrorCode.SOURCE_UNREACHABLE
+    PlaybackException.ERROR_CODE_PARSING_CONTAINER_MALFORMED,
+    PlaybackException.ERROR_CODE_PARSING_CONTAINER_UNSUPPORTED,
+    PlaybackException.ERROR_CODE_PARSING_MANIFEST_MALFORMED,
+    PlaybackException.ERROR_CODE_PARSING_MANIFEST_UNSUPPORTED ->
+      PlaybackErrorCode.FILE_FORMAT_NOT_RECOGNIZED
+    PlaybackException.ERROR_CODE_DECODER_INIT_FAILED,
+    PlaybackException.ERROR_CODE_DECODER_QUERY_FAILED ->
+      PlaybackErrorCode.DECODER_NOT_FOUND
+    PlaybackException.ERROR_CODE_DECODING_FAILED,
+    PlaybackException.ERROR_CODE_DECODING_FORMAT_EXCEEDS_CAPABILITIES,
+    PlaybackException.ERROR_CODE_DECODING_FORMAT_UNSUPPORTED,
+    PlaybackException.ERROR_CODE_DECODING_RESOURCES_RECLAIMED ->
+      PlaybackErrorCode.DECODING_FAILED
+    else -> PlaybackErrorCode.UNKNOWN
+  }
+
+  /**
+   * Whether the lib should retry on this code automatically (subject
+   * to `PlayerConfig.autoRetries`). Mirrors iOS
+   * `PlaybackErrorMapping.swift#isTransient`.
+   */
+  @VisibleForTesting
+  fun isTransient(code: PlaybackErrorCode): Boolean = when (code) {
+    PlaybackErrorCode.TIMEOUT,
+    PlaybackErrorCode.CONNECTION_LOST,
+    PlaybackErrorCode.NETWORK_UNREACHABLE,
+    PlaybackErrorCode.SOURCE_UNREACHABLE,
+    PlaybackErrorCode.CANNOT_OPEN,
+    PlaybackErrorCode.UNKNOWN -> true
+    PlaybackErrorCode.HTTP_ERROR,
+    PlaybackErrorCode.AUTH_ERROR,
+    PlaybackErrorCode.CLEARTEXT_NOT_PERMITTED,
+    PlaybackErrorCode.FILE_FORMAT_NOT_RECOGNIZED,
+    PlaybackErrorCode.DECODER_NOT_FOUND,
+    PlaybackErrorCode.DECODING_FAILED -> false
+  }
+
+  /**
+   * Strip query strings from a native error message so logged
+   * `nativeMessage` doesn't leak auth tokens (Subsonic-style
+   * `s=…&t=…` salt+token pairs in stream URLs end up inside
+   * `PlaybackException.message`).
+   *
+   * Walks the full message removing EVERY `?…(whitespace|end)` run
+   * so multi-URL error messages have all query strings stripped.
+   * Mirrors iOS `PlaybackErrorMapping.stripQuery`.
+   */
+  @VisibleForTesting
+  fun stripQuery(message: String): String {
+    val out = StringBuilder()
+    var i = 0
+    while (i < message.length) {
+      if (message[i] == '?') {
+        // Skip until whitespace or end.
+        while (i < message.length && !message[i].isWhitespace()) i++
+      } else {
+        out.append(message[i])
+        i++
+      }
+    }
+    return out.toString()
+  }
+
+  /**
+   * Lib-mapped human-readable message for a standardized code.
+   * Mirrors iOS `PlaybackErrorMapping.swift#messageFor`.
+   */
+  @VisibleForTesting
+  fun messageFor(code: PlaybackErrorCode): String = when (code) {
+    PlaybackErrorCode.TIMEOUT -> "Network request timed out."
+    PlaybackErrorCode.CONNECTION_LOST -> "Network connection lost."
+    PlaybackErrorCode.NETWORK_UNREACHABLE -> "Network unreachable."
+    PlaybackErrorCode.HTTP_ERROR -> "Server returned an error response."
+    PlaybackErrorCode.AUTH_ERROR -> "Authentication required or rejected."
+    PlaybackErrorCode.CLEARTEXT_NOT_PERMITTED ->
+      "Cleartext HTTP not permitted by app transport policy."
+    PlaybackErrorCode.FILE_FORMAT_NOT_RECOGNIZED ->
+      "Audio format not recognized."
+    PlaybackErrorCode.DECODER_NOT_FOUND ->
+      "No decoder available for this audio format."
+    PlaybackErrorCode.DECODING_FAILED -> "Audio decoder failure."
+    PlaybackErrorCode.SOURCE_UNREACHABLE ->
+      "Audio source could not be reached."
+    PlaybackErrorCode.CANNOT_OPEN ->
+      "Audio source could not be opened."
+    PlaybackErrorCode.UNKNOWN -> "Playback failed."
+  }
+
+  /**
+   * Construct a richly-populated [PlaybackError] from a
+   * [PlaybackException] + the already-mapped standardized code.
+   * Centralised so every Android error fire site produces the same
+   * shape (sanitised `nativeMessage`, consistent `fatal` classifier,
+   * etc.). Mirrors `TrackPlayer.swift#buildPlaybackError` on iOS.
+   *
+   * `nativeDomain` is `"Media3"` (matches iOS's domain-only
+   * convention — `"NSURLErrorDomain"` / `"AVFoundationErrorDomain"`).
+   * The Media3 `errorCodeName` (e.g.
+   * `"ERROR_CODE_IO_NETWORK_CONNECTION_TIMEOUT"`) is surfaced via
+   * the `nativeMessage` prefix so consumers parsing the message can
+   * grep for the enum name without splitting fields.
+   */
+  fun buildPlaybackError(
+    error: PlaybackException,
+    mapped: PlaybackErrorCode,
+    queueItemId: String = "",
+    url: String = ""
+  ): PlaybackError {
+    val rawMessage = error.message ?: ""
+    // Prefix the message with the Media3 errorCodeName so consumers
+    // can branch on it without parsing nativeDomain. iOS doesn't
+    // need this because NSError carries the code as a number that's
+    // already in nativeCode + iOS error codes don't have stable
+    // string names. nativeMessage stays PII-safe via stripQuery.
+    val prefixedMessage = "${error.errorCodeName}: $rawMessage"
+    return PlaybackError(
+      code = mapped,
+      message = messageFor(mapped),
+      fatal = !isTransient(mapped),
+      nativeCode = error.errorCode.toDouble(),
+      nativeDomain = "Media3",
+      nativeMessage = stripQuery(prefixedMessage),
+      queueItemId = queueItemId,
+      url = url,
+    )
+  }
+}

package/android/src/main/java/com/margelo/nitro/queueplayer/PlaybackModeStateMachine.kt

@@ -0,0 +1,127 @@
+package com.margelo.nitro.queueplayer
+
+/**
+ * Pure-data transition table for `PlaybackMode` switches.
+ *
+ * Owns nothing — `TrackPlayer.setPlaybackMode` calls into the
+ * machine to compute (next state, transition effect) given the
+ * current `active` state. The caller applies the effect:
+ *
+ * - [TransitionEffect.NoOp]          → already in the requested mode.
+ * - [TransitionEffect.ImmediateSwap] → swap engines synchronously,
+ *   regardless of play state. A brief audible interruption while
+ *   the new engine constructs is the expected feedback to the user.
+ *
+ * Always-immediate is the right UX: the user sees + hears the
+ * engine change as soon as they confirm it. The same pattern
+ * extends naturally to cast-engine swaps (Chromecast / AirPlay)
+ * where waiting for a track boundary would be wrong.
+ *
+ * Mirrored on iOS in `PlaybackModeStateMachine.swift` with the
+ * same transition matrix. Cross-platform parity is enforced by
+ * the per-platform unit suites against the same matrix.
+ */
+internal class PlaybackModeStateMachine {
+
+  companion object {
+    /**
+     * Default seed state for first-configure callers — gapless
+     * mode. Avoids hand-construction at every entry point.
+     */
+    val Initial: State = State(active = PlaybackMode(PlaybackModeKind.GAPLESS, null))
+  }
+
+  data class State(
+    val active: PlaybackMode,
+  )
+
+  sealed interface TransitionEffect {
+    object NoOp : TransitionEffect
+    object ImmediateSwap : TransitionEffect
+  }
+
+  /**
+   * Compute the result of a `setPlaybackMode(requested)` call.
+   *
+   * Equality is structural — same kind + same `crossfadeDurationMs`
+   * (or both nil for gapless) is a no-op. Swapping `crossfade(2000)`
+   * → `crossfade(5000)` is NOT equal — the engine must rebuild for
+   * the new duration.
+   *
+   * The caller is responsible for managing the brief audio
+   * interruption (resume position carryover, queue re-attach,
+   * etc.) — that's the engine-handoff contract.
+   */
+  fun setRequested(
+    state: State,
+    requested: PlaybackMode,
+  ): Pair<State, TransitionEffect> {
+    requireValid(requested)
+    if (modesEqual(state.active, requested)) {
+      return state to TransitionEffect.NoOp
+    }
+    return State(active = requested) to TransitionEffect.ImmediateSwap
+  }
+
+  /**
+   * Modes match when kind matches AND, for crossfade, when the
+   * `crossfadeDurationMs` matches. Gapless never carries a duration
+   * and is equal across construction.
+   */
+  private fun modesEqual(a: PlaybackMode, b: PlaybackMode): Boolean {
+    if (a.kind != b.kind) return false
+    return when (a.kind) {
+      PlaybackModeKind.GAPLESS -> true
+      PlaybackModeKind.CROSSFADE -> a.crossfadeDurationMs == b.crossfadeDurationMs
+    }
+  }
+
+  /**
+   * Reject malformed `PlaybackMode` at the state-machine entry so
+   * the downstream `CrossfadeEngine` constructor sees only valid
+   * inputs. Crossfade duration must be:
+   *   - non-null
+   *   - within `[CrossfadeDurationBounds.MIN_MS, CrossfadeDurationBounds.MAX_MS]`
+   *   - quantised to `CrossfadeDurationBounds.STEP_MS` increments
+   *
+   * The runtime safety clamp inside `CrossfadeEngine`
+   * (`effectiveCrossfadeMs`) reduces the configured value further
+   * when the leading or standby track is shorter than twice the
+   * configured duration — that clamp is silent + audio-only +
+   * applies on top of this surface validation.
+   */
+  private fun requireValid(mode: PlaybackMode) {
+    if (mode.kind != PlaybackModeKind.CROSSFADE) return
+    val ms = mode.crossfadeDurationMs
+      ?: throw IllegalArgumentException("PlaybackMode(crossfade) requires crossfadeDurationMs; got null")
+    require(ms.isFinite()) { "crossfadeDurationMs must be finite; got $ms" }
+    require(ms in CrossfadeDurationBounds.MIN_MS..CrossfadeDurationBounds.MAX_MS) {
+      "crossfadeDurationMs must be in [${CrossfadeDurationBounds.MIN_MS}, ${CrossfadeDurationBounds.MAX_MS}]; got $ms"
+    }
+    require(CrossfadeDurationBounds.isQuantised(ms)) {
+      "crossfadeDurationMs must be quantised to ${CrossfadeDurationBounds.STEP_MS}ms steps; got $ms"
+    }
+  }
+}
+
+/**
+ * Surface-validation bounds for `crossfadeDurationMs`. Centralised
+ * so both the state machine + any consumer wanting to render a
+ * stepper UI can read the same numbers.
+ */
+internal object CrossfadeDurationBounds {
+  const val MIN_MS: Double = 1_000.0
+  const val MAX_MS: Double = 12_000.0
+  const val STEP_MS: Double = 500.0
+
+  /**
+   * True when [ms] lands exactly on a [STEP_MS] boundary. Uses
+   * integer rounding so floating-point noise within ±0.5 of an
+   * integer ms doesn't reject otherwise-valid inputs.
+   */
+  fun isQuantised(ms: Double): Boolean {
+    val rounded = kotlin.math.round(ms)
+    if (rounded != ms) return false
+    return rounded.toLong() % STEP_MS.toLong() == 0L
+  }
+}