react-native-audio-browser 0.2.0-next.9 → 0.2.0

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

@@ -1,129 +0,0 @@
-package com.audiobrowser.player
-
-import androidx.media3.common.PlaybackException
-import androidx.media3.datasource.HttpDataSource.InvalidResponseCodeException
-import com.margelo.nitro.audiobrowser.PlaybackError
-import com.margelo.nitro.audiobrowser.PlaybackErrorKind
-import java.io.IOException
-
-/**
- * Maps ExoPlayer's failure codes onto [PlaybackErrorKind], the cross-platform contract iOS
- * populates from AVFoundation. Consumers branch on the kind; the raw ExoPlayer code still travels
- * alongside it as `PlaybackError.code` for telemetry.
- *
- * Codes that carry no real evidence of a cause (`ERROR_CODE_UNSPECIFIED`,
- * `ERROR_CODE_IO_UNSPECIFIED`, a bad HTTP status whose response code we could not recover) stay
- * [PlaybackErrorKind.UNKNOWN] rather than being guessed into a nicer-sounding bucket — a wrong
- * classification is worse than an honest one, both for the listener and for the aggregates.
- */
-object PlaybackErrorClassifier {
-  /**
-   * Classifies a player failure.
-   *
-   * @param online whether the device had connectivity at the moment of failure. ExoPlayer's codes
-   *   cannot distinguish "the device is offline" from "this stream is unreachable"; only the
-   *   connectivity monitor can, which is why it is passed in.
-   */
-  fun classify(error: PlaybackException, online: Boolean): PlaybackErrorKind {
-    if (!online) return PlaybackErrorKind.OFFLINE
-    val responseCode = responseCode(error)
-    if (responseCode != null) return kindForHttpStatus(responseCode)
-    return kindForErrorCode(error.errorCode)
-  }
-
-  /** The HTTP status the server answered with, if this failure came from an HTTP response. */
-  fun responseCode(error: PlaybackException): Int? =
-    generateSequence(error.cause) { it.cause }
-      .filterIsInstance<InvalidResponseCodeException>()
-      .firstOrNull()
-      ?.responseCode
-
-  /**
-   * Classifies a load error the retry policy is still working on, as an advisory (`retrying`)
-   * [PlaybackError]. Load errors arrive as raw [IOException]s (see
-   * [RetryLoadErrorHandlingPolicy.classifyError]), never as [PlaybackException] — that shape only
-   * exists once retries are exhausted. The policy only retries HTTP statuses and transport
-   * failures, so a non-HTTP retryable load error is by construction a network one.
-   */
-  fun retryingLoadError(exception: IOException, online: Boolean): PlaybackError {
-    val responseCode =
-      generateSequence(exception as Throwable) { it.cause }
-        .filterIsInstance<InvalidResponseCodeException>()
-        .firstOrNull()
-        ?.responseCode
-    // Fixed message per classification (mirrors iOS's localized descriptions): raw
-    // IOException messages vary between attempts of the same outage, which would defeat
-    // the caller's identical-repeat dedupe and churn the wire payload.
-    val (kind, code, message) =
-      when {
-        !online ->
-          Triple(PlaybackErrorKind.OFFLINE, "not-connected-to-internet", "No internet connection")
-        responseCode != null ->
-          Triple(
-            kindForHttpStatus(responseCode),
-            "io-bad-http-status",
-            "Server responded with HTTP $responseCode",
-          )
-        else ->
-          Triple(
-            PlaybackErrorKind.UNREACHABLE,
-            "io-network-connection-failed",
-            "Could not reach the stream host",
-          )
-      }
-    return PlaybackError(kind, code, message, responseCode?.toDouble(), retrying = true)
-  }
-
-  fun kindForHttpStatus(status: Int): PlaybackErrorKind =
-    when (status) {
-      404,
-      410 -> PlaybackErrorKind.NOT_FOUND
-      in 500..599 -> PlaybackErrorKind.SERVER_ERROR
-      // Every other 4xx is the server refusing us — auth, geo-blocking, a rate limit. All of them
-      // mean "you can't have this stream", not "retry".
-      in 400..499 -> PlaybackErrorKind.REJECTED
-      else -> PlaybackErrorKind.UNKNOWN
-    }
-
-  private fun kindForErrorCode(errorCode: Int): PlaybackErrorKind =
-    when (errorCode) {
-      PlaybackException.ERROR_CODE_IO_NETWORK_CONNECTION_FAILED,
-      PlaybackException.ERROR_CODE_IO_NETWORK_CONNECTION_TIMEOUT,
-      PlaybackException.ERROR_CODE_TIMEOUT -> PlaybackErrorKind.UNREACHABLE
-
-      PlaybackException.ERROR_CODE_IO_FILE_NOT_FOUND -> PlaybackErrorKind.NOT_FOUND
-
-      // The server, the licence server, or the session refused us.
-      PlaybackException.ERROR_CODE_IO_NO_PERMISSION,
-      PlaybackException.ERROR_CODE_AUTHENTICATION_EXPIRED,
-      PlaybackException.ERROR_CODE_PREMIUM_ACCOUNT_REQUIRED,
-      PlaybackException.ERROR_CODE_CONCURRENT_STREAM_LIMIT,
-      PlaybackException.ERROR_CODE_PARENTAL_CONTROL_RESTRICTED,
-      PlaybackException.ERROR_CODE_NOT_AVAILABLE_IN_REGION,
-      in DRM_CODES -> PlaybackErrorKind.REJECTED
-
-      // Fetched, but nothing we can turn into audio: wrong content type, malformed or unsupported
-      // container, a decoder that refused it, or an output track we could not open.
-      PlaybackException.ERROR_CODE_IO_INVALID_HTTP_CONTENT_TYPE,
-      PlaybackException.ERROR_CODE_IO_CLEARTEXT_NOT_PERMITTED,
-      PlaybackException.ERROR_CODE_IO_READ_POSITION_OUT_OF_RANGE,
-      PlaybackException.ERROR_CODE_NOT_SUPPORTED,
-      in PARSING_CODES,
-      in DECODING_CODES,
-      in AUDIO_TRACK_CODES -> PlaybackErrorKind.UNPLAYABLE
-
-      else -> PlaybackErrorKind.UNKNOWN
-    }
-
-  private val PARSING_CODES =
-    PlaybackException.ERROR_CODE_PARSING_CONTAINER_MALFORMED..PlaybackException
-        .ERROR_CODE_PARSING_MANIFEST_UNSUPPORTED
-  private val DECODING_CODES =
-    PlaybackException.ERROR_CODE_DECODER_INIT_FAILED..PlaybackException
-        .ERROR_CODE_DECODING_RESOURCES_RECLAIMED
-  private val AUDIO_TRACK_CODES =
-    PlaybackException.ERROR_CODE_AUDIO_TRACK_INIT_FAILED..PlaybackException
-        .ERROR_CODE_AUDIO_TRACK_OFFLOAD_INIT_FAILED
-  private val DRM_CODES =
-    PlaybackException.ERROR_CODE_DRM_UNSPECIFIED..PlaybackException.ERROR_CODE_DRM_LICENSE_EXPIRED
-}

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

@@ -1,85 +0,0 @@
-package com.audiobrowser.player
-
-import androidx.media3.common.Player as MediaPlayer
-import com.margelo.nitro.audiobrowser.PlaybackState
-
-/**
- * An observation that may move the playback state machine. Context (does a track exist, is the
- * engine audibly playing, the queue size) is captured into the event at the call site —
- * [PlaybackStateMachine] itself stays pure.
- */
-sealed interface PlaybackEvent {
-  /**
-   * ExoPlayer's playback state changed. [exoState] MUST be the real ExoPlayer state, not the
-   * InterceptingPlayer-masked value (which reports READY through a masked terminal error to keep
-   * the session alive — feeding that back in would clear the ERROR state).
-   */
-  data class ExoPlaybackStateChanged(
-    @get:MediaPlayer.State val exoState: Int,
-    val mediaItemCount: Int,
-    val playWhenReady: Boolean,
-  ) : PlaybackEvent
-
-  /** The active media item changed (auto-advance, skip, queue swap). */
-  data class MediaItemTransition(val hasTrack: Boolean, val isPlaying: Boolean) : PlaybackEvent
-
-  data class PlayWhenReadyChanged(val playWhenReady: Boolean) : PlaybackEvent
-
-  data class IsPlayingChanged(val isPlaying: Boolean) : PlaybackEvent
-}
-
-/**
- * The playback state transitions: the next states (in order) for an event from the current state,
- * empty to suppress. The Android analog of iOS's `nextPlaybackState(from:on:)` — guards here are
- * state-related ("not from ERROR/STOPPED"); context-related guards live in the event fields.
- * Effects (error clearing, event emission, timers) stay with the caller: the machine only decides.
- */
-object PlaybackStateMachine {
-
-  fun transitions(current: PlaybackState, event: PlaybackEvent): List<PlaybackState> =
-    when (event) {
-      is PlaybackEvent.ExoPlaybackStateChanged ->
-        when (event.exoState) {
-          MediaPlayer.STATE_BUFFERING -> listOf(PlaybackState.BUFFERING)
-          MediaPlayer.STATE_READY ->
-            // While playing (playWhenReady), READY is a transient before PLAYING —
-            // suppress it so consumers don't flash a settled/non-loading state
-            // mid-startup (none→loading→buffering→playing). When paused it IS the
-            // settled signal a buffer-that-finished-while-paused needs, so consumers
-            // can clear their loading spinner (mono#3325).
-            if (event.playWhenReady) emptyList() else listOf(PlaybackState.READY)
-          MediaPlayer.STATE_IDLE ->
-            // A terminal error (or an explicit stop) idles ExoPlayer; transitioning to NONE
-            // would clear the ERROR/STOPPED state the session is rendering.
-            if (current == PlaybackState.ERROR || current == PlaybackState.STOPPED) emptyList()
-            else listOf(PlaybackState.NONE)
-          MediaPlayer.STATE_ENDED ->
-            // An emptied queue also reports STATE_ENDED; without items that is "nothing
-            // loaded", not "played to end".
-            listOf(if (event.mediaItemCount > 0) PlaybackState.ENDED else PlaybackState.NONE)
-          else -> emptyList()
-        }
-      is PlaybackEvent.MediaItemTransition ->
-        when {
-          !event.hasTrack -> emptyList()
-          // Already audibly playing (gapless auto-advance): run the full burst so consumers
-          // see the canonical loading→ready→playing sequence rather than sticking on LOADING.
-          event.isPlaying ->
-            listOf(PlaybackState.LOADING, PlaybackState.READY, PlaybackState.PLAYING)
-          else -> listOf(PlaybackState.LOADING)
-        }
-      is PlaybackEvent.PlayWhenReadyChanged ->
-        // STOPPED and ENDED are terminal: dropping the intent there (stop()'s own
-        // clear, the clear on natural end, or a redundant pause press) must not
-        // re-report the state as PAUSED.
-        if (
-          !event.playWhenReady && current != PlaybackState.STOPPED && current != PlaybackState.ENDED
-        ) {
-          listOf(PlaybackState.PAUSED)
-        } else {
-          emptyList()
-        }
-      is PlaybackEvent.IsPlayingChanged ->
-        if (event.isPlaying) listOf(PlaybackState.PLAYING) else emptyList()
-    }
-}

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

@@ -1,56 +0,0 @@
-package com.audiobrowser.player
-
-import com.margelo.nitro.audiobrowser.PlaybackState
-import kotlinx.coroutines.Job
-import kotlinx.coroutines.MainScope
-import kotlinx.coroutines.delay
-import kotlinx.coroutines.launch
-
-/**
- * A playback-gated repeating timer. Runs [onTick] every [interval] seconds while the current
- * playback state satisfies [isActive]. A null interval (or <= 0) means stopped — the single
- * off-switch.
- */
-class PlaybackTimer(
-  private val isActive: (PlaybackState) -> Boolean,
-  private val onTick: () -> Unit,
-) {
-  private val scope = MainScope()
-  private var job: Job? = null
-  private var interval: Double? = null
-  private var active = false
-
-  fun setInterval(value: Double?) {
-    val normalized = if (value != null && value > 0) value else null
-    if (normalized == interval) return
-    interval = normalized
-    stop() // restart with the new interval on reconcile
-    reconcile()
-  }
-
-  fun onPlaybackStateChanged(state: PlaybackState) {
-    active = isActive(state)
-    reconcile()
-  }
-
-  private fun reconcile() {
-    val interval = interval
-    if (interval != null && active) start(interval) else stop()
-  }
-
-  private fun start(interval: Double) {
-    if (job != null) return
-    job =
-      scope.launch {
-        while (true) {
-          delay((interval * 1000).toLong())
-          onTick()
-        }
-      }
-  }
-
-  private fun stop() {
-    job?.cancel()
-    job = null
-  }
-}

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

@@ -1,20 +0,0 @@
-package com.audiobrowser.player
-
-import com.margelo.nitro.audiobrowser.FavoritesMatchMode
-import com.margelo.nitro.audiobrowser.PlayerCapabilities
-
-/**
- * Resolved favorite match mode, or null when favoriting is disabled.
- *
- * `false`/unset → null; `true` → EXACT; `{ match }` → that match.
- */
-val PlayerCapabilities.favoriteMatch: FavoritesMatchMode?
-  get() =
-    favorite?.match(
-      first = { enabled -> if (enabled) FavoritesMatchMode.EXACT else null },
-      second = { config -> config.match },
-    )
-
-/** Whether the favorite/like control is enabled. */
-val PlayerCapabilities.favoriteEnabled: Boolean
-  get() = favoriteMatch != null

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

@@ -1,130 +0,0 @@
-package com.audiobrowser.player
-
-import android.content.Context
-import androidx.media3.common.AudioAttributes
-import androidx.media3.common.C
-import androidx.media3.common.TrackSelectionParameters
-import androidx.media3.datasource.cache.SimpleCache
-import androidx.media3.exoplayer.DefaultRenderersFactory
-import androidx.media3.exoplayer.ExoPlayer
-import androidx.media3.exoplayer.upstream.DefaultBandwidthMeter
-import com.audiobrowser.model.PlayerSetupOptions
-import com.audiobrowser.util.AndroidAudioContentTypeFactory
-import com.margelo.nitro.audiobrowser.AndroidPlayerWakeMode
-import com.margelo.nitro.audiobrowser.MediaRequestConfig
-import java.io.IOException
-
-// media3's configurable stuck-buffering (type-1, STUCK_BUFFERING_NO_PROGRESS) timeout. Fires only
-// on zero loading progress; 60s of silent non-progress is already a bad live-radio experience,
-// while the media3 default of 600s would mean 10 minutes of dead air. (Type-0
-// STUCK_BUFFERING_NOT_LOADING is a separate, uncontrollable fixed-4s check.)
-private const val STUCK_BUFFERING_DETECTION_TIMEOUT_MS = 60_000
-
-/** The engine pieces [buildPlayerEngine] constructs together for one setup() generation. */
-internal class PlayerEngine(
-  val loadControl: DynamicLoadControl,
-  val mediaFactory: MediaFactory,
-  val exoPlayer: ExoPlayer,
-)
-
-/**
- * The buffer configuration described by the setup options. When `rebufferBuffer` is unset
- * (automatic), post-rebuffer playback starts at `playBuffer` and AutomaticBufferManager adjusts it;
- * when set, that fixed value is used. Pure — pinned by PlayerEngineFactoryTest.
- */
-internal fun bufferConfig(options: PlayerSetupOptions): BufferConfig =
-  BufferConfig(
-    minBufferMs = options.minBuffer.toInt(),
-    maxBufferMs = options.maxBuffer.toInt(),
-    bufferForPlaybackMs = options.playBuffer.toInt(),
-    bufferForPlaybackAfterRebufferMs = (options.rebufferBuffer ?: options.playBuffer).toInt(),
-    backBufferMs = options.backBuffer.toInt(),
-  )
-
-/**
- * Constructs the playback engine for one `setup()` generation: load control, media factory, and the
- * ExoPlayer they plug into — pure construction, no lifecycle. Tearing down the previous generation,
- * wiring listeners/session, and everything stateful stays in [Player.setup], which provides its
- * mutable context through the lambdas.
- */
-internal fun buildPlayerEngine(
-  context: Context,
-  options: PlayerSetupOptions,
-  cache: SimpleCache?,
-  shouldRetry: () -> Boolean,
-  isOnline: () -> Boolean,
-  hasPlayed: () -> Boolean,
-  onRetryPending: (exception: IOException, isNetworkError: Boolean) -> Unit,
-  resolveMediaConfig: (url: String) -> MediaRequestConfig?,
-): PlayerEngine {
-  val renderer = DefaultRenderersFactory(context)
-  renderer.setExtensionRendererMode(DefaultRenderersFactory.EXTENSION_RENDERER_MODE_PREFER)
-
-  // Bandwidth meter for adaptive bitrate selection in HLS/DASH
-  val bandwidthMeter = DefaultBandwidthMeter.Builder(context).build()
-
-  val loadControl = DynamicLoadControl(initialConfig = bufferConfig(options))
-
-  // shouldRetry checks playWhenReady to avoid retrying when paused (e.g., another app took audio
-  // focus) — via a thread-safe cache since this runs on ExoPlayer's playback thread. isOnline and
-  // onRetryPending enable network-aware retry acceleration.
-  val mediaFactory =
-    MediaFactory(
-      context,
-      cache,
-      options.retryPolicy,
-      shouldRetry = shouldRetry,
-      isOnline = isOnline,
-      hasPlayed = hasPlayed,
-      onRetryPending = onRetryPending,
-      transferListener = bandwidthMeter,
-      getRequestConfig = resolveMediaConfig,
-    )
-
-  val exoPlayer =
-    ExoPlayer.Builder(context)
-      .setRenderersFactory(renderer)
-      .setBandwidthMeter(bandwidthMeter)
-      .setHandleAudioBecomingNoisy(options.handleAudioBecomingNoisy)
-      .setMediaSourceFactory(mediaFactory)
-      .setStuckBufferingDetectionTimeoutMs(STUCK_BUFFERING_DETECTION_TIMEOUT_MS)
-      .setWakeMode(
-        when (options.wakeMode) {
-          AndroidPlayerWakeMode.NONE -> C.WAKE_MODE_NONE
-          AndroidPlayerWakeMode.LOCAL -> C.WAKE_MODE_LOCAL
-          AndroidPlayerWakeMode.NETWORK -> C.WAKE_MODE_NETWORK
-        }
-      )
-      .setLoadControl(loadControl)
-      .setName("AudioBrowser")
-      .build()
-
-  exoPlayer.setAudioAttributes(
-    AudioAttributes.Builder()
-      .setUsage(C.USAGE_MEDIA)
-      .setContentType(AndroidAudioContentTypeFactory.toMedia3(options.audioContentType))
-      .build(),
-    true, // handle audio focus
-  )
-
-  options.audioOffload?.let {
-    val audioOffloadPreferences =
-      TrackSelectionParameters.AudioOffloadPreferences.Builder()
-        .setAudioOffloadMode(
-          TrackSelectionParameters.AudioOffloadPreferences.AUDIO_OFFLOAD_MODE_ENABLED
-        )
-        .setIsGaplessSupportRequired(it.gaplessSupportRequired)
-        .setIsSpeedChangeSupportRequired(it.rateChangeSupportRequired)
-        .build()
-    // Assigning the public final field compiles to a putfield that throws
-    // IllegalAccessError on ART, and mutating the getter's snapshot wouldn't
-    // reach the selector anyway — go through the builder.
-    exoPlayer.trackSelectionParameters =
-      exoPlayer.trackSelectionParameters
-        .buildUpon()
-        .setAudioOffloadPreferences(audioOffloadPreferences)
-        .build()
-  }
-
-  return PlayerEngine(loadControl, mediaFactory, exoPlayer)
-}

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

@@ -1,80 +0,0 @@
-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

@@ -1,50 +0,0 @@
-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/VolumeFader.kt

@@ -1,81 +0,0 @@
-package com.audiobrowser.player
-
-import android.os.Handler
-import android.os.Looper
-import android.os.SystemClock
-
-/**
- * Ramps the player volume down over a duration (sleep-timer fade). The gain follows a squared
- * curve: loudness perception is logarithmic, so a linear gain ramp sounds like a late cutoff rather
- * than a fade.
- */
-class VolumeFader(private val getVolume: () -> Float, private val setVolume: (Float) -> Unit) {
-  private val handler = Handler(Looper.getMainLooper())
-  private var stepRunnable: Runnable? = null
-
-  /**
-   * Volume captured when the fade started; restored after the fade resolves. Non-null from fade
-   * start until cancel/completion, even once the ramp has reached silence.
-   */
-  var originalVolume: Float? = null
-    private set
-
-  val isActive: Boolean
-    get() = originalVolume != null
-
-  fun start(durationSeconds: Double) {
-    // If a fade is already running, keep its captured volume as the baseline — the current
-    // (partially faded) volume is not the value to restore.
-    val baseVolume = originalVolume ?: getVolume()
-    cancel(restoreVolume = false)
-    originalVolume = baseVolume
-    if (durationSeconds <= 0) return
-
-    val startTime = SystemClock.uptimeMillis()
-    val durationMs = durationSeconds * 1000
-    val runnable =
-      object : Runnable {
-        override fun run() {
-          val progress = ((SystemClock.uptimeMillis() - startTime) / durationMs).coerceAtMost(1.0)
-          val remaining = (1 - progress).toFloat()
-          setVolume(baseVolume * remaining * remaining)
-          if (progress < 1.0) {
-            handler.postDelayed(this, STEP_INTERVAL_MS)
-          } else {
-            stepRunnable = null
-          }
-        }
-      }
-    stepRunnable = runnable
-    handler.post(runnable)
-  }
-
-  /**
-   * Stops the ramp. With [restoreVolume] the pre-fade volume is put back immediately
-   * (cancellation); without it the caller restores after pausing (completion path — restoring first
-   * would let full-volume audio slip out).
-   */
-  fun cancel(restoreVolume: Boolean) {
-    stepRunnable?.let { handler.removeCallbacks(it) }
-    stepRunnable = null
-    val original = originalVolume ?: return
-    originalVolume = null
-    if (restoreVolume) setVolume(original)
-  }
-
-  /**
-   * Resolves the fade around a halting action: stops the ramp, runs [halt], then restores the
-   * pre-fade volume — in that order, because restoring before halting would let full-volume audio
-   * slip out. The restore is skipped when no fade was running.
-   */
-  fun resolve(halt: () -> Unit) {
-    val preFadeVolume = originalVolume
-    cancel(restoreVolume = false)
-    halt()
-    preFadeVolume?.let { setVolume(it) }
-  }
-
-  companion object {
-    private const val STEP_INTERVAL_MS = 50L
-  }
-}