react-native-queue-player 1.1.2 → 2.0.0

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,24 @@ 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 {
+    val cached = cacheDataSourceFactory(upstream)
+    // 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 +162,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 +183,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 +225,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 +261,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 +275,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 +368,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 +391,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
@@ -492,27 +523,28 @@ class LookaheadCacheWriter @VisibleForTesting internal constructor(
       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/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.