react-native-audio-browser 0.1.0 → 0.2.0-next.1

package/android/src/main/java/com/audiobrowser/player/RetryLoadErrorHandlingPolicy.kt

@@ -1,10 +1,14 @@
 package com.audiobrowser.player
 
 import androidx.media3.common.C
-import androidx.media3.common.PlaybackException
+import androidx.media3.common.ParserException
+import androidx.media3.datasource.DataSourceException
 import androidx.media3.datasource.HttpDataSource
 import androidx.media3.exoplayer.upstream.DefaultLoadErrorHandlingPolicy
 import androidx.media3.exoplayer.upstream.LoadErrorHandlingPolicy
+import androidx.media3.exoplayer.upstream.Loader
+import java.io.FileNotFoundException
+import java.io.IOException
 import kotlin.math.min
 import kotlin.math.pow
 import timber.log.Timber
@@ -16,19 +20,37 @@ import timber.log.Timber
  * will use a shorter retry delay and the network restoration callback can trigger an immediate
  * retry when connectivity is restored.
  *
+ * Two duration budgets apply, chosen by whether the current load has ever produced audio
+ * ([hasPlayed]): a short first-connect budget — a stream that fails before ever playing is usually
+ * dead, and the listener is actively waiting for a verdict — and the full recovery budget for a
+ * stream that played and then dropped (tunnels, handovers, encoder restarts). The short budget
+ * counts only online time, so a station tapped in a tunnel still gets its online seconds once
+ * connectivity returns. Both budgets are enforced here at the policy level, never via ExoPlayer's
+ * [LoadErrorHandlingPolicy.LoadErrorInfo.errorCount] — that counts per *loadable* (an HLS stream
+ * has playlist and segment loadables, each with its own count), so it cannot express a per-load
+ * promise.
+ *
  * @param maxRetries Maximum number of retries, or null for infinite retries
- * @param maxRetryDurationMs Maximum duration to keep retrying before giving up, or null for default (2 minutes)
+ * @param maxRetryDurationMs Maximum duration to keep retrying before giving up, or null for default
+ *   (2 minutes)
+ * @param firstConnectMaxRetryDurationMs Maximum duration to keep retrying a load that has never
+ *   produced audio, while online, or null for default (12 seconds)
  * @param shouldRetry Optional callback to check if retry should proceed (e.g., check playWhenReady)
  * @param isOnline Optional callback to check current network state
- * @param onRetryPending Optional callback invoked when a retry is pending (for network restoration
- *   acceleration)
+ * @param hasPlayed Optional callback: whether the current load has produced audio. Must be safe to
+ *   call from ExoPlayer's loader thread (e.g. backed by a volatile cache).
+ * @param onRetryPending Optional callback invoked when a retry is pending, with the load error
+ *   being retried (for surfacing it while the retry runs, and for network restoration
+ *   acceleration). Invoked on ExoPlayer's loader thread.
  */
 class RetryLoadErrorHandlingPolicy(
   private val maxRetries: Int? = null,
   maxRetryDurationMs: Long? = null,
+  firstConnectMaxRetryDurationMs: Long? = null,
   private val shouldRetry: () -> Boolean = { true },
   private val isOnline: () -> Boolean = { true },
-  private val onRetryPending: ((isNetworkError: Boolean) -> Unit)? = null,
+  private val hasPlayed: () -> Boolean = { false },
+  private val onRetryPending: ((exception: IOException, isNetworkError: Boolean) -> Unit)? = null,
 ) : DefaultLoadErrorHandlingPolicy() {
 
   companion object {
@@ -42,6 +64,8 @@ class RetryLoadErrorHandlingPolicy(
     private const val OFFLINE_RETRY_DELAY_MS = 1000L
     // Default maximum duration to keep retrying before giving up (in milliseconds).
     private const val DEFAULT_MAX_RETRY_DURATION_MS = 120_000L // 2 minutes
+    // Default maximum duration for a load that has never produced audio, while online.
+    private const val DEFAULT_FIRST_CONNECT_MAX_RETRY_DURATION_MS = 12_000L
 
     // HTTP status codes that are worth retrying
     private val RETRYABLE_HTTP_STATUS_CODES =
@@ -59,13 +83,40 @@ class RetryLoadErrorHandlingPolicy(
   // This prevents surprising playback resumption after long periods offline.
   private val maxRetryDurationMs: Long = maxRetryDurationMs ?: DEFAULT_MAX_RETRY_DURATION_MS
 
+  private val firstConnectMaxRetryDurationMs: Long =
+    firstConnectMaxRetryDurationMs ?: DEFAULT_FIRST_CONNECT_MAX_RETRY_DURATION_MS
+
   // Track when we started retrying to enforce max duration
-  @Volatile
-  private var firstErrorTime: Long? = null
+  @Volatile private var firstErrorTime: Long? = null
+
+  // First error observed while online — the first-connect budget's clock. Never set while
+  // offline, and wiped by any offline observation, so an offline stretch cannot burn the short
+  // budget: the clock restarts at the next error observed online.
+  @Volatile private var firstOnlineErrorTime: Long? = null
 
   /** Resets the retry timer. Call when track changes. */
   fun reset() {
     firstErrorTime = null
+    firstOnlineErrorTime = null
+  }
+
+  /**
+   * The name of the exhausted budget, or null while budget remains. The recovery duration bounds
+   * everything (including offline waits); the first-connect duration additionally bounds
+   * never-played loads, online only.
+   */
+  private fun exhaustedBudget(currentTime: Long): String? {
+    firstErrorTime?.let { start ->
+      if (currentTime - start >= maxRetryDurationMs) return "max retry duration ($maxRetryDurationMs ms)"
+    }
+    if (!hasPlayed() && isOnline()) {
+      firstOnlineErrorTime?.let { start ->
+        if (currentTime - start >= firstConnectMaxRetryDurationMs) {
+          return "first-connect retry duration ($firstConnectMaxRetryDurationMs ms)"
+        }
+      }
+    }
+    return null
   }
 
   /** Calculates exponential backoff delay: 1s -> 1.5s -> 2.3s -> 3.4s -> 5s (capped) */
@@ -76,22 +127,6 @@ class RetryLoadErrorHandlingPolicy(
     return min(exponentialDelay.toLong(), MAX_RETRY_DELAY_MS)
   }
 
-  /**
-   * Checks if an HTTP error is worth retrying based on status code. Only server errors (5xx) and
-   * specific client errors (408, 429) are retryable.
-   */
-  private fun isRetryableHttpError(exception: Throwable): Boolean {
-    // Check the exception chain for HttpDataSource.InvalidResponseCodeException
-    var current: Throwable? = exception
-    while (current != null) {
-      if (current is HttpDataSource.InvalidResponseCodeException) {
-        return current.responseCode in RETRYABLE_HTTP_STATUS_CODES
-      }
-      current = current.cause
-    }
-    return false
-  }
-
   override fun getRetryDelayMsFor(loadErrorInfo: LoadErrorHandlingPolicy.LoadErrorInfo): Long {
     val exception = loadErrorInfo.exception
     val errorCount = loadErrorInfo.errorCount
@@ -113,15 +148,20 @@ class RetryLoadErrorHandlingPolicy(
     if (firstErrorTime == null) {
       firstErrorTime = currentTime
     }
+    if (isOnline()) {
+      if (firstOnlineErrorTime == null) firstOnlineErrorTime = currentTime
+    } else {
+      // Seeing the device offline restarts the first-connect clock: a station that lost
+      // connectivity mid-budget gets its full online seconds again after restoration,
+      // instead of the offline gap counting against it.
+      firstOnlineErrorTime = null
+    }
 
-    // Check if we've been retrying too long (prevents surprising resumption after long offline)
-    val startTime = firstErrorTime
-    if (startTime != null) {
-      val elapsed = currentTime - startTime
-      if (elapsed >= maxRetryDurationMs) {
-        Timber.d("Max retry duration (${maxRetryDurationMs}ms) exceeded after ${elapsed}ms, giving up")
-        return C.TIME_UNSET
-      }
+    // Check if we've been retrying too long (prevents surprising resumption after long
+    // offline periods, and grants dead-on-arrival streams a fast verdict)
+    exhaustedBudget(currentTime)?.let { budget ->
+      Timber.d("$budget exceeded, giving up")
+      return C.TIME_UNSET
     }
 
     // Classify the error
@@ -148,40 +188,64 @@ class RetryLoadErrorHandlingPolicy(
       )
 
       // Notify that a retry is pending (for network restoration acceleration)
-      onRetryPending?.invoke(isNetworkError)
+      onRetryPending?.invoke(exception, isNetworkError)
 
       delay
     } else {
-      // For non-recoverable errors, use default behavior (no retry)
-      super.getRetryDelayMsFor(loadErrorInfo)
+      // Non-recoverable error: stop now. We can't delegate to super here —
+      // DefaultLoadErrorHandlingPolicy still schedules a backoff retry for some errors it doesn't
+      // consider fatal (e.g. a 404 InvalidResponseCodeException), which combined with our infinite
+      // getMinimumLoadableRetryCount would retry a dead URL until the max-retry-duration timeout.
+      C.TIME_UNSET
     }
   }
 
   /** Classification result for an error */
   private data class ErrorClassification(val isRecoverable: Boolean, val isNetworkError: Boolean)
 
-  /** Classifies whether an error is recoverable and whether it's network-related */
-  private fun classifyError(exception: Throwable): ErrorClassification {
-    return when {
-      exception is PlaybackException -> {
-        when (exception.errorCode) {
-          // Clearly transient network errors
-          PlaybackException.ERROR_CODE_IO_NETWORK_CONNECTION_FAILED,
-          PlaybackException.ERROR_CODE_IO_NETWORK_CONNECTION_TIMEOUT ->
-            ErrorClassification(isRecoverable = true, isNetworkError = true)
-          // HTTP errors - retry on server errors and specific client errors
-          PlaybackException.ERROR_CODE_IO_BAD_HTTP_STATUS -> {
-            val isRetryable = isRetryableHttpError(exception)
-            ErrorClassification(isRecoverable = isRetryable, isNetworkError = isRetryable)
-          }
-          else -> ErrorClassification(isRecoverable = false, isNetworkError = false)
+  /**
+   * Classifies whether an error is recoverable and whether it's network-related.
+   *
+   * Load errors are delivered as a raw [IOException] (e.g.
+   * [HttpDataSource.HttpDataSourceException], `UnknownHostException`, `SocketTimeoutException`) —
+   * never as a `PlaybackException`, which is only surfaced at the player level *after* retries are
+   * exhausted. So we classify by walking the IOException cause chain. This is essential: a plain
+   * Wi-Fi drop surfaces as a socket/DNS IOException, and unless we flag it as a network error the
+   * connectivity-restoration path can't fire an immediate retry, leaving playback stuck buffering
+   * until it returns.
+   */
+  private fun classifyError(exception: IOException): ErrorClassification {
+    val nonRecoverable = ErrorClassification(isRecoverable = false, isNetworkError = false)
+
+    var current: Throwable? = exception
+    while (current != null) {
+      when (current) {
+        // HTTP responses: only retry server errors (5xx) and specific client errors (408, 429).
+        // Other status codes (e.g. 403/404) will never succeed on retry.
+        is HttpDataSource.InvalidResponseCodeException -> {
+          val retryable = current.responseCode in RETRYABLE_HTTP_STATUS_CODES
+          return ErrorClassification(isRecoverable = retryable, isNetworkError = retryable)
         }
+        // Errors that retrying cannot fix — mirror DefaultLoadErrorHandlingPolicy's
+        // non-retryable set so we don't spin until the max-retry-duration timeout.
+        is HttpDataSource.CleartextNotPermittedException,
+        is ParserException,
+        is FileNotFoundException,
+        is Loader.UnexpectedLoaderException -> return nonRecoverable
       }
-      // HTTP errors outside PlaybackException wrapper
-      isRetryableHttpError(exception) ->
-        ErrorClassification(isRecoverable = true, isNetworkError = true)
-      else -> ErrorClassification(isRecoverable = false, isNetworkError = false)
+      current = current.cause
+    }
+
+    // A read at a position the source can no longer provide (e.g. behind a live window) won't
+    // recover via an in-place loader retry.
+    if (DataSourceException.isCausedByPositionOutOfRange(exception)) {
+      return nonRecoverable
     }
+
+    // Any other IOException is a transient network/transport failure (connection reset, DNS
+    // failure, socket timeout, network interface lost, ...): recoverable, and flagged as a network
+    // error so connectivity restoration can trigger an immediate retry.
+    return ErrorClassification(isRecoverable = true, isNetworkError = true)
   }
 
   override fun getMinimumLoadableRetryCount(dataType: Int): Int {

package/android/src/main/java/com/audiobrowser/player/SleepTimer.kt

@@ -7,7 +7,8 @@ import android.os.Looper
  * Manages a sleep timer that calls a completion callback after a specified duration.
  *
  * The timer stores the expiration time as a timestamp and uses a Handler to schedule the completion
- * callback. Supports both time-based and end-of-track modes.
+ * callback. Supports both time-based and end-of-track modes, plus an optional fade-out that starts
+ * `fadeDuration` seconds before the deadline so silence lands exactly when the timer completes.
  */
 open class SleepTimer {
   var time: Double? = null
@@ -17,6 +18,7 @@ open class SleepTimer {
     private set
 
   private var runnable: Runnable? = null
+  private var fadeRunnable: Runnable? = null
   private val handler = Handler(Looper.getMainLooper())
 
   val isRunning: Boolean
@@ -26,15 +28,27 @@ open class SleepTimer {
    * Sets a timer to complete after the specified number of seconds.
    *
    * @param seconds Number of seconds until the timer completes
+   * @param fadeDuration Seconds over which to fade out before completion; clamped to [seconds]
    */
-  fun sleepAfter(seconds: Double) {
+  fun sleepAfter(seconds: Double, fadeDuration: Double? = null) {
     stopTimer()
+    onFadeCancel()
     sleepWhenPlayedToEnd = false
 
     val runnable = Runnable { complete() }
     this.runnable = runnable
     handler.postDelayed(runnable, (seconds * 1000).toLong())
     time = System.currentTimeMillis() + (seconds * 1000)
+
+    if (fadeDuration != null && fadeDuration > 0) {
+      val fade = minOf(fadeDuration, seconds)
+      val fadeRunnable = Runnable {
+        this.fadeRunnable = null
+        onFadeStart(fade)
+      }
+      this.fadeRunnable = fadeRunnable
+      handler.postDelayed(fadeRunnable, ((seconds - fade) * 1000).toLong())
+    }
   }
 
   /**
@@ -43,6 +57,7 @@ open class SleepTimer {
    */
   fun sleepWhenPlayedToEnd() {
     stopTimer()
+    onFadeCancel()
     time = null
     sleepWhenPlayedToEnd = true
   }
@@ -55,6 +70,7 @@ open class SleepTimer {
   fun clear(): Boolean {
     val wasRunning = isRunning
     stopTimer()
+    onFadeCancel()
     time = null
     sleepWhenPlayedToEnd = false
     return wasRunning
@@ -65,9 +81,23 @@ open class SleepTimer {
     // Default implementation does nothing - override in subclass
   }
 
+  /** Override to begin fading the volume; the timer still completes at its deadline. */
+  open fun onFadeStart(durationSeconds: Double) {
+    // Default implementation does nothing - override in subclass
+  }
+
+  /** Override to handle a fade cancelled before completion — restore the volume. */
+  open fun onFadeCancel() {
+    // Default implementation does nothing - override in subclass
+  }
+
   private fun complete() {
     if (!isRunning) return
-    clear()
+    // Tear down without onFadeCancel: completion pauses first, then the completion handler
+    // restores the volume.
+    stopTimer()
+    time = null
+    sleepWhenPlayedToEnd = false
     onComplete()
   }
 
@@ -76,5 +106,9 @@ open class SleepTimer {
       handler.removeCallbacks(it)
       runnable = null
     }
+    fadeRunnable?.let {
+      handler.removeCallbacks(it)
+      fadeRunnable = null
+    }
   }
 }

package/android/src/main/java/com/audiobrowser/player/SleepTimerManager.kt

@@ -0,0 +1,80 @@
+package com.audiobrowser.player
+
+import com.margelo.nitro.audiobrowser.SleepTimer as NitroSleepTimer
+import com.margelo.nitro.audiobrowser.SleepTimerEndOfTrack
+import com.margelo.nitro.audiobrowser.SleepTimerTime
+import com.margelo.nitro.core.NullType
+import timber.log.Timber
+
+/**
+ * Owns the Sleep Timer's interplay with the volume fade and its JS event emission: the timer counts
+ * down natively (the webview may be asleep), an optional fade finishes exactly at the deadline, and
+ * completion pauses — never stops — with the pre-fade volume restored so a half-asleep listener can
+ * resume at full volume. Mirrors iOS's SleepTimerManager. [pause] is the player's pause;
+ * [onChanged] emits onSleepTimerChanged.
+ */
+internal class SleepTimerManager(
+  private val volumeFader: VolumeFader,
+  private val pause: () -> Unit,
+  private val onChanged: (NitroSleepTimer) -> Unit,
+) {
+
+  private val timer =
+    object : SleepTimer() {
+      override fun onFadeStart(durationSeconds: Double) {
+        volumeFader.start(durationSeconds)
+      }
+
+      override fun onFadeCancel() {
+        volumeFader.cancel(restoreVolume = true)
+      }
+
+      override fun onComplete() {
+        Timber.d("Sleep timer completed, pausing playback")
+        volumeFader.resolve { pause() }
+        onChanged(none())
+      }
+    }
+
+  private fun none(): NitroSleepTimer = NitroSleepTimer.create(NullType.NULL)
+
+  /** The current state: a time-based deadline, end-of-track, or none. */
+  fun get(): NitroSleepTimer =
+    when {
+      timer.time != null -> NitroSleepTimer.create(SleepTimerTime(timer.time!!))
+      timer.sleepWhenPlayedToEnd -> NitroSleepTimer.create(SleepTimerEndOfTrack(true))
+      else -> none()
+    }
+
+  /**
+   * Pauses playback after [seconds], optionally fading out over the last [fadeDuration] seconds
+   * (clamped to [seconds]).
+   */
+  fun setAfter(seconds: Double, fadeDuration: Double? = null) {
+    timer.sleepAfter(seconds, fadeDuration)
+    onChanged(get())
+  }
+
+  /** Pauses playback when the current track finishes playing. */
+  fun setEndOfTrack() {
+    timer.sleepWhenPlayedToEnd()
+    onChanged(get())
+  }
+
+  /** Clears the active timer. @return true when a timer was actually cleared. */
+  fun clear(): Boolean {
+    val wasRunning = timer.clear()
+    if (wasRunning) onChanged(none())
+    return wasRunning
+  }
+
+  /** Pauses when an end-of-track sleep is armed; called when a track finishes naturally. */
+  fun onTrackEnd() {
+    if (timer.sleepWhenPlayedToEnd) {
+      Timber.d("Sleep timer triggered on track end, pausing playback")
+      timer.clear()
+      pause()
+      onChanged(none())
+    }
+  }
+}

package/android/src/main/java/com/audiobrowser/player/StuckRecoveryPolicy.kt

@@ -0,0 +1,50 @@
+package com.audiobrowser.player
+
+/**
+ * Caps how many times the player auto-recovers from a media3
+ * [androidx.media3.common.util.StuckPlayerException] before surfacing a terminal error.
+ *
+ * media3 1.9.0 detects a stuck player and reports it through Player.Listener.onPlayerError. We
+ * recover (re-prepare / rejoin live edge) rather than going to ERROR, because for a live-radio app
+ * a transient stall should reconnect, not stop playback. But a genuinely dead stream would re-fire
+ * forever, so we allow at most [maxRecoveries] recoveries. The budget refills only when the caller
+ * has proof the stream is alive (sustained playback) or on a track change — both via [reset]. Once
+ * the cap is exceeded the decision stays [Decision.GIVE_UP] (it does not self-refill), so a dead
+ * stream produces one clean terminal error instead of a recover/error sawtooth.
+ *
+ * Deliberately holds no clock or time-window: a time-window keyed on recovery timing lets a stream
+ * that re-stalls just outside the window recover indefinitely. "Is it alive?" is answered by the
+ * caller from actual playback progress, not elapsed time.
+ *
+ * @param maxRecoveries Maximum recoveries allowed before giving up.
+ */
+class StuckRecoveryPolicy(private val maxRecoveries: Int = DEFAULT_MAX_RECOVERIES) {
+  enum class Decision {
+    RECOVER,
+    GIVE_UP,
+  }
+
+  private var recoveryCount = 0
+
+  /**
+   * Records a stuck event and decides what to do. [Decision.RECOVER] means the caller should
+   * re-prepare; [Decision.GIVE_UP] means recovery is exhausted and the caller should surface a
+   * terminal error. Stays [Decision.GIVE_UP] until [reset] is called.
+   */
+  fun onStuck(): Decision {
+    recoveryCount++
+    return if (recoveryCount > maxRecoveries) Decision.GIVE_UP else Decision.RECOVER
+  }
+
+  /**
+   * Refills the recovery budget. Call on proof the stream is alive (sustained playback) or on a
+   * track change.
+   */
+  fun reset() {
+    recoveryCount = 0
+  }
+
+  companion object {
+    private const val DEFAULT_MAX_RECOVERIES = 3
+  }
+}

package/android/src/main/java/com/audiobrowser/player/TransformingDataSource.kt

@@ -7,25 +7,24 @@ import androidx.media3.datasource.DataSpec
 import androidx.media3.datasource.TransferListener
 import com.audiobrowser.util.BrowserPathHelper
 import com.margelo.nitro.audiobrowser.MediaRequestConfig
+import java.io.IOException
 import timber.log.Timber
 
 /**
  * A DataSource wrapper that defers media URL transformation to ExoPlayer's IO thread.
  *
  * ExoPlayer calls [MediaSource.Factory.createMediaSource] on the main thread during
- * `addMediaItem()`, but calls [DataSource.open] on a background IO thread when it
- * needs to fetch data. By deferring URL transformation (which may invoke a JS callback
- * via `runBlocking`) to [open], we avoid blocking the main thread and prevent deadlocks
- * when the JS thread is occupied by synchronous Nitro calls (e.g., `seekTo`).
+ * `addMediaItem()`, but calls [DataSource.open] on a background IO thread when it needs to fetch
+ * data. By deferring URL transformation (which may invoke a JS callback via `runBlocking`) to
+ * [open], we avoid blocking the main thread and prevent deadlocks when the JS thread is occupied by
+ * synchronous Nitro calls (e.g., `seekTo`).
  *
- * The transform is resolved once per track on the first [open] call (the manifest/media
- * URL). The resulting headers and user-agent are cached on the [Factory] and reused for
- * subsequent requests (segments, encryption keys) without calling the JS transform again.
+ * The transform is resolved once per track on the first [open] call (the manifest/media URL). The
+ * resulting headers and user-agent are cached on the [Factory] and reused for subsequent requests
+ * (segments, encryption keys) without calling the JS transform again.
  */
-class TransformingDataSource(
-  private val upstream: DataSource,
-  private val factory: Factory,
-) : DataSource {
+class TransformingDataSource(private val upstream: DataSource, private val factory: Factory) :
+  DataSource {
 
   companion object {
     private const val DEFAULT_USER_AGENT = "react-native-audio-browser"
@@ -36,19 +35,28 @@ class TransformingDataSource(
   override fun open(dataSpec: DataSpec): Long {
     val originalUrl = dataSpec.uri.toString()
 
-    // Check if the Factory already has a cached transform result.
-    // The first DataSource to open() resolves the transform and caches it.
-    // All subsequent opens (segments, keys, replays) reuse the cached
-    // headers/user-agent but keep their original URLs.
+    // The first open() resolves the transform and caches it on the Factory; subsequent opens
+    // (segments, keys, replays) reuse the cached headers/user-agent but keep their own URLs.
     val cached = factory.cachedTransform
-    val (finalUrl, headers, userAgent) = if (cached == null) {
-      val resolved = resolveRequestConfig(originalUrl)
-      factory.cachedTransform = resolved
-      Timber.d("TransformingDataSource: resolved $originalUrl -> ${resolved.first}")
-      resolved
-    } else {
-      Triple(originalUrl, cached.second, cached.third)
-    }
+    val (finalUrl, headers, userAgent) =
+      when {
+        cached == null -> resolveAndCache(originalUrl)
+        // Re-open of the same media URL (e.g. a retry after a network drop). By default reuse the
+        // resolved URL: re-emitting the schemeless original ("/listen/<id>/x.mp3") would hit the
+        // file data source -> FileNotFoundException. But if the previous media-URL load failed,
+        // re-resolve once (see the catch below): the URL/token may be stale. The fresh URL is still
+        // absolute, so that hazard stays avoided.
+        originalUrl == factory.cachedOriginalUrl ->
+          if (factory.reresolveOnNextMediaOpen) {
+            factory.reresolveOnNextMediaOpen = false
+            resolveAndCache(originalUrl)
+          } else {
+            cached
+          }
+        // A different URL (already-absolute HLS segment or key): reuse the cached headers but keep
+        // its own URL.
+        else -> Triple(originalUrl, cached.second, cached.third)
+      }
 
     // Build merged headers including user-agent override
     val mergedHeaders = buildMap {
@@ -64,7 +72,27 @@ class TransformingDataSource(
       dataSpec.buildUpon().setUri(finalUrl.toUri()).setHttpRequestHeaders(mergedHeaders).build()
 
     resolvedUri = transformedSpec.uri
-    return upstream.open(transformedSpec)
+    return try {
+      upstream.open(transformedSpec)
+    } catch (e: IOException) {
+      // The media-URL load failed: if ExoPlayer retries, re-resolve so a stale URL/token is
+      // refreshed instead of replayed. Scoped to the media URL (segment/key failures keep their own
+      // URL). The flag lives on this item's Factory, so it stays correct when several tracks'
+      // factories are alive at once (a queue).
+      if (originalUrl == factory.cachedOriginalUrl) {
+        factory.reresolveOnNextMediaOpen = true
+      }
+      throw e
+    }
+  }
+
+  /** Resolves the transform for [originalUrl] and caches the result on the [Factory]. */
+  private fun resolveAndCache(originalUrl: String): Triple<String, Map<String, String>, String> {
+    val resolved = resolveRequestConfig(originalUrl)
+    factory.cachedTransform = resolved
+    factory.cachedOriginalUrl = originalUrl
+    Timber.d("TransformingDataSource: resolved $originalUrl -> ${resolved.first}")
+    return resolved
   }
 
   override fun read(buffer: ByteArray, offset: Int, length: Int): Int {
@@ -79,6 +107,18 @@ class TransformingDataSource(
     return resolvedUri ?: upstream.uri
   }
 
+  /**
+   * Forward the upstream response headers. ExoPlayer's `ProgressiveMediaPeriod` reads these back
+   * through the data-source chain to parse `IcyHeaders` (the `icy-metaint` interval) and only then
+   * installs the `IcyDataSource` that emits in-stream ICY/Shoutcast song metadata via
+   * `Player.Listener.onMetadata`. The `DataSource` default returns an empty map, so without this
+   * override this transparent wrapper would swallow the ICY headers — playback keeps working but
+   * `onMetadata` never fires (live "now playing" song goes missing).
+   */
+  override fun getResponseHeaders(): Map<String, List<String>> {
+    return upstream.responseHeaders
+  }
+
   override fun close() {
     upstream.close()
     resolvedUri = null
@@ -129,19 +169,29 @@ class TransformingDataSource(
   ) : DataSource.Factory {
 
     /**
-     * Cached transform result (url, headers, userAgent) from the first open() call.
-     * Shared across all DataSource instances created by this factory.
-     * A new Factory is created per [MediaFactory.createMediaSource] call (per track),
-     * so the cache naturally resets on track transitions.
+     * Cached transform result (url, headers, userAgent) from the first open() call. Shared across
+     * all DataSource instances created by this factory. A new Factory is created per
+     * [MediaFactory.createMediaSource] call (per track), so the cache naturally resets on track
+     * transitions.
+     */
+    @Volatile internal var cachedTransform: Triple<String, Map<String, String>, String>? = null
+
+    /**
+     * The original (pre-transform) URL that [cachedTransform] was resolved from. Used to recognise
+     * a re-open of the same media URL (e.g. a retry) so it reuses the resolved URL instead of the
+     * raw original.
+     */
+    @Volatile internal var cachedOriginalUrl: String? = null
+
+    /**
+     * Set when a media-URL load fails so the next media-URL open re-runs the transform instead of
+     * replaying [cachedTransform] — recovers an expired short-lived URL/token across a retry.
+     * Self-clearing: consumed by the first re-resolve.
      */
-    @Volatile
-    internal var cachedTransform: Triple<String, Map<String, String>, String>? = null
+    @Volatile internal var reresolveOnNextMediaOpen: Boolean = false
 
     override fun createDataSource(): DataSource {
-      return TransformingDataSource(
-        upstream = upstreamFactory.createDataSource(),
-        factory = this,
-      )
+      return TransformingDataSource(upstream = upstreamFactory.createDataSource(), factory = this)
     }
   }
 }