react-native-queue-player 1.2.0 → 2.0.1

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

@@ -57,7 +57,7 @@ public abstract class HeadlessJsMediaService :
   internal val activeTasks: MutableSet<Int> = CopyOnWriteArraySet()
 
   /**
-   * Latch flipped on the first task spawn so a re-entrant
+   * Set on the first task spawn so a re-entrant
    * [onStartCommand] for the same wake doesn't double-start the JS
    * handler. Reset is implicit — service destruction reclaims this
    * field along with the rest of the instance.

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

@@ -8,7 +8,9 @@ package com.margelo.nitro.queueplayer
  * call through the interface; consumers never see which backend
  * is active.
  *
- * Threading: methods are called from the service main looper.
+ * Threading: see the implementations — attach / detach arrive on the
+ * service main looper and on the Equalizer-constructing thread, the
+ * mutators on the `Promise.async` pool, the getters on the JS thread.
  */
 interface IEqualizerEngine {
 

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

@@ -43,9 +43,13 @@ class LookaheadCache(
   evictionPolicy: EvictionPolicy = EvictionPolicy.LRU
 ) {
 
-  /** Resolved on-disk cache directory: `context.cacheDir/<cacheDirName>`. */
+  /**
+   * Resolved on-disk cache directory: `context.cacheDir/<cacheDirName>`.
+   * Resolved through the application context, as the shared-instance key is,
+   * so a wrapper context with its own `cacheDir` cannot split the two.
+   */
   @VisibleForTesting
-  val cacheDir: File = File(context.cacheDir, cacheDirName)
+  val cacheDir: File = File(context.applicationContext.cacheDir, cacheDirName)
 
   private val shared: SharedCacheInstance =
     sharedInstanceFor(context.applicationContext, cacheDir, maxSizeBytes, evictionPolicy)
@@ -58,7 +62,28 @@ class LookaheadCache(
   @VisibleForTesting
   internal val simpleCache: SimpleCache = shared.cache
 
-  private val databaseProvider: StandaloneDatabaseProvider = shared.databaseProvider
+  private val protectingEvictor: FifoCacheEvictor? = shared.protectingEvictor
+
+  /**
+   * Name the urls eviction must not take — the playing track and its
+   * neighbours. Eviction runs on every span commit, so without this the entry
+   * backing the playing track can be deleted while it plays.
+   *
+   * A no-op under the LRU policy, whose evictor has no protected-key concept.
+   * LRU is not an equivalent safeguard — it bumps the recency of the span just
+   * read, not the whole resource — so on Android the playing track is only
+   * genuinely protected under FIFO. iOS protects under both policies.
+   */
+  fun setProtectedUrls(urls: Set<String>) {
+    protectingEvictor?.setProtectedKeys(urls)
+  }
+
+  /**
+   * Whether this cache's evictor honours [setProtectedUrls]. False under LRU,
+   * letting callers skip building a set that would be discarded.
+   */
+  val honoursProtection: Boolean
+    get() = protectingEvictor != null
 
   /**
    * Per-URL MIME store populated by the prefetch path's
@@ -89,8 +114,32 @@ class LookaheadCache(
    * transparently fall through to a re-download instead of
    * surfacing a load error.
    */
-  fun wrapDataSourceFactory(upstream: DataSource.Factory): DataSource.Factory =
-    cacheDataSourceFactory(upstream)
+  fun wrapDataSourceFactory(upstream: DataSource.Factory): DataSource.Factory {
+    // Read-only for playback. A write here would commit whatever the origin
+    // answered with — a server's error envelope included — as a track, and the
+    // body check that refuses one belongs on the prefetch path, where a false
+    // refusal costs a prefetch instead of the track. `null` sets Media3's
+    // `cacheIsReadOnly`, which is tested before the default-sink fallback.
+    // So playing a track does not cache it and does not complete a partial
+    // prefetch of it; only the prefetcher writes. Matches iOS, whose
+    // read-through server also only reads.
+    val cached = cacheDataSourceFactory(upstream).setCacheWriteDataSinkFactory(null)
+    // Decided per data source, which Media3 creates per item load, so a
+    // change to `servesPlayback` reaches the next item without rebuilding
+    // the player; the item already loading keeps the source it opened.
+    return DataSource.Factory {
+      if (servesPlayback) cached.createDataSource() else upstream.createDataSource()
+    }
+  }
+
+  /**
+   * Whether the player's reads go through this cache. False while the
+   * consumer has the cache disabled: every read then goes to the origin and
+   * nothing is written, whatever the disk already holds. Written on main by
+   * `TrackPlayer`, read on Media3's loading thread when an item opens.
+   */
+  @Volatile
+  var servesPlayback: Boolean = true
 
   /**
    * Build a [CacheDataSource.Factory] rooted at [simpleCache] +
@@ -121,8 +170,13 @@ class LookaheadCache(
       //     helping" signal. Log the reason so a "why is this not
       //     cached" investigation has a trail.
       .setEventListener(object : CacheDataSource.EventListener {
-        // Required by EventListener; no per-byte progress surfaced today.
-        override fun onCachedBytesRead(cacheSizeBytes: Long, cachedBytesRead: Long) { }
+        override fun onCachedBytesRead(cacheSizeBytes: Long, cachedBytesRead: Long) {
+          // Accumulated rather than logged per read: this fires per buffer, so
+          // logging here would flood. The running total is what answers
+          // "is playback actually being served from the cache", which cannot
+          // be told apart from a network read by listening.
+          cachedBytesReadTotal.addAndGet(cachedBytesRead)
+        }
         override fun onCacheIgnored(reason: Int) {
           val name = when (reason) {
             CacheDataSource.CACHE_IGNORED_REASON_ERROR -> "ERROR"
@@ -137,7 +191,13 @@ class LookaheadCache(
       })
 
   /**
-   * Drop per-instance state. The [SimpleCache] + [databaseProvider]
+   * Total bytes served to the player from cache rather than upstream.
+   * Monotonic for the cache's lifetime; read as a delta across an interval.
+   */
+  val cachedBytesReadTotal = java.util.concurrent.atomic.AtomicLong(0)
+
+  /**
+   * Drop per-instance state. The [SimpleCache] + database provider
    * stay alive (process-singleton, see class doc) — releasing them
    * would race Media3's `lockedFolders` static registry on the next
    * [LookaheadCache] construction targeting the same directory.
@@ -173,18 +233,17 @@ class LookaheadCache(
   // --- Status surface ---
 
   /**
-   * Sum of cached bytes across every key in the cache. Walks
-   * `simpleCache.keys` + `getCachedBytes` per key. O(N) on the
-   * key count + cheap span lookup. Used by
-   * [TrackPlayer.getLookaheadCacheStatus] for the
-   * `currentSizeMb` field.
+   * Bytes currently held on disk. Reads the total Media3 already maintains, so
+   * it is O(1) and needs no lock beyond the cache's own.
+   *
+   * Also more accurate than summing per-key cached bytes, which reports zero
+   * for any resource whose content length has not been recorded yet — a
+   * chunked download in flight occupies disk but has no length until it
+   * completes. Used by [TrackPlayer.getLookaheadCacheStatus] for `currentSizeMb`.
    */
-  fun currentSizeBytes(): Long {
-    return simpleCache.keys.sumOf { key ->
-      val length = contentLength(key) ?: return@sumOf 0L
-      simpleCache.getCachedBytes(key, 0, length)
-    }
-  }
+  // Every SimpleCache method rejects a released cache, and this is read off the
+  // looper that releases it. A cache that has gone away holds nothing.
+  fun currentSizeBytes(): Long = runCatching { simpleCache.cacheSpace }.getOrDefault(0L)
 
   /**
    * Whether the cache holds the entire content for `key`. True
@@ -210,12 +269,12 @@ class LookaheadCache(
    * field — the count reflects the cache itself, not the intersection
    * with `self.tracks`.
    */
-  fun fullyCachedCount(): Int {
-    return simpleCache.keys.count { key ->
+  fun fullyCachedCount(): Int = runCatching {
+    simpleCache.keys.count { key ->
       val length = contentLength(key) ?: return@count false
       simpleCache.getCachedBytes(key, 0, length) >= length
     }
-  }
+  }.getOrDefault(0)
 
   /**
    * Wipe every cached entry + free the on-disk space. Used by
@@ -224,9 +283,14 @@ class LookaheadCache(
    * handles the file deletion + index update internally.
    */
   fun clear() {
-    val keys = simpleCache.keys.toList()
+    // Every SimpleCache method rejects a released cache, the key walk included.
+    // A policy change releases the shared instance out from under an in-flight
+    // wipe, and this now runs off the caller's thread, so an escaping throw
+    // reaches the default handler rather than the JS call that asked for it.
+    // Nothing is left to clear in that case — the release took the files with it.
+    val keys = runCatching { simpleCache.keys.toList() }.getOrElse { return }
     for (key in keys) {
-      simpleCache.removeResource(key)
+      runCatching { simpleCache.removeResource(key) }.getOrElse { return }
     }
     mimeStore.clear()
   }
@@ -312,11 +376,20 @@ class LookaheadCache(
         EvictionPolicy.FIFO -> FifoCacheEvictor(maxSizeBytes)
       }
       val cache = SimpleCache(cacheDir, evictor, db)
-      val newInstance = SharedCacheInstance(cache, db)
+      val newInstance = SharedCacheInstance(cache, db, evictor as? FifoCacheEvictor, evictionPolicy)
       sharedInstances[key] = newInstance
       return newInstance
     }
 
+    /**
+     * The eviction policy the live cache for [cacheDir] was built with, or null
+     * when this process holds no cache there. Media3 fixes the evictor at
+     * construction, so the instance is the record of what was applied.
+     */
+    @JvmStatic
+    internal fun appliedEvictionPolicy(cacheDir: File): EvictionPolicy? =
+      sharedInstances[cacheDir.absolutePath]?.evictionPolicy
+
     /**
      * Release + forget the shared SimpleCache for [cacheDir] so the next
      * [LookaheadCache] construction builds a fresh one. Used when the eviction
@@ -326,18 +399,27 @@ class LookaheadCache(
      */
     @JvmStatic
     @Synchronized
-    internal fun releaseSharedInstance(cacheDir: File) {
-      sharedInstances.remove(cacheDir.absolutePath)?.cache?.release()
+    internal fun releaseSharedInstance(cacheDir: File): StandaloneDatabaseProvider? {
+      val instance = sharedInstances.remove(cacheDir.absolutePath) ?: return null
+      instance.cache.release()
+      // Handed back so the caller can drop the cache's index tables along with
+      // its files. Index storage is keyed by the cache uid, so deleting the
+      // directory alone strands one table per policy change.
+      return instance.databaseProvider
     }
   }
 
   /**
    * Pair of process-singleton SimpleCache + DatabaseProvider for a
    * single cache folder. Held by the companion object's
-   * [sharedInstances] map; never released within the process lifetime.
+   * [sharedInstances] map until [releaseSharedInstance] drops it for a
+   * policy change; a destroy leaves it in place.
    */
   private data class SharedCacheInstance(
     val cache: SimpleCache,
-    val databaseProvider: StandaloneDatabaseProvider
+    val databaseProvider: StandaloneDatabaseProvider,
+    /** Null under LRU, which has no protected-key concept. */
+    val protectingEvictor: FifoCacheEvictor?,
+    val evictionPolicy: EvictionPolicy,
   )
 }

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

@@ -9,6 +9,7 @@ import androidx.media3.datasource.DataSource
 import androidx.media3.datasource.DataSpec
 import androidx.media3.datasource.cache.CacheDataSource
 import androidx.media3.datasource.cache.CacheWriter
+import java.io.IOException
 import kotlinx.coroutines.CancellationException
 import kotlinx.coroutines.CoroutineScope
 import kotlinx.coroutines.Deferred
@@ -16,7 +17,10 @@ import kotlinx.coroutines.Dispatchers
 import kotlinx.coroutines.Job
 import kotlinx.coroutines.SupervisorJob
 import kotlinx.coroutines.async
+import kotlinx.coroutines.awaitCancellation
 import kotlinx.coroutines.cancel
+import kotlinx.coroutines.ensureActive
+import kotlinx.coroutines.isActive
 import kotlinx.coroutines.launch
 import kotlinx.coroutines.withContext
 
@@ -48,10 +52,10 @@ import kotlinx.coroutines.withContext
  * flaky-network resilience:
  *
  * - Per-track download failure (IOException, HTTP error, transient
- *   network drop): swallowed via [logSwallowed]; the orchestrator
- *   continues to the next pending target. The failed URL is NOT
- *   marked as cached or in-flight, so it remains eligible for
- *   re-attempt on a subsequent reschedule.
+ *   network drop): caught in the orchestrator loop and logged at
+ *   `Log.w`; the orchestrator continues to the next pending target.
+ *   The failed URL is NOT marked as cached or in-flight, so it
+ *   remains eligible for re-attempt on a subsequent reschedule.
  * - Complete network outage (every target throws): orchestrator
  *   drains pendingTargets cleanly, leaves [inFlightUrl] null, and
  *   exits. The next [reschedule] call re-enqueues the still-desired
@@ -75,9 +79,21 @@ import kotlinx.coroutines.withContext
 class LookaheadCacheWriter @VisibleForTesting internal constructor(
   @get:VisibleForTesting internal val downloader: suspend (TrackItem) -> Unit,
   @get:VisibleForTesting internal val scope: CoroutineScope,
-  @get:VisibleForTesting internal val isFullyCached: (String) -> Boolean = { false }
+  @get:VisibleForTesting internal val isFullyCached: (String) -> Boolean = { false },
+  /** True when the active network is cellular. Consulted only while
+   *  [allowsCellularAccess] is false. */
+  internal val isOnCellular: () -> Boolean = { false }
 ) {
 
+  /**
+   * Whether prefetch may run over cellular. False empties the desired
+   * window while the active network is cellular, so nothing is
+   * enqueued and an in-flight download is cancelled on the next
+   * [reschedule]. Set from `setLookaheadCache`.
+   */
+  @Volatile
+  internal var allowsCellularAccess: Boolean = true
+
   /**
    * Optional callback fired after each per-track download iteration
    * completes (success, failure, or cancellation handled). Used by
@@ -182,6 +198,14 @@ class LookaheadCacheWriter @VisibleForTesting internal constructor(
     val desired = mutableListOf<TrackItem>()
     desired.addAll(computeTargets(tracks, currentIndex, lookaheadCount))
     lookbackTarget(tracks, currentIndex)?.let { desired.add(it) }
+    // Prefetch downloads whole upcoming tracks, so on a metered connection it
+    // can spend a lot of data on tracks the listener skips past. When it is not
+    // permitted nothing is desired, and the reconciliation below prunes what is
+    // pending and cancels what is in flight. The next reschedule refills it —
+    // a track advance, a skip, a queue change, or the flag going back on.
+    if (!allowsCellularAccess && isOnCellular()) {
+      desired.clear()
+    }
     val desiredUrls = desired.map { it.url }.toSet()
 
     val toCancel: Job?
@@ -225,6 +249,8 @@ class LookaheadCacheWriter @VisibleForTesting internal constructor(
 
     // Cancel outside the lock — Job.cancel() is fast but can run
     // listeners on this thread.
+    // Cancelling the job is what stops the blocking write too: the download
+    // body relays its coroutine's cancellation onto its own `CacheWriter`.
     toCancel?.cancel()
 
     if (needsOrchestrator) {
@@ -266,10 +292,9 @@ class LookaheadCacheWriter @VisibleForTesting internal constructor(
   }
 
   /**
-   * Cancel + tear down the coroutine scope. Call from
-   * [TrackPlayer.destroyInternal] before the [LookaheadCache] is
-   * released — once the cache is gone, an in-flight CacheWriter
-   * reading from `cache.simpleCache` would NPE.
+   * Cancel + tear down the coroutine scope. Called before
+   * `LookaheadCache.release()` clears the MIME store, so a prefetch
+   * still in flight cannot record a MIME type after the clear.
    */
   fun release() {
     requireMainThread()
@@ -278,11 +303,12 @@ class LookaheadCacheWriter @VisibleForTesting internal constructor(
   }
 
   /**
-   * Reads/writes of `inFlightUrl`, `inFlightJob`, `orchestratorJob`,
-   * and `pendingTargets` happen exclusively on main; this trap turns
-   * a future off-main caller into a debug-build crash so the bug is
-   * visible at the call site instead of as a silent race on the
-   * cache state.
+   * The public entry points (reschedule / cancel / release) are main-only; this
+   * trap turns a future off-main caller into a crash at the call site
+   * so the mistake is visible there. The fields themselves —
+   * `inFlightUrl`, `inFlightJob`, `orchestratorJob`, `pendingTargets`
+   * — are also written from the IO orchestrator coroutine, so they are
+   * guarded by `stateLock`, not by thread affinity.
    *
    * `runCatching` swallows the "Method myLooper in android.os.Looper
    * not mocked" exception that fires on a JVM host without the Android
@@ -313,7 +339,11 @@ class LookaheadCacheWriter @VisibleForTesting internal constructor(
     if (lookaheadCount <= 0 || tracks.isEmpty()) return emptyList()
     val start = (currentIndex + 1).coerceAtLeast(0)
     if (start >= tracks.size) return emptyList()
-    val end = (start + lookaheadCount).coerceAtMost(tracks.size)
+    // `start + lookaheadCount` overflows to a negative for a very large count,
+    // which coerceAtMost then keeps and subList rejects. The count reaches here
+    // from a JS Double, so Int.MAX_VALUE is one `Infinity` away.
+    val remaining = tracks.size - start
+    val end = start + lookaheadCount.coerceAtMost(remaining)
     return tracks.subList(start, end).filter { isRemote(it.url) }
   }
 
@@ -475,7 +505,8 @@ class LookaheadCacheWriter @VisibleForTesting internal constructor(
      */
     fun create(
       cache: LookaheadCache,
-      httpFactory: DataSource.Factory
+      httpFactory: DataSource.Factory,
+      isOnCellular: () -> Boolean
     ): LookaheadCacheWriter {
       val scope = CoroutineScope(Dispatchers.IO + SupervisorJob())
       // Wrap the upstream HTTP factory so each prefetch download
@@ -485,34 +516,35 @@ class LookaheadCacheWriter @VisibleForTesting internal constructor(
       // window where we'd want to learn the format. Mirrors iOS's
       // file-extension persistence on the cached file.
       val mimeCapturingFactory = MimeCapturingDataSourceFactory(
-        upstream = httpFactory,
+        upstream = MediaValidatingDataSourceFactory(httpFactory),
         onMime = { uri, contentType -> cache.recordMimeType(uri, contentType) }
       )
       val cacheDataSourceFactory = cache.cacheDataSourceFactory(mimeCapturingFactory)
       return LookaheadCacheWriter(
         downloader = { track -> downloadViaCacheWriter(track, cacheDataSourceFactory) },
         scope = scope,
-        isFullyCached = cache::isFullyCached
+        isFullyCached = cache::isFullyCached,
+        isOnCellular = isOnCellular
       )
     }
 
     /**
-     * Per-track download body. Builds a fresh [CacheDataSource] from
-     * the shared factory, runs the synchronous `CacheWriter.cache()`
-     * on `Dispatchers.IO`. Coroutine cancellation propagates via the
-     * explicit `CancellationException` catch — `writer.cancel()`
-     * sets the volatile cancel flag that the cache loop polls
-     * between buffer iterations, then we rethrow so the parent
-     * launch's `for (track in targets)` loop terminates.
+     * Per-track download body. Builds a fresh [CacheDataSource] from the
+     * shared factory and runs the synchronous `CacheWriter.cache()` on
+     * `Dispatchers.IO`. `cache()` blocks and polls only its own cancelled
+     * flag, so the coroutine's cancellation is relayed onto that flag by a
+     * child that exists to be cancelled with it — each writer is tied to
+     * its own job, which is what keeps a cancel from reaching the download
+     * the orchestrator starts next.
      */
     private suspend fun downloadViaCacheWriter(
       track: TrackItem,
-      cacheDataSourceFactory: CacheDataSource.Factory
+      cacheDataSourceFactory: CacheDataSource.Factory,
     ) = withContext(Dispatchers.IO) {
       val cacheDataSource = cacheDataSourceFactory.createDataSource()
       // Cache key = source URL. The consumer-supplied `track.id` is
-      // a metadata field that varies per app (Subsonic-style hash,
-      // Spotify URI, app-internal counter); keying by URL keeps the
+      // a metadata field that varies per app (a server-side hash, a
+      // catalogue URI, an app-internal counter); keying by URL keeps the
       // cache generic + correct across apps + matches iOS. Same
       // URL → same cache file (collision === "already cached").
       val dataSpec = DataSpec.Builder()
@@ -520,11 +552,27 @@ class LookaheadCacheWriter @VisibleForTesting internal constructor(
         .setKey(track.url)
         .build()
       val writer = CacheWriter(cacheDataSource, dataSpec, /* temporaryBuffer = */ null, /* progressListener = */ null)
+      // Unconfined, so the relay resumes on the thread that cancels the job
+      // rather than waiting for an IO worker: the workers are what a
+      // blocking `cache()` occupies, and a cancel that queued behind them
+      // would leave the download running for as long as they stay busy.
+      val cancelRelay = launch(Dispatchers.Unconfined) {
+        try {
+          awaitCancellation()
+        } finally {
+          writer.cancel()
+        }
+      }
       try {
+        ensureActive()
         writer.cache()
-      } catch (e: CancellationException) {
-        writer.cancel()
+      } catch (e: IOException) {
+        // A cancelled writer throws InterruptedIOException; report it as the
+        // cancellation it is so the orchestrator does not log a failed prefetch.
+        if (!isActive) throw CancellationException("prefetch cancelled").also { it.initCause(e) }
         throw e
+      } finally {
+        cancelRelay.cancel()
       }
     }
   }

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

@@ -25,8 +25,8 @@ import androidx.media3.extractor.DefaultExtractorsFactory
  * header override) and lines up with which names
  * [DefaultHttpDataSource.Factory.setDefaultRequestProperties] as the
  * integration point. Per-track headers would require a custom
- * MediaSource.Factory reading per-item metadata extras — tracked as
- * a backlog item if Subsonic-style per-request signing ever lands.
+ * MediaSource.Factory reading per-item metadata extras, which this
+ * builder does not do.
  *
  * `file://` URIs transparently route through [DefaultDataSource]
  * without touching the HTTP factory — matches iOS's file-URL
@@ -249,8 +249,8 @@ object MediaItemBuilder {
    * remain coherent.
    *
    * Read timeout: defaults to 30000 ms (vs Media3's 8s default).
-   * The longer timeout tolerates slow-spin-up servers (e.g. Subsonic
-   * on spun-down disks needing ~20s to respond). Connect timeout
+   * The longer timeout tolerates slow-spin-up servers (a media server
+   * on spun-down disks can take ~20s to respond). Connect timeout
    * stays at Media3's 8s default — TCP handshake is unaffected by
    * disk spin-up.
    */
@@ -264,8 +264,8 @@ object MediaItemBuilder {
       if (merged.isNotEmpty()) {
         setDefaultRequestProperties(merged)
       }
-      // Subsonic-behind-reverse-proxy deployments redirect
-      // http→https (or vice versa) for auth flows; disabling
+      // Some servers behind a reverse proxy redirect http→https (or
+      // vice versa) for auth flows; disabling
       // cross-protocol redirects silently truncates downloads
       // partway through a redirect.
       setAllowCrossProtocolRedirects(true)

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

@@ -0,0 +1,156 @@
+package com.margelo.nitro.queueplayer
+
+/**
+ * Decides whether an HTTP response that claims to carry a track can be
+ * believed, from its `Content-Type` and the first bytes of its body.
+ *
+ * A server that answers an API-level failure with `200` and an XML or JSON
+ * envelope is the case this exists for: media servers commonly report
+ * errors that way by design, and a proxy answering with an HTML page does the
+ * same. Such a body passes every length and status check, so without this the
+ * prefetcher writes it into the cache as a complete track and it is served from
+ * disk on every later play — the track stays broken after the server is well
+ * again.
+ *
+ * The rules identify what is **not** media rather than demanding proof of what
+ * is. The two mistakes are not equal: a false rejection costs a prefetch and the
+ * track still plays from its origin, while a false acceptance breaks the track
+ * until the cache is cleared by hand.
+ *
+ * Mirrored rule for rule by `MediaResponseCheck.swift` on iOS.
+ */
+internal object MediaResponseCheck {
+
+  /**
+   * Why a response was refused. Each case carries what was judged so a caller's
+   * message names the response rather than just the verdict.
+   */
+  sealed interface Rejection {
+    /** The declared type is a markup or JSON document, which no audio container is. */
+    data class MarkupContentType(val contentType: String) : Rejection
+
+    /**
+     * The declared type is text of some other kind and the body carries no
+     * recognised container signature. `text/plain` is not refused on the label
+     * alone — media servers do mislabel audio — so the body is given the chance
+     * to prove itself.
+     */
+    data class TextWithoutMediaSignature(val contentType: String) : Rejection
+
+    /** No usable declared type, and the body begins as a markup or JSON document. */
+    data object MarkupBody : Rejection
+  }
+
+  /** Enough of a body to carry any container signature read below. */
+  const val HEAD_BYTES: Int = 64
+
+  /**
+   * Types that are documents, never audio. Narrow on purpose:
+   * `application/octet-stream` and `text/plain` are missing because servers
+   * serve real audio under both.
+   */
+  private val MARKUP_TYPES = setOf(
+    "text/html", "application/xhtml+xml",
+    "application/xml", "text/xml",
+    "application/json", "text/json",
+  )
+
+  private val SIGNATURE_PREFIXES = listOf(
+    "ID3", "fLaC", "OggS", "RIFF", "FORM", "caff", "#!AMR", "#EXTM3U",
+  )
+
+  /**
+   * The verdict for a response, or null to accept it.
+   *
+   * [head] is the first bytes of the body — [HEAD_BYTES] is plenty for every
+   * signature below. [headIsStartOfResource] is false when the request carried a
+   * range, and then only the declared type is judged: a body that begins part
+   * way into a file says nothing about the file's first bytes.
+   */
+  fun rejection(
+    contentType: String?,
+    head: ByteArray,
+    headIsStartOfResource: Boolean
+  ): Rejection? {
+    val declared = normalised(contentType)
+    if (declared != null && declared in MARKUP_TYPES) {
+      return Rejection.MarkupContentType(declared)
+    }
+    if (!headIsStartOfResource) return null
+    val body = droppingByteOrderMark(head)
+    if (declared != null && declared.startsWith("text/")) {
+      return if (hasMediaSignature(body)) null else Rejection.TextWithoutMediaSignature(declared)
+    }
+    return if (beginsAsMarkup(body)) Rejection.MarkupBody else null
+  }
+
+  /**
+   * Lowercased type with any `; charset=…` parameter and surrounding space
+   * removed. Null for a missing or empty header.
+   */
+  private fun normalised(contentType: String?): String? {
+    if (contentType.isNullOrEmpty()) return null
+    return contentType.substringBefore(';').trim().lowercase().ifEmpty { null }
+  }
+
+  /**
+   * Drop a byte-order mark so the checks below read the first real byte. A
+   * UTF-16 mark matters twice over: `FF FE` also satisfies the MPEG frame sync
+   * pattern, so a UTF-16 document would otherwise read as audio.
+   */
+  private fun droppingByteOrderMark(head: ByteArray): ByteArray {
+    if (head.size >= 3 &&
+      head[0] == 0xEF.toByte() && head[1] == 0xBB.toByte() && head[2] == 0xBF.toByte()
+    ) {
+      return head.copyOfRange(3, head.size)
+    }
+    if (head.size >= 2 && (
+        (head[0] == 0xFF.toByte() && head[1] == 0xFE.toByte()) ||
+          (head[0] == 0xFE.toByte() && head[1] == 0xFF.toByte())
+        )
+    ) {
+      return head.copyOfRange(2, head.size)
+    }
+    return head
+  }
+
+  /**
+   * Whether the body opens with the magic bytes of a container either platform
+   * plays, or with an HLS playlist's own first line.
+   */
+  private fun hasMediaSignature(body: ByteArray): Boolean {
+    if (body.isEmpty()) return false
+    // MPEG audio frame sync: eleven set bits across the first two bytes. ADTS
+    // AAC shares it.
+    if (body.size >= 2 &&
+      body[0] == 0xFF.toByte() &&
+      (body[1].toInt() and 0xE0) == 0xE0
+    ) {
+      return true
+    }
+    if (SIGNATURE_PREFIXES.any { startsWith(body, it, 0) }) return true
+    // ISO base media (MP4 / M4A / ALAC): a box length, then the type.
+    if (body.size >= 8 && startsWith(body, "ftyp", 4)) return true
+    return false
+  }
+
+  /**
+   * Whether the body opens as an XML / HTML document or a JSON value. No
+   * container above begins with either character.
+   */
+  private fun beginsAsMarkup(body: ByteArray): Boolean {
+    val first = body.firstOrNull { !isAsciiSpace(it) } ?: return false
+    return first == '<'.code.toByte() || first == '{'.code.toByte()
+  }
+
+  private fun isAsciiSpace(b: Byte): Boolean =
+    b == 0x20.toByte() || b == 0x09.toByte() || b == 0x0A.toByte() || b == 0x0D.toByte()
+
+  private fun startsWith(body: ByteArray, ascii: String, at: Int): Boolean {
+    if (body.size < at + ascii.length) return false
+    for (i in ascii.indices) {
+      if (body[at + i] != ascii[i].code.toByte()) return false
+    }
+    return true
+  }
+}