react-native-queue-player 2.0.0 → 2.0.1

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

@@ -840,6 +840,38 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
    *  initiation so the retry-then-fail can fire a fresh error. */
   private var lastErrorKey: Pair<Int, PlaybackErrorCode>? = null
 
+  /**
+   * Positions whose playback error has been reported to the consumer and not
+   * recovered since. Empty when nothing is outstanding, and `-1` is never a
+   * member — a failure carrying no track records nothing, which is what keeps
+   * `currentTrackIndex in this` from reading as stopped while no track is
+   * seated.
+   *
+   * A set, not one position: under crossfade the standby leg prerolls the next
+   * track, so a broken one is reported while the leading track still plays and
+   * both are outstanding at once. Holding only the latest would hand the
+   * listener the standby's failure a second time when the engine seats it.
+   * The queue is stopped when `currentTrackIndex` is a member.
+   *
+   * Written only where [handlePlayerError] hands an `onError` out, so it names
+   * a track the consumer has been told about and nothing has recovered.
+   * [retryFailedItem] and every skip drop the entry for the position they
+   * attempt; a track change keeps only the announced position's; `setQueue`,
+   * `clearQueue`, `destroy` and `shuffleQueue` empty it, and `addToQueue`,
+   * `removeFromQueue` and `moveInQueue` keep only the current track's, carried
+   * to its new index. `onCrossfadeCancel` deliberately keeps the set: it
+   * returns to the track already playing rather than announcing a new one, and
+   * the prerolled track is still queued and still broken. Deliberately NOT a
+   * PLAYING emit: a source the player keeps re-attempting flips to playing
+   * between attempts, so clearing there would reopen a track's report.
+   *
+   * Separate from [lastErrorKey] even though both name a failing track: that
+   * one exists to dedup repeat reports and is cleared whenever a repeat would
+   * be wanted again, which is not the same question as whether the queue is
+   * still stopped. Mirrors the iOS `reportedFailureQueueItemIds` set.
+   */
+  private val reportedFailureIndices = mutableSetOf<Int>()
+
   /** Auto-retry counter per queue position, keyed on
    *  `currentTrackIndex` (lib-internal authoritative position; never
    *  derived from consumer fields). Decremented on each
@@ -1369,6 +1401,7 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
     pendingStateChangeReason = null
     pendingTrackChangeReason = null
     lastErrorKey = null
+    reportedFailureIndices.clear()
     cancelPendingRetry()
     retryAttemptsRemaining.clear()
     if (current === this) current = null
@@ -1675,6 +1708,7 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
     // last item must not suppress an identical coded error on the
     // new queue's first item.
     lastErrorKey = null
+    reportedFailureIndices.clear()
     cancelPendingRetry()
     // Reset auto-retry counters: new queue → new budget per index.
     val attempts = effectiveAutoRetries()
@@ -1783,6 +1817,11 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
     val ctx = boundContext ?: return -1
 
     val at = QueueMutationArithmetic.clampInsertBefore(insertBefore, tracks.size)
+    // A mutation renumbers positions, so every recorded index but the current
+    // track's is stale afterwards. The one that matters is the stop on the
+    // track being heard: it follows the index through the mutation, and the
+    // rest go rather than being carried onto whatever now sits at their number.
+    val wasStoppedOnCurrent = currentTrackIndex in reportedFailureIndices
     this.tracks = tracks.toMutableList().apply { addAll(at, newTracks) }
     this.currentTrackIndex = QueueMutationArithmetic.currentIndexAfterAdd(
       currentIndex = currentTrackIndex,
@@ -1809,6 +1848,8 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
     for (newIdx in at until at + shift) {
       retryAttemptsRemaining[newIdx] = attempts
     }
+    reportedFailureIndices.clear()
+    if (wasStoppedOnCurrent) reportedFailureIndices.add(currentTrackIndex)
     val items = MediaItemBuilder.buildMediaItems(ctx, newTracks, lookaheadCache, config.placeholderArtworkUri)
     serviceBinder?.engine?.addMediaItems(items, insertBefore = at)
     // Diverges from iOS: add-into-empty-queue on iOS leaves the
@@ -1879,6 +1920,11 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
       newTracks.removeAt(i)
     }
     this.tracks = newTracks
+    // A mutation renumbers positions, so every recorded index but the current
+    // track's is stale afterwards. The one that matters is the stop on the
+    // track being heard: it follows the index through the mutation, and the
+    // rest go rather than being carried onto whatever now sits at their number.
+    val wasStoppedOnCurrent = currentTrackIndex in reportedFailureIndices
     this.currentTrackIndex = QueueMutationArithmetic.currentIndexAfterRemove(
       currentIndex = oldCur,
       sanitisedIndices = sanitised,
@@ -1921,6 +1967,8 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
     val attempts = effectiveAutoRetries()
     retryAttemptsRemaining.clear()
     for (i in this.tracks.indices) retryAttemptsRemaining[i] = attempts
+    reportedFailureIndices.clear()
+    if (wasStoppedOnCurrent) reportedFailureIndices.add(currentTrackIndex)
     // Mirror the wake-mode hook on `setQueueInternal` /
     // `addToQueueInternal`: removing the last remote URL out of a
     // mixed queue must downgrade to LOCAL so the WiFi wake lock
@@ -1978,6 +2026,11 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
     mutable.add(to, moved)
     this.tracks = mutable
 
+    // A mutation renumbers positions, so every recorded index but the current
+    // track's is stale afterwards. The one that matters is the stop on the
+    // track being heard: it follows the index through the mutation, and the
+    // rest go rather than being carried onto whatever now sits at their number.
+    val wasStoppedOnCurrent = currentTrackIndex in reportedFailureIndices
     this.currentTrackIndex = QueueMutationArithmetic.currentIndexAfterMove(
       currentIndex = currentTrackIndex,
       fromIndex = from,
@@ -1995,6 +2048,8 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
     val attempts = effectiveAutoRetries()
     retryAttemptsRemaining.clear()
     for (i in this.tracks.indices) retryAttemptsRemaining[i] = attempts
+    reportedFailureIndices.clear()
+    if (wasStoppedOnCurrent) reportedFailureIndices.add(currentTrackIndex)
     rescheduleLookahead()
     recomputeCapabilities()
     // Reached only past the invalid / `from == to` / pinned-current
@@ -2033,6 +2088,7 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
     // Reset error-dedup so a subsequent queue's identical-coded error
     // isn't suppressed by a stale entry from the cleared queue.
     lastErrorKey = null
+    reportedFailureIndices.clear()
     cancelPendingRetry()
     retryAttemptsRemaining.clear()
     tracks = emptyList()
@@ -2092,12 +2148,30 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
         // error, hand the track back the allowance the consumer configured and
         // re-prepare. Not a hard-coded 1: a consumer who set `autoRetries: 0`
         // asked for none. Mirrors iOS `play()` stuck-recovery.
-        if (lastReportedState == PlayerState.ERROR &&
-            currentTrackIndex >= 0 &&
-            (retryAttemptsRemaining[currentTrackIndex] ?: 0) == 0) {
+        if (currentTrackIndex >= 0 && currentTrackIndex in reportedFailureIndices) {
           retryAttemptsRemaining[currentTrackIndex] = effectiveAutoRetries()
           lastErrorKey = null
-          player?.prepare()
+          // `retryFailedItem`, not a bare `prepare()`: a bare prepare re-uses
+          // the wedged DataSource this exists to discard. It removes and re-adds
+          // the item, which rebuilds the source from the MediaSource.Factory.
+          retryFailedItem(currentTrackIndex)
+        } else if (currentTrackIndex >= 0 &&
+          player?.playbackState == Player.STATE_IDLE &&
+          (player?.mediaItemCount ?: 0) > 0
+        ) {
+          // With no current track there is no position to re-seat, which the
+          // index guard above covers; the branch below refuses to start
+          // anything in that state at all.
+          // A failure leaves ExoPlayer in STATE_IDLE, and a skip off the failed
+          // track seeks without re-preparing — so `play()` would set
+          // `playWhenReady` on a player that never leaves IDLE and nothing would
+          // be heard. `retryFailedItem`, not a bare `prepare()`: on a same-index
+          // skip the item is the one that failed, and a bare prepare re-uses the
+          // DataSource that wedged. The timeline has to hold items for prepare to
+          // reach anything — between `clearQueue` and the next `setMediaItems`
+          // it is empty, and preparing there lands in STATE_ENDED, which the
+          // line below reads as a finished queue.
+          retryFailedItem(currentTrackIndex)
         }
         // At the end of the queue there is nothing to play: ExoPlayer stays
         // STATE_ENDED through play(), and a playWhenReady left set would
@@ -2105,6 +2179,12 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
         // seek or a fresh queue leaves this state; play() alone restarts
         // nothing — the same contract as iOS.
         if (player?.playbackState == Player.STATE_ENDED && tracks.isNotEmpty()) return@onMain
+        // Nothing is seated: an add into an empty queue primes the player and
+        // deliberately leaves the current index at -1, so starting here would
+        // play position 0 while every read still answers for no track. The
+        // consumer seats one — `skipToIndex(0)` — and plays. iOS reaches the
+        // same outcome by leaving its queue player empty until then.
+        if (currentTrackIndex < 0) return@onMain
         // Stash USER on the pending-reason channel so the
         // subsequent Player.Listener fire attributes the transition
         // correctly.
@@ -2140,6 +2220,8 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
         lastErrorKey = null
         pendingStateChangeReason = StateChangeReason.USER
         wantsToPlay = true
+        // Drops this track's report on its way through, before its own
+        // current-track bail, so a retry always clears what it attempts.
         retryFailedItem(currentTrackIndex)
         recomputeBufferState()
       }
@@ -2374,6 +2456,11 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
     val p = player ?: return
     if (target < 0 || target >= tracks.size) return
     currentTrackIndex = target
+    // Seating a position is an attempt at it, so the report against it no
+    // longer describes what is about to play. Cleared here rather than left to
+    // the media-item transition, which does not fire for a skip that seats the
+    // track already selected. Mirrors iOS `applyNewCurrentIndex`.
+    reportedFailureIndices.remove(target)
     pendingTrackChangeReason = TrackChangeReason.USER_SKIP_TO_INDEX
     // Guard against IllegalSeekPositionException: `seekTo(index, 0L)`
     // throws when `index` is outside `mediaItemCount`. When the lib
@@ -2401,6 +2488,7 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
     val p = player ?: return
     val next = computeNextIndex() ?: return
     currentTrackIndex = next
+    reportedFailureIndices.remove(next)
     pendingTrackChangeReason = TrackChangeReason.USER_SKIP_NEXT
     if (next < p.mediaItemCount) {
       serviceBinder?.engine?.seekTo(next, 0L)
@@ -2439,6 +2527,7 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
       is QueueSkipArithmetic.SkipToPreviousAction.Previous -> {
         val prev = action.index
         currentTrackIndex = prev
+        reportedFailureIndices.remove(prev)
         pendingTrackChangeReason = TrackChangeReason.USER_SKIP_PREVIOUS
         if (prev < p.mediaItemCount) {
           serviceBinder?.engine?.seekTo(prev, 0L)
@@ -2453,6 +2542,7 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
         // untouched (stashing a reason no transition consumes would leak
         // into the next real skip).
         if (currentTrackIndex in 0 until p.mediaItemCount) {
+          reportedFailureIndices.remove(currentTrackIndex)
           serviceBinder?.engine?.seekTo(currentTrackIndex, 0L)
         }
       }
@@ -3084,6 +3174,11 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
     val attempts = effectiveAutoRetries()
     retryAttemptsRemaining.clear()
     for (i in newTracks.indices) retryAttemptsRemaining[i] = attempts
+    // The permutation decides what lands at position 0, so the track the queue
+    // stopped on is not the one the index now names. The stop is dropped with
+    // the retry budget rather than carried onto whichever track was moved to
+    // the front.
+    reportedFailureIndices.clear()
 
     val items = MediaItemBuilder.buildMediaItems(ctx, newTracks, lookaheadCache, config.placeholderArtworkUri)
     serviceBinder?.engine?.setMediaItems(items, startIndex = 0, startPositionMs = 0L)
@@ -3961,6 +4056,7 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
     if (incomingIndex !in tracks.indices) return
     currentTrackIndex = incomingIndex
     lastErrorKey = null
+    reportedFailureIndices.retainAll(setOf(incomingIndex))
     val track = tracks[incomingIndex]
     currentTrackSource = classifyTrackSource(track.url, ::servedFromCache)
     crossfadeFadeStartEmittedIdx = incomingIndex
@@ -4008,6 +4104,11 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
     if (revertedIndex !in tracks.indices) return
     currentTrackIndex = revertedIndex
     lastErrorKey = null
+    // The reported set is left alone. A cancel goes back to the track that was
+    // already playing rather than announcing a new one, and the track the
+    // standby leg was prerolling is still in the queue and still broken — the
+    // engine seats it next. Dropping its report here would hand the listener
+    // the same failure a second time when it does.
     crossfadeFadeStartEmittedIdx = null
     val track = tracks[revertedIndex]
     currentTrackSource = classifyTrackSource(track.url, ::servedFromCache)
@@ -4189,6 +4290,10 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
     // suppressed even though they're independent failures. Mirrors
     // iOS reset in `handleCurrentItemDidChange`.
     lastErrorKey = null
+    // A report against some other track says nothing about the one now
+    // being announced, so it goes. A report against the track being
+    // announced stands — clearing it would leave nothing to hold on.
+    reportedFailureIndices.retainAll(setOf(currentTrackIndex))
     val track = if (currentTrackIndex in tracks.indices) tracks[currentTrackIndex] else null
     currentTrackSource = classifyTrackSource(track?.url, ::servedFromCache)
 
@@ -4389,6 +4494,26 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
     // An echo of a failure whose attempt has not run yet belongs to that
     // attempt, not to the consumer.
     if (idx >= 0 && idx == pendingRetryIndex) return
+    // Already reported and not yet recovered. Under crossfade the standby leg
+    // prerolls the next track, so a broken one is reported while the leading
+    // track still plays; the engine then seats it and it fails again as the
+    // current track. `lastErrorKey` cannot carry that on its own — the track
+    // change between the two clears it — so one thing asked for would report
+    // twice. The state still has to be announced when this becomes the track
+    // the listener is on, because the report was raised before it was.
+    if (idx >= 0 && idx in reportedFailureIndices) {
+      if (idx == currentTrackIndex) emitState(PlayerState.ERROR, StateChangeReason.ERROR)
+      return
+    }
+    // Once the queue has stopped on the current track, the tracks behind it go
+    // quiet: the listener has been told the track they are on failed, and one
+    // error per unplayable track in the run is noise they cannot act on. While
+    // playback is healthy this does not fire, so a standby leg failing to
+    // preroll under crossfade is still surfaced. Mirrors iOS.
+    if (idx >= 0 && idx != currentTrackIndex &&
+        currentTrackIndex in reportedFailureIndices) {
+      return
+    }
     if (lastErrorKey == key) return
     lastErrorKey = key
     // Auto-retry path: transient errors with retries left
@@ -4398,9 +4523,8 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
     // Only the track being played is retried. A standby leg's preroll failing
     // is the *next* track failing to load early, and the cancel that precedes
     // the report reverts `currentTrackIndex` to the leading track, so an
-    // attempt scheduled for it could never run. Surfacing it instead is both
-    // honest and harmless: when that track becomes current it is loaded fresh
-    // and gets its own automatic attempt then.
+    // attempt scheduled for it could never run. It is surfaced instead, and
+    // gets its own automatic attempt when it becomes current and loads fresh.
     if (idx >= 0 &&
         idx == currentTrackIndex &&
         PlaybackErrorMapping.isTransient(mapped) &&
@@ -4428,6 +4552,11 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
     val err = PlaybackErrorMapping.buildPlaybackError(
       error, mapped, queueItemId = "", url = failedUrl,
     )
+    // The consumer now knows this track failed, so the queue holds on it until
+    // something asks for playback again. Recorded for whichever track failed,
+    // current or not: that is what keeps the standby leg's report from being
+    // handed to the listener a second time when the engine seats it.
+    if (idx >= 0) reportedFailureIndices.add(idx)
     errorListeners.forEach { it(err) }
     // The state is the current track's. A standby leg's preroll failing is
     // reported above and leaves the leading leg playing; announcing ERROR for
@@ -4477,6 +4606,8 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
       pendingRetryIndex = -1
       pendingRetryRunnable = null
     }
+    // The attempt re-seats the item, so the queue is no longer stopped on it.
+    reportedFailureIndices.remove(atIndex)
     // The failed item must still be the current one; a skip or a queue mutation
     // since the failure makes the retry moot. Checked before the fade is
     // settled, because settling is an audible cut and a retry that is about to
@@ -4492,7 +4623,17 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
     val p = player ?: return
     val current = p.currentMediaItem
     if (current != null) {
-      val idx = p.currentMediaItemIndex
+      // Act on the index that was approved above, not on whatever the engine
+      // happens to be pointing at. They agree in every path found so far — the
+      // standby leg carries the whole queue so its index is in the queue's own
+      // space, and the settle above puts the leading leg on the current track —
+      // but nothing enforces it, and a disagreement means the engine has not
+      // caught up with a mutation. Rebuilding at either index would then be
+      // wrong: the track being heard gets torn down and restarted at another
+      // track's position, because `resumeMs` below is that track's. Refuse
+      // instead; whatever asks next attempts it again.
+      if (atIndex >= p.mediaItemCount || p.currentMediaItemIndex != atIndex) return
+      val idx = atIndex
       val resumeMs = p.currentPosition.coerceAtLeast(0L)
       // Force a FRESH MediaSource/DataSource for the failed item without
       // collapsing the rest of the timeline. `replaceMediaItem(idx, current)`

package/android/src/test/java/com/margelo/nitro/queueplayer/LookaheadCacheTest.kt

@@ -1,11 +1,16 @@
 package com.margelo.nitro.queueplayer
 
+import android.net.Uri
 import androidx.media3.common.util.UnstableApi
+import androidx.media3.datasource.DataSource
+import androidx.media3.datasource.DataSpec
 import androidx.media3.datasource.DefaultHttpDataSource
+import androidx.media3.datasource.TransferListener
 import androidx.media3.datasource.cache.CacheDataSource
 import androidx.test.core.app.ApplicationProvider
 import org.junit.After
 import org.junit.Assert.assertEquals
+import org.junit.Assert.assertFalse
 import org.junit.Assert.assertNotNull
 import org.junit.Assert.assertTrue
 import org.junit.Before
@@ -79,6 +84,61 @@ class LookaheadCacheTest {
     )
   }
 
+  /**
+   * Only the prefetcher fills the cache. The playback factory is built with a
+   * null cache-write sink, which is what Media3 reads as `cacheIsReadOnly`, so
+   * a body pulled all the way through it leaves nothing on disk.
+   */
+  @Test
+  fun `a body read through the playback factory is not written to the cache`() {
+    val body = ByteArray(4096) { it.toByte() }
+    val url = "https://example.com/playback-read.mp3"
+    val source = cache.wrapDataSourceFactory(FixedBodyDataSource.Factory(body))
+      .createDataSource()
+
+    source.open(DataSpec.Builder().setUri(url).setKey(url).build())
+    val buffer = ByteArray(1024)
+    var total = 0
+    while (true) {
+      val read = source.read(buffer, 0, buffer.size)
+      if (read == -1) break
+      total += read
+    }
+    source.close()
+
+    assertEquals("the whole body reaches the caller", body.size, total)
+    assertEquals("nothing is written to disk", 0L, cache.currentSizeBytes())
+    assertFalse("and the url is not held as cached", cache.isFullyCached(url))
+  }
+
+  /** Serves a fixed body for any [DataSpec], honouring its position. */
+  private class FixedBodyDataSource(private val body: ByteArray) : DataSource {
+    class Factory(private val body: ByteArray) : DataSource.Factory {
+      override fun createDataSource(): DataSource = FixedBodyDataSource(body)
+    }
+
+    private var uri: Uri? = null
+    private var position = 0
+
+    override fun open(dataSpec: DataSpec): Long {
+      uri = dataSpec.uri
+      position = dataSpec.position.toInt()
+      return (body.size - position).toLong()
+    }
+
+    override fun read(buffer: ByteArray, offset: Int, length: Int): Int {
+      if (position >= body.size) return -1
+      val take = minOf(length, body.size - position)
+      body.copyInto(buffer, offset, position, position + take)
+      position += take
+      return take
+    }
+
+    override fun getUri(): Uri? = uri
+    override fun close() {}
+    override fun addTransferListener(transferListener: TransferListener) {}
+  }
+
   /**
    * Disabled means every read goes to the origin and nothing is written,
    * whatever the disk holds — the wrapper hands out the bare upstream source.

package/android/src/test/java/com/margelo/nitro/queueplayer/MediaResponseCheckTest.kt

@@ -0,0 +1,163 @@
+package com.margelo.nitro.queueplayer
+
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertNull
+import org.junit.Test
+
+/**
+ * What the cache will and will not believe is a track, judged from a response's
+ * declared type and the first bytes of its body. Mirrors iOS's
+ * `MediaResponseCheckTests` case for case so the two platforms refuse and
+ * accept the same responses.
+ */
+class MediaResponseCheckTest {
+
+  private val xmlEnvelope =
+    """<api-response status="failed"><error code="70"/></api-response>""".toByteArray()
+  private val mp3 = byteArrayOf(0x49, 0x44, 0x33, 0x04, 0, 0, 0, 0)
+
+  private fun rejection(
+    contentType: String?,
+    body: ByteArray,
+    whole: Boolean = true
+  ): MediaResponseCheck.Rejection? =
+    MediaResponseCheck.rejection(contentType, body, headIsStartOfResource = whole)
+
+  @Test
+  fun markupAndJsonContentTypesAreRefused() {
+    for (type in listOf(
+      "application/xml", "text/xml", "text/html",
+      "application/xhtml+xml", "application/json", "text/json",
+    )) {
+      assertEquals(
+        "$type is a document type",
+        MediaResponseCheck.Rejection.MarkupContentType(type),
+        rejection(type, xmlEnvelope)
+      )
+    }
+  }
+
+  @Test
+  fun theDeclaredTypeIsReadWithoutItsParameters() {
+    assertEquals(
+      MediaResponseCheck.Rejection.MarkupContentType("application/xml"),
+      rejection("application/xml; charset=utf-8", xmlEnvelope)
+    )
+    assertEquals(
+      MediaResponseCheck.Rejection.MarkupContentType("application/xml"),
+      rejection("APPLICATION/XML", xmlEnvelope)
+    )
+  }
+
+  @Test
+  fun aDeclaredDocumentIsRefusedOnAPartialBodyToo() {
+    assertEquals(
+      MediaResponseCheck.Rejection.MarkupContentType("application/xml"),
+      rejection("application/xml", byteArrayOf(0x3C, 0x00), whole = false)
+    )
+  }
+
+  @Test
+  fun aPartialBodyIsNotJudgedByItsLeadingBytes() {
+    // The same markup, under a type that is not itself a document, so only the
+    // leading-byte rule can decide: refused as a whole resource, accepted as a
+    // range, which is what separates the two inputs.
+    val markup = "<api-response/>".toByteArray()
+    assertEquals(
+      MediaResponseCheck.Rejection.MarkupBody,
+      rejection("application/octet-stream", markup)
+    )
+    assertNull(
+      "a body that begins part way into a file says nothing about its first bytes",
+      rejection("application/octet-stream", markup, whole = false)
+    )
+  }
+
+  @Test
+  fun textWithoutAContainerSignatureIsRefused() {
+    assertEquals(
+      MediaResponseCheck.Rejection.TextWithoutMediaSignature("text/plain"),
+      rejection("text/plain", "not found".toByteArray())
+    )
+  }
+
+  @Test
+  fun textCarryingAContainerSignatureIsAccepted() {
+    assertNull(
+      "a server mislabelling audio as text does not make it a document",
+      rejection("text/plain", mp3)
+    )
+  }
+
+  @Test
+  fun aPlaylistDeclaredAsTextIsAccepted() {
+    assertNull(rejection("text/plain", "#EXTM3U\n#EXT-X-VERSION:3".toByteArray()))
+  }
+
+  @Test
+  fun aMarkupBodyIsRefusedWhenNothingUsableIsDeclared() {
+    assertEquals(MediaResponseCheck.Rejection.MarkupBody, rejection(null, xmlEnvelope))
+    assertEquals(
+      MediaResponseCheck.Rejection.MarkupBody,
+      rejection("application/octet-stream", xmlEnvelope)
+    )
+    assertEquals(
+      MediaResponseCheck.Rejection.MarkupBody,
+      rejection(null, "<!DOCTYPE html><html>".toByteArray())
+    )
+    assertEquals(
+      MediaResponseCheck.Rejection.MarkupBody,
+      rejection(null, """{"error":"not found"}""".toByteArray())
+    )
+  }
+
+  @Test
+  fun leadingSpaceAndAByteOrderMarkDoNotHideAMarkupBody() {
+    assertEquals(
+      MediaResponseCheck.Rejection.MarkupBody,
+      rejection(null, "\n  <?xml version=\"1.0\"?>".toByteArray())
+    )
+    assertEquals(
+      MediaResponseCheck.Rejection.MarkupBody,
+      rejection(null, byteArrayOf(0xEF.toByte(), 0xBB.toByte(), 0xBF.toByte()) + "<error/>".toByteArray())
+    )
+    // `FF FE` also satisfies the MPEG frame sync, so a UTF-16 document would
+    // read as audio if the mark were not dropped first.
+    assertEquals(
+      MediaResponseCheck.Rejection.MarkupBody,
+      rejection(null, byteArrayOf(0xFF.toByte(), 0xFE.toByte()) + "<e/>".toByteArray())
+    )
+  }
+
+  @Test
+  fun recognisedContainersAreAccepted() {
+    val bodies = mapOf(
+      "ID3" to byteArrayOf(0x49, 0x44, 0x33, 0x04, 0, 0, 0, 0),
+      "MPEG frame sync" to byteArrayOf(0xFF.toByte(), 0xFB.toByte(), 0x90.toByte(), 0, 0, 0, 0, 0),
+      "ADTS AAC" to byteArrayOf(0xFF.toByte(), 0xF1.toByte(), 0x50, 0x80.toByte(), 0, 0, 0, 0),
+      "FLAC" to byteArrayOf(0x66, 0x4C, 0x61, 0x43, 0, 0, 0, 0),
+      "Ogg" to byteArrayOf(0x4F, 0x67, 0x67, 0x53, 0, 0, 0, 0),
+      "WAV" to byteArrayOf(0x52, 0x49, 0x46, 0x46, 0, 0, 0, 0),
+      "AIFF" to byteArrayOf(0x46, 0x4F, 0x52, 0x4D, 0, 0, 0, 0),
+      "CAF" to byteArrayOf(0x63, 0x61, 0x66, 0x66, 0, 0, 0, 0),
+      "MP4" to byteArrayOf(0, 0, 0, 0x20, 0x66, 0x74, 0x79, 0x70),
+    )
+    for ((name, bytes) in bodies) {
+      assertNull("$name is media", rejection("text/plain", bytes))
+      assertNull("$name is media", rejection(null, bytes))
+    }
+  }
+
+  @Test
+  fun anUndeclaredOrOpaqueBinaryBodyIsAccepted() {
+    val binary = byteArrayOf(0x00, 0x01, 0x02, 0x03, 0x04)
+    assertNull("an unrecognised container is not a document", rejection(null, binary))
+    assertNull(rejection("application/octet-stream", binary))
+    assertNull(rejection("audio/mpeg", binary))
+  }
+
+  @Test
+  fun anEmptyBodyIsNotJudged() {
+    assertNull(rejection(null, ByteArray(0)))
+  }
+}