react-native-queue-player 1.2.0 → 2.0.1

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

@@ -0,0 +1,165 @@
+package com.margelo.nitro.queueplayer
+
+import android.net.Uri
+import androidx.media3.common.C
+import androidx.media3.common.PlaybackException
+import androidx.media3.common.util.UnstableApi
+import androidx.media3.datasource.DataSource
+import androidx.media3.datasource.DataSpec
+import androidx.media3.datasource.HttpDataSource
+import androidx.media3.datasource.TransferListener
+
+/**
+ * Wraps an HTTP-capable [DataSource.Factory] so a response that is a document
+ * rather than media fails before any of it is returned.
+ *
+ * Installed on the prefetcher's upstream only. Media3 writes to its cache sink
+ * only after this `read` returns, so throwing instead of returning keeps the
+ * body out of the cache — and the playback path is left alone, because there a
+ * refusal would be an unplayable track rather than a prefetch that did not
+ * happen. Playback cannot poison the cache either: its `CacheDataSource` is
+ * built read-only.
+ *
+ * Transparent for a source with no response headers (file:// / asset://):
+ * those carry no `Content-Type` and are not the case this exists for.
+ */
+@UnstableApi
+internal class MediaValidatingDataSourceFactory(
+  private val upstream: DataSource.Factory
+) : DataSource.Factory {
+  override fun createDataSource(): DataSource =
+    MediaValidatingDataSource(upstream.createDataSource())
+}
+
+@UnstableApi
+internal class MediaValidatingDataSource(
+  private val delegate: DataSource
+) : DataSource {
+
+  private var dataSpec: DataSpec? = null
+  private var contentType: String? = null
+  private var isHttp = false
+  private var startsAtResourceStart = true
+
+  /**
+   * Bytes read from the delegate to judge the body, held back until the verdict
+   * is in and then served from here before the delegate is read again. Null once
+   * drained — every later read passes straight through.
+   */
+  private var head: ByteArray? = null
+  private var headOffset = 0
+  private var bodyJudged = false
+
+  override fun addTransferListener(transferListener: TransferListener) {
+    delegate.addTransferListener(transferListener)
+  }
+
+  override fun open(dataSpec: DataSpec): Long {
+    this.dataSpec = dataSpec
+    head = null
+    headOffset = 0
+    bodyJudged = false
+    val length = delegate.open(dataSpec)
+    // The scheme says whether this is a remote source. Response headers cannot:
+    // an HTTP answer that carries no `Content-Type` has none, and that is
+    // precisely a body this has to judge. Casting to `HttpDataSource` cannot
+    // either — a wrapper is a `DataSource`, so the cast misses whenever one
+    // sits between this and the HTTP source.
+    isHttp = dataSpec.uri.scheme?.lowercase() in setOf("http", "https")
+    if (!isHttp) {
+      bodyJudged = true
+      return length
+    }
+    // `responseHeaders` is declared on `DataSource`, so it reads through a
+    // wrapper. Header names are case-insensitive and not every server or proxy
+    // normalises them.
+    contentType = delegate.responseHeaders.entries
+      .firstOrNull { it.key.equals("Content-Type", ignoreCase = true) }
+      ?.value?.firstOrNull()
+    startsAtResourceStart = dataSpec.position == 0L
+    // A declared document type is refused here, before a byte is read.
+    MediaResponseCheck.rejection(
+      contentType = contentType,
+      head = EMPTY,
+      headIsStartOfResource = false
+    )?.let { throw rejected(it, dataSpec, HttpDataSource.HttpDataSourceException.TYPE_OPEN) }
+    return length
+  }
+
+  override fun read(buffer: ByteArray, offset: Int, length: Int): Int {
+    if (!bodyJudged) judgeBody()
+    val pending = head
+    if (pending != null) {
+      val remaining = pending.size - headOffset
+      val take = minOf(remaining, length)
+      pending.copyInto(buffer, offset, headOffset, headOffset + take)
+      headOffset += take
+      if (headOffset == pending.size) head = null
+      return take
+    }
+    return delegate.read(buffer, offset, length)
+  }
+
+  /**
+   * Pull enough of the body from the delegate to read a container signature,
+   * judge it, and keep it for [read] to serve. Nothing reaches the caller — and
+   * so nothing reaches the cache — until this has run.
+   */
+  private fun judgeBody() {
+    bodyJudged = true
+    if (!isHttp) return
+    val scratch = ByteArray(MediaResponseCheck.HEAD_BYTES)
+    var filled = 0
+    while (filled < scratch.size) {
+      val read = delegate.read(scratch, filled, scratch.size - filled)
+      // A zero-length read would otherwise spin here; treat it as nothing more
+      // to judge, the same as the end of the input.
+      if (read == C.RESULT_END_OF_INPUT || read == 0) break
+      filled += read
+    }
+    if (filled == 0) return
+    val body = if (filled == scratch.size) scratch else scratch.copyOf(filled)
+    MediaResponseCheck.rejection(
+      contentType = contentType,
+      head = body,
+      headIsStartOfResource = startsAtResourceStart
+    )?.let { throw rejected(it, dataSpec, HttpDataSource.HttpDataSourceException.TYPE_READ) }
+    head = body
+    headOffset = 0
+  }
+
+  private fun rejected(
+    rejection: MediaResponseCheck.Rejection,
+    spec: DataSpec?,
+    type: Int
+  ): HttpDataSource.HttpDataSourceException {
+    val detail = when (rejection) {
+      is MediaResponseCheck.Rejection.MarkupContentType ->
+        "declared type ${rejection.contentType} is a document, not media"
+      is MediaResponseCheck.Rejection.TextWithoutMediaSignature ->
+        "declared type ${rejection.contentType} with no recognised container signature"
+      MediaResponseCheck.Rejection.MarkupBody ->
+        "body begins as a markup or JSON document"
+    }
+    return HttpDataSource.HttpDataSourceException(
+      "Response is not media: $detail",
+      spec ?: DataSpec(Uri.EMPTY),
+      PlaybackException.ERROR_CODE_IO_INVALID_HTTP_CONTENT_TYPE,
+      type
+    )
+  }
+
+  override fun getUri(): Uri? = delegate.uri
+
+  override fun close() {
+    head = null
+    headOffset = 0
+    delegate.close()
+  }
+
+  override fun getResponseHeaders(): Map<String, List<String>> = delegate.responseHeaders
+
+  private companion object {
+    val EMPTY = ByteArray(0)
+  }
+}

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

@@ -4,7 +4,6 @@ import android.net.Uri
 import androidx.media3.common.util.UnstableApi
 import androidx.media3.datasource.DataSource
 import androidx.media3.datasource.DataSpec
-import androidx.media3.datasource.HttpDataSource
 import androidx.media3.datasource.TransferListener
 
 /**
@@ -17,8 +16,8 @@ import androidx.media3.datasource.TransferListener
  * type observed during prefetch and let the playback path pass it
  * to Media3 via [androidx.media3.common.MediaItem.Builder.setMimeType].
  *
- * The wrapper is transparent for non-HTTP underlying sources (file://,
- * asset://) — it forwards every call through and skips MIME capture.
+ * Only the prefetch path builds this, and its window holds http/https URLs
+ * alone, so every response it sees is a server's.
  */
 @UnstableApi
 internal class MimeCapturingDataSourceFactory(
@@ -41,12 +40,13 @@ internal class MimeCapturingDataSource(
 
   override fun open(dataSpec: DataSpec): Long {
     val length = delegate.open(dataSpec)
-    val httpDelegate = delegate as? HttpDataSource ?: return length
-    // HTTP headers are case-insensitive; Media3 normalises but
-    // some servers / proxies emit lowercase. Accept either.
-    val contentType = httpDelegate.responseHeaders["Content-Type"]?.firstOrNull()
-      ?: httpDelegate.responseHeaders["content-type"]?.firstOrNull()
-    onMime(dataSpec.uri.toString(), contentType)
+    // `responseHeaders` is declared on `DataSource`, so this reads through
+    // whatever wraps the HTTP source — casting to `HttpDataSource` would miss,
+    // because a wrapper is a `DataSource`.
+    // Reported even when null: the sink resolves a declared type first and
+    // falls back to the URL's extension, so a response with no `Content-Type`
+    // still gets a usable type recorded.
+    onMime(dataSpec.uri.toString(), contentTypeOf(delegate.responseHeaders))
     return length
   }
 
@@ -61,4 +61,13 @@ internal class MimeCapturingDataSource(
 
   override fun getResponseHeaders(): Map<String, List<String>> =
     delegate.responseHeaders
+
+  private companion object {
+    /** HTTP header names are case-insensitive; some servers and proxies emit
+     *  lowercase and Media3 does not always normalise. */
+    fun contentTypeOf(headers: Map<String, List<String>>): String? =
+      headers.entries
+        .firstOrNull { it.key.equals("Content-Type", ignoreCase = true) }
+        ?.value?.firstOrNull()
+  }
 }

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

@@ -28,6 +28,42 @@ import com.margelo.nitro.core.NullType
 @UnstableApi
 internal object NowPlayingFormatExtractor {
 
+  /**
+   * Average encoded bitrate of a `file://` source, from its size and duration.
+   *
+   * The figure is an average over the whole file, which is what "bitrate"
+   * means for a variable-rate codec anyway, and it includes the container's
+   * headers and any embedded artwork — a few kbps on a typical track.
+   *
+   * Returns null for any non-local source, for a file that cannot be measured,
+   * and for a duration the player has not resolved yet: a bitrate derived from
+   * an unknown duration would be arbitrary, and reporting nothing is the
+   * honest answer until the player knows.
+   */
+  private fun deriveLocalBitrate(player: Player, durationSec: Double?): Double? {
+    val uri = player.currentMediaItem?.localConfiguration?.uri ?: return null
+    if (!uri.scheme.equals("file", ignoreCase = true)) return null
+    return averageBitrateOf(uri.path, durationSec)
+  }
+
+  /**
+   * Average bits per second of the file at [path] over [durationSec].
+   *
+   * Split from its caller so the arithmetic is reachable without a player.
+   * Null for an unusable duration, an unreadable path, or an empty file —
+   * every case where the answer would be invented rather than measured.
+   */
+  internal fun averageBitrateOf(path: String?, durationSec: Double?): Double? {
+    if (durationSec == null || durationSec <= 0.0) return null
+    if (path == null) return null
+    // One `stat` of a local file, taken on the looper with the rest of the
+    // player snapshot; the answer is not worth an extra hop.
+    val bytes = runCatching { java.io.File(path).length() }.getOrNull() ?: return null
+    if (bytes <= 0L) return null
+    val bitsPerSecond = bytes * 8.0 / durationSec
+    return if (bitsPerSecond.isFinite() && bitsPerSecond > 0.0) bitsPerSecond else null
+  }
+
   /**
    * Extract the format snapshot from `player`'s currently selected
    * audio track. Returns `null` only when no audio track exists in the
@@ -53,7 +89,7 @@ internal object NowPlayingFormatExtractor {
     val mimeType = format.sampleMimeType
     val sampleRate = format.sampleRate.takeIf { it != Format.NO_VALUE }?.toDouble()
     val channelCount = format.channelCount.takeIf { it != Format.NO_VALUE }?.toDouble()
-    val bitrate = format.bitrate.takeIf { it != Format.NO_VALUE }?.toDouble()
+    val reportedBitrate = format.bitrate.takeIf { it != Format.NO_VALUE }?.toDouble()
     val peakBitrate = format.peakBitrate.takeIf { it != Format.NO_VALUE }?.toDouble()
     val pcmEncoding = format.pcmEncoding.takeIf { it != Format.NO_VALUE }?.toDouble()
     val codecsString = format.codecs
@@ -61,6 +97,17 @@ internal object NowPlayingFormatExtractor {
     val durationSec = if (durationMs == C.TIME_UNSET || durationMs <= 0) null
                       else durationMs / 1000.0
 
+    // Media3 leaves both bitrate fields unset for some codecs — FLAC reports
+    // NO_VALUE for average and peak alike, on local files as well as remote —
+    // so a consumer asking what it is playing gets nothing back. Where the
+    // source is on disk the average is arithmetic: encoded bytes over playing
+    // time. Not gated on codec; it fills in whatever the extractor did not
+    // report, and does nothing when Media3 already answered.
+    //
+    // A local stat only. A remote source would need its Content-Length, which
+    // costs a request the library deliberately does not make.
+    val bitrate = reportedBitrate ?: deriveLocalBitrate(player, durationSec)
+
     val rgData = engine?.currentReplayGainData()
     val rgActive = engine?.currentReplayGainActive() ?: false
 

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

@@ -9,8 +9,9 @@ import androidx.media3.common.PlaybackParameters
  *   time-stretch resamples, so pitch shifts with speed.
  * - `voice` → pitch preserved (`pitch == 1`): the built-in (speech-tuned)
  *   time-stretch holds pitch while changing speed.
- * - `music` → currently the same pitch-preserving path as `voice`; a
- *   dedicated music-grade engine is a separate effort.
+ * - `music` → the same parameters as `voice` (`pitch == 1`); which
+ *   stretcher applies them is `PitchAwareAudioProcessorChain`'s choice —
+ *   `SignalsmithStretchAudioProcessor` for `music`, Sonic otherwise.
  *
  * At `speed == 1.0` every mode yields `(1.0, 1.0)`, so the built-in
  * stretch is inactive — the auto-bypass at unity rate.

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

@@ -9,40 +9,29 @@ import androidx.media3.exoplayer.audio.TeeAudioProcessor
 /**
  * Strategy abstraction over the audio output pipeline.
  *
- * Two concrete implementations:
+ * Three concrete implementations:
  *  - [GaplessEngine]: single ExoPlayer, native gapless via item chaining.
  *  - [CrossfadeEngine]: dual ExoPlayer with equal-power gain ramping at
  *    track boundaries.
+ *  - [AirPlayEngine]: single ExoPlayer bound to an AirPlay PCM sink;
+ *    selected by `applyEngineSwapForMode` while an AirPlay session is
+ *    active.
  *
  * 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.
+ * through whichever engine is active. An engine swap (gapless ↔ crossfade)
+ * is `TrackPlayer.applyEngineSwapForMode`: [PlaybackService.swapEngine]
+ * installs the new engine and releases the old one, then `TrackPlayer`
+ * seeds the new engine through [setMediaItems].
  *
  * 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).
+ * noted; 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.
@@ -127,20 +116,16 @@ interface PlaybackEngine {
   val allMediaItems: List<MediaItem>
 
   /**
-   * Underlying ExoPlayer instance the service-level wiring
-   * (audio-focus listener, `MediaSession.setPlayer`) attaches
-   * to. `GaplessEngine` returns its single player; `CrossfadeEngine`
+   * Underlying ExoPlayer for the audio-focus listener and the
+   * `MediaSession` binding. `GaplessEngine` returns its single
+   * player, which [PlaybackService] binds directly; `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.
+   * A mid-fade role swap inside `CrossfadeEngine` flips which player this
+   * getter returns, and nothing re-reads it: [PlaybackService] binds a
+   * crossfade engine through a [CrossfadeForwardingPlayer] instead, which
+   * re-targets via `setPlayer` on every role swap, fade start and fade
+   * cancel, so the session and the focus listener follow the audible leg.
    */
   val mediaSessionPlayer: ExoPlayer
 
@@ -176,12 +161,36 @@ interface PlaybackEngine {
   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.
+   * Settle any in-flight or armed crossfade so the queue can be mutated by
+   * something other than this engine.
+   *
+   * An armed standby leg holds a snapshot of the queue taken when it was
+   * armed. A caller that appends or replaces items through a path the engine
+   * does not see — Media3 setting them on the session player after resolving
+   * an assistant request — leaves that snapshot stale, and promoting it drops
+   * whatever the caller added. Default is a no-op: an engine with one player
+   * has nothing to settle.
+   */
+  fun settlePendingFade() {}
+
+  /**
+   * Settle an in-flight fade by promoting the incoming leg, so the leg a
+   * caller reads is the track actually being heard.
+   *
+   * Mid-fade the leading leg holds the outgoing track while the canonical
+   * index names the incoming one, so a caller that reads the player and the
+   * index together sees two different tracks. Promoting resolves them to the
+   * incoming track, which is the one the listener is arriving at. Default is a
+   * no-op: an engine with one player is never in this state.
+   */
+  fun settlePendingFadeByPromoting() {}
+
+  /**
+   * 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. The default is `null`, for an engine that
+   * reads no tags.
    */
   fun currentReplayGainData(): ReplayGainData? = null
 
@@ -194,43 +203,22 @@ interface PlaybackEngine {
    */
   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.
+   * Strong reference by design; the iOS counterpart is `weak` because
+   * `TrackPlayer` owns its engine strongly and Swift's reference graph
+   * would otherwise close (TrackPlayer → engine → delegate → TrackPlayer).
+   * On Android the engine lives inside [PlaybackService], reached through
+   * [PlaybackService.LocalBinder.engine] and owned by the service
+   * lifecycle, not by TrackPlayer; the cycle is broken explicitly by
+   * [release] dropping `delegate` and by `TrackPlayer.tearDownEventObservers`
+   * clearing itself from the engine's `delegate`.
    *
    * Threading: setter MUST be invoked on the service main looper to
-   * avoid a write-vs-fire race during [handoff].
+   * avoid a write-vs-fire race during an engine swap.
    */
   var delegate: PlaybackEngineDelegate?
 }
@@ -290,10 +278,14 @@ interface PlaybackEngineDelegate {
   fun onActiveItemFormatChanged(engine: PlaybackEngine)
 
   /**
-   * Fires on Media3 `Player.Listener.onPlayerError`. The delegate
-   * maps [exception] via the lib's `PlaybackErrorMapping`.
+   * Fires on Media3 `Player.Listener.onPlayerError`. The delegate maps
+   * [exception] via the lib's `PlaybackErrorMapping`. [failedIndex] is the
+   * queue position of the item that failed, or -1 when the engine cannot
+   * attribute it. A crossfade engine can fail on its standby leg while the
+   * leading leg plays on, so the failure need not belong to the track the
+   * delegate considers current.
    */
-  fun onError(engine: PlaybackEngine, exception: PlaybackException)
+  fun onError(engine: PlaybackEngine, exception: PlaybackException, failedIndex: Int = -1)
 
   /**
    * Fires on Media3 `Player.STATE_ENDED`. The delegate consults the
@@ -316,9 +308,10 @@ interface PlaybackEngineDelegate {
    * [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
+   * `onTrackChange` for the incoming track; the `MediaSession` re-bind
+   * to the standby leg is [CrossfadeForwardingPlayer]'s, through the
+   * engine's `onCrossfadeBegin` lambda. The subsequent `onTrackTransition`
+   * for the same incoming index is a structural Media3 echo and must be
    * deduplicated.
    *
    * Crossfade-only — [GaplessEngine] never invokes this.
@@ -333,7 +326,9 @@ interface PlaybackEngineDelegate {
    * 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
+   * track; the `MediaSession` re-bind back to the leading leg is
+   * [CrossfadeForwardingPlayer]'s, through the engine's
+   * `onCrossfadeCancel` lambda. Pairs with
    * [onCrossfadeBegin]: only fires when a `Begin` was fired
    * earlier and the fade did not complete.
    *

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

@@ -43,9 +43,17 @@ internal object PlaybackErrorMapping {
       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 ->
+    PlaybackException.ERROR_CODE_IO_FILE_NOT_FOUND ->
       PlaybackErrorCode.SOURCE_UNREACHABLE
+    PlaybackException.ERROR_CODE_IO_INVALID_HTTP_CONTENT_TYPE ->
+      // The source answered, and what it sent is not media — a server
+      // reporting an API-level failure as a successful response, or a proxy
+      // serving an error page. Not SOURCE_UNREACHABLE: it was reached, and
+      // calling it unreachable invites a retry that cannot change the answer.
+      // Not HTTP_ERROR either: the status was a success. What is wrong is the
+      // payload, which is the same thing iOS reports when AVFoundation fails to
+      // parse the identical body.
+      PlaybackErrorCode.FILE_FORMAT_NOT_RECOGNIZED
     PlaybackException.ERROR_CODE_PARSING_CONTAINER_MALFORMED,
     PlaybackException.ERROR_CODE_PARSING_CONTAINER_UNSUPPORTED,
     PlaybackException.ERROR_CODE_PARSING_MANIFEST_MALFORMED,
@@ -85,9 +93,9 @@ internal object PlaybackErrorMapping {
 
   /**
    * 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`).
+   * `nativeMessage` doesn't leak auth tokens: stream URLs with
+   * `?token=…`-style query strings end up inside
+   * `PlaybackException.message`.
    *
    * Walks the full message removing EVERY `?…(whitespace|end)` run
    * so multi-URL error messages have all query strings stripped.

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

@@ -49,8 +49,8 @@ internal class PlaybackModeStateMachine {
    * 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.
+   * interruption — `applyEngineSwapForMode` carries the position
+   * and re-installs the queue.
    */
   fun setRequested(
     state: State,