react-native-queue-player 2.0.0 → 2.0.1

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

@@ -115,7 +115,15 @@ class LookaheadCache(
    * surfacing a load error.
    */
   fun wrapDataSourceFactory(upstream: DataSource.Factory): DataSource.Factory {
-    val cached = cacheDataSourceFactory(upstream)
+    // 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.

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

@@ -516,7 +516,7 @@ 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)

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

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/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,