react-native-audio-browser 0.1.1 → 0.2.0-next.10

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

@@ -0,0 +1,347 @@
+package com.audiobrowser.player
+
+import com.audiobrowser.util.url
+import com.margelo.nitro.audiobrowser.FormatNowPlayingParams
+import com.margelo.nitro.audiobrowser.NowPlayingMetadata
+import com.margelo.nitro.audiobrowser.NowPlayingUpdate
+import com.margelo.nitro.audiobrowser.PlaybackError
+import com.margelo.nitro.audiobrowser.PlaybackState
+import com.margelo.nitro.audiobrowser.StallReason
+import com.margelo.nitro.audiobrowser.TimedMetadata
+import com.margelo.nitro.audiobrowser.Track
+import kotlinx.coroutines.CoroutineScope
+import kotlinx.coroutines.Job
+import kotlinx.coroutines.cancel
+import kotlinx.coroutines.delay
+import kotlinx.coroutines.launch
+import timber.log.Timber
+
+/**
+ * What the now-playing logic needs from the platform — implemented by [Player] (current playback
+ * reads, MediaItem stamping via `replaceMediaItem`, artwork resolution through the browser).
+ * Mirrors iOS's NowPlayingUpdater / NowPlayingInfoController split: this seam is what makes the
+ * precedence/guard/dedupe logic testable with a fake.
+ */
+interface NowPlayingSurface {
+  val currentIndex: Int?
+  val currentTrack: Track?
+  val playbackState: PlaybackState
+  val playbackError: PlaybackError?
+
+  /**
+   * MUST be the real play/pause intent read from the underlying ExoPlayer — not the
+   * InterceptingPlayer-masked value, which can report false through a masked terminal error to keep
+   * the session paused-but-alive. The formatter receives this; feeding it the masked value breaks
+   * its output exactly in the error case the mask exists for.
+   */
+  val playWhenReady: Boolean
+  val isRebuffering: Boolean
+
+  /** Device connectivity, used to classify a stall as offline vs a plain rebuffer. */
+  val isOnline: Boolean
+
+  val hasNowPlayingArtworkConfig: Boolean
+
+  /** Stamp title/secondary/album onto the playing item. */
+  fun stampFields(index: Int, track: Track, title: String?, secondaryLine: String?, album: String?)
+
+  /** Stamp a resolved artwork uri onto the playing item. */
+  fun stampArtwork(index: Int, track: Track, uri: String)
+
+  /**
+   * Resolve the now-playing artwork for [track] via the `nowPlayingArtwork` config kind. Returns
+   * the final uri, or null when resolution produced nothing (errors are logged inside).
+   */
+  suspend fun resolveNowPlayingArtwork(track: Track, sizePx: Double): String?
+
+  fun emitNowPlayingChanged(metadata: NowPlayingMetadata)
+}
+
+/**
+ * Owns the Now Playing rendering pipeline: the flash > override > formatter > track precedence, the
+ * publish dedupe, the stale-result guards (render generation + track-id keying), timed (ICY)
+ * metadata, and the once-per-track artwork keying. Mirrors iOS's NowPlayingUpdater. The platform is
+ * reached only through [NowPlayingSurface]; the JS formatter arrives as a plain suspend lambda
+ * (wrapped at the Nitro boundary in Player.setup), so every guard here runs under JVM tests.
+ */
+class NowPlayingUpdater(private val surface: NowPlayingSurface, private val scope: CoroutineScope) {
+
+  /** Whether now-playing rendering (override/flash/formatter) is enabled (PlayerSetupOptions). */
+  var enabled = true
+
+  /** The JS formatter, wrapped to a plain suspend call at the Nitro boundary (see Player.setup). */
+  var formatter: (suspend (FormatNowPlayingParams) -> NowPlayingUpdate?)? = null
+
+  /** Latest live timed (ICY/ID3) metadata; cleared on track change. */
+  @Volatile private var latestTimedMetadata: TimedMetadata? = null
+
+  /** Imperative override (from `updateNowPlaying()`); cleared on track change. */
+  private var override: NowPlayingUpdate? = null
+
+  /**
+   * Transient now-playing fields (e.g. feedback for a refused remote command). Outranks the
+   * formatter and the override while active, so live metadata can't stomp it mid-flash. Reverted by
+   * a coroutine delay on [scope] — NOT a JS timer, which pauses with a backgrounded host (and the
+   * lock screen is exactly the backgrounded case) — and cleared early on track change.
+   */
+  private var flash: NowPlayingUpdate? = null
+  private var flashRevert: Job? = null
+
+  /**
+   * Monotonic stamp for renders. An async formatter result applies only when no newer render —
+   * notably a flash — has superseded the one that launched it.
+   */
+  private var renderGeneration = 0L
+
+  /** The last fields actually published, to dedupe redundant stamps. */
+  private data class Published(
+    val index: Int,
+    val trackId: String?,
+    val title: String?,
+    val secondaryLine: String?,
+    val album: String?,
+  )
+
+  private var lastPublished: Published? = null
+
+  /**
+   * The track id whose now-playing artwork has been resolved (or is being resolved), so a
+   * `nowPlayingArtwork` resolve runs once per track instead of on every render.
+   */
+  private var artworkResolvedForTrackId: String? = null
+
+  /** Size hint (px, square) for now-playing artwork. Mirrors iOS (screen-width-capped to 1200). */
+  private val artworkSizePx = 1200.0
+
+  /** Cancels in-flight work. Called from Player.destroy. */
+  fun destroy() {
+    scope.cancel()
+  }
+
+  /** Sets/clears the imperative override (null reverts to track metadata) and re-renders. */
+  fun updateNowPlaying(update: NowPlayingUpdate?) {
+    override = update
+    render()
+  }
+
+  fun flashNowPlaying(update: NowPlayingUpdate, durationMs: Double) {
+    flashRevert?.cancel()
+    flash = update
+    flashRevert =
+      scope.launch {
+        delay(durationMs.toLong())
+        flash = null
+        flashRevert = null
+        render()
+      }
+    render()
+  }
+
+  /** Clears an active flash immediately, reverting to the live metadata. No-op when none. */
+  fun clearNowPlayingFlash() {
+    if (flash == null) return
+    cancelFlash()
+    render()
+  }
+
+  private fun cancelFlash() {
+    flashRevert?.cancel()
+    flashRevert = null
+    flash = null
+  }
+
+  /** Gets the current now playing metadata (flash/override if set, else track metadata). */
+  fun getNowPlaying(): NowPlayingMetadata? {
+    val track = surface.currentTrack ?: return null
+    val flash = flash
+    val override = override
+
+    return NowPlayingMetadata(
+      elapsedTime = null,
+      title = flash?.title ?: override?.title ?: track.title,
+      album = flash?.album ?: override?.album ?: track.album,
+      artist = flash?.artist ?: override?.artist ?: track.artist,
+      duration = track.duration,
+      artwork = track.artwork?.url,
+      description = track.description,
+      mediaId = track.src ?: track.url,
+      genre = track.genre,
+    )
+  }
+
+  /** Clears override, flash, and timed metadata on track change (PlayerListener transition). */
+  fun clearOverride() {
+    override = null
+    cancelFlash()
+    latestTimedMetadata = null
+  }
+
+  /**
+   * Records the latest live timed (ICY/ID3) metadata and, when a formatter is configured, re-runs
+   * it so the live song is reflected on the now-playing surface.
+   */
+  fun onTimedMetadataReceived(timed: TimedMetadata) {
+    latestTimedMetadata = timed
+    if (enabled && formatter != null) {
+      render()
+    }
+  }
+
+  /**
+   * Renders the current now playing metadata to the surface. Flash wins while active (formatter
+   * skipped entirely so its async result can't land on top); otherwise the override-or-track
+   * default is stamped immediately and a configured formatter customizes it asynchronously, guarded
+   * by track identity and [renderGeneration].
+   */
+  fun render() {
+    val index = surface.currentIndex ?: return
+    val track = surface.currentTrack ?: return
+    renderGeneration += 1
+    val generation = renderGeneration
+
+    // Metadata source. When metadata is disabled, use the raw track (ignore override + formatter);
+    // otherwise the imperative `updateNowPlaying` override wins over the track's own fields.
+    val activeOverride = if (enabled) override else null
+    val defaultTitle = activeOverride?.title ?: track.title
+    val defaultSecondary = activeOverride?.artist ?: track.artist
+    val defaultAlbum = activeOverride?.album ?: track.album
+
+    // A flash outranks both the formatter and the override; while one is active the formatter pass
+    // is skipped entirely so its async result can't land on top.
+    val activeFlash = if (enabled) flash else null
+    if (activeFlash != null) {
+      applyFields(
+        index,
+        track,
+        activeFlash.title ?: defaultTitle,
+        activeFlash.artist ?: defaultSecondary,
+        activeFlash.album ?: defaultAlbum,
+      )
+      return
+    }
+
+    // Apply the default immediately so the now-playing never lags a track/status change.
+    applyFields(index, track, defaultTitle, defaultSecondary, defaultAlbum)
+
+    // If a formatter is configured, let it customize the fields asynchronously. Falls back to the
+    // default on null/throw.
+    val activeFormatter = if (enabled) formatter else null
+    if (activeFormatter != null) {
+      val capturedId = track.src ?: track.url
+      // Gate the raw load-control signal to the buffering state so `stalled` is correct on its
+      // own: ExoPlayer's rebuffering flag is polled on a different cadence than state transitions
+      // and can linger true into the PLAYING transition as a rebuffer recovers. Classify by
+      // connectivity so the formatter can show "offline" vs a plain rebuffer; null when not
+      // stalled.
+      val isStalled = surface.playbackState == PlaybackState.BUFFERING && surface.isRebuffering
+      val stalled =
+        if (isStalled) {
+          if (surface.isOnline) StallReason.BUFFERING else StallReason.OFFLINE
+        } else {
+          null
+        }
+      val params =
+        FormatNowPlayingParams(
+          track,
+          latestTimedMetadata,
+          surface.playWhenReady,
+          stalled,
+          surface.playbackError,
+        )
+      scope.launch {
+        val formatted =
+          try {
+            activeFormatter(params)
+          } catch (e: Exception) {
+            Timber.e(e, "NowPlaying formatter threw; using default")
+            null
+          }
+        // Apply only if still the same track (a fast skip must not be overwritten by a stale
+        // result) AND no newer render superseded this one — without the generation check, a
+        // formatter round-trip in flight when a flash starts lands a beat later and overwrites
+        // the flash (mirrors the iOS renderGeneration guard).
+        val current = surface.currentTrack
+        val currentIdx = surface.currentIndex
+        if (
+          formatted != null &&
+            current != null &&
+            currentIdx != null &&
+            (current.src ?: current.url) == capturedId &&
+            renderGeneration == generation
+        ) {
+          applyFields(
+            currentIdx,
+            current,
+            formatted.title ?: defaultTitle,
+            formatted.artist ?: defaultSecondary,
+            formatted.album ?: defaultAlbum,
+          )
+        }
+      }
+    }
+  }
+
+  /** Stamps the fields via the surface, deduped on (index, track identity, fields). */
+  private fun applyFields(
+    index: Int,
+    track: Track,
+    title: String?,
+    secondaryLine: String?,
+    album: String?,
+  ) {
+    // Skip republishing identical fields. The formatter is re-invoked on every state change, so
+    // the same fields are recomputed often; an unconditional stamp would churn the MediaSession
+    // (and flicker Android Auto / now-playing) for no visible change. Keyed on the track identity
+    // so a new track with a coincidentally identical line still publishes.
+    val published = Published(index, track.src ?: track.url, title, secondaryLine, album)
+    if (published == lastPublished) return
+    lastPublished = published
+
+    surface.stampFields(index, track, title, secondaryLine, album)
+    getNowPlaying()?.let { surface.emitNowPlayingChanged(it) }
+
+    // Resolve the now-playing-only artwork (lock screen / notification / Android Auto
+    // now-playing), keyed on track id so it runs once per track and not on every render.
+    maybeResolveArtwork(track)
+  }
+
+  /**
+   * Resolves the playing track's now-playing artwork and stamps it onto the playing media item.
+   * Guarded exactly like iOS: only when `nowPlayingArtwork` is configured AND the track has a
+   * non-empty id (so the `{id}` token never resolves to an empty string). Otherwise the existing
+   * artworkUri — which came from `artwork` (browse list path) — is left in place.
+   */
+  private fun maybeResolveArtwork(track: Track) {
+    val trackId =
+      track.id?.takeIf { it.isNotEmpty() }
+        ?: run {
+          // No id → skip nowPlayingArtwork entirely; keep the existing (browse) artworkUri.
+          artworkResolvedForTrackId = null
+          return
+        }
+
+    if (!surface.hasNowPlayingArtworkConfig) {
+      // No now-playing artwork config (or no browser) → fall back to the existing artworkUri.
+      artworkResolvedForTrackId = null
+      return
+    }
+
+    // Already resolved (or resolving) for this track id — avoid a redundant resolve per render.
+    if (artworkResolvedForTrackId == trackId) return
+    artworkResolvedForTrackId = trackId
+
+    scope.launch {
+      val uri =
+        surface.resolveNowPlayingArtwork(track, artworkSizePx)?.takeIf { it.isNotEmpty() }
+          ?: return@launch
+
+      // Apply only if still the same track (a fast skip must not be overwritten by a stale
+      // result).
+      val currentIdx = surface.currentIndex ?: return@launch
+      val current = surface.currentTrack ?: return@launch
+      if (current.id != trackId) return@launch
+
+      surface.stampArtwork(currentIdx, current, uri)
+    }
+  }
+}

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

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

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

@@ -4,6 +4,9 @@ import android.content.Context
 import android.content.SharedPreferences
 import androidx.core.content.edit
 import androidx.media3.common.C
+import com.audiobrowser.util.artworkOf
+import com.audiobrowser.util.url
+import com.margelo.nitro.audiobrowser.PlaybackState
 import com.margelo.nitro.audiobrowser.RepeatMode
 import com.margelo.nitro.audiobrowser.Track
 import com.margelo.nitro.audiobrowser.TrackStyle
@@ -96,11 +99,20 @@ class PlaybackStateStore(private val player: Player) {
       }
   }
 
-  /** Stops periodic position saving and saves final position. Call when playback stops. */
-  fun stopPeriodicSave() {
+  /** Cancels the periodic save without a final save. Call on engine teardown. */
+  fun cancelPeriodicSave() {
     periodicSaveJob?.cancel()
     periodicSaveJob = null
-    if (!player.isCurrentItemLive) {
+  }
+
+  /** Stops periodic position saving and saves final position. Call when playback stops. */
+  fun stopPeriodicSave() {
+    cancelPeriodicSave()
+    // Skip the final save after a natural end: setPlaybackState(ENDED) wrote
+    // position 0 for resumption, and the intent-drop's listener echo runs this
+    // strictly afterwards — a save here would overwrite that 0 with the
+    // end-of-track position, making cold-start resume restart at the very end.
+    if (!player.isCurrentItemLive && player.playbackState != PlaybackState.ENDED) {
       savePosition()
     }
   }
@@ -139,13 +151,15 @@ class PlaybackStateStore(private val player: Player) {
   private fun trackToJson(track: Track): String =
     JSONObject()
       .apply {
+        put("id", track.id)
         put("url", track.url)
         put("src", track.src)
         put("title", track.title)
         put("subtitle", track.subtitle)
         put("artist", track.artist)
+        put("albumUrl", track.albumUrl)
         put("album", track.album)
-        put("artwork", track.artwork)
+        put("artwork", track.artwork?.url)
         put("description", track.description)
         put("genre", track.genre)
         put("duration", track.duration)
@@ -161,13 +175,15 @@ class PlaybackStateStore(private val player: Player) {
     runCatching {
         val obj = JSONObject(json)
         Track(
+          id = obj.optString("id").takeIf { it.isNotEmpty() },
           url = obj.optString("url").takeIf { it.isNotEmpty() },
           src = obj.optString("src").takeIf { it.isNotEmpty() },
           title = obj.getString("title"),
           subtitle = obj.optString("subtitle").takeIf { it.isNotEmpty() },
           artist = obj.optString("artist").takeIf { it.isNotEmpty() },
+          albumUrl = obj.optString("albumUrl").takeIf { it.isNotEmpty() },
           album = obj.optString("album").takeIf { it.isNotEmpty() },
-          artwork = obj.optString("artwork").takeIf { it.isNotEmpty() },
+          artwork = artworkOf(obj.optString("artwork").takeIf { it.isNotEmpty() }),
           artworkSource = null, // Not persisted - will be re-transformed on browse
           artworkCarPlayTinted = null, // iOS-only, not persisted
           description = obj.optString("description").takeIf { it.isNotEmpty() },
@@ -189,6 +205,10 @@ class PlaybackStateStore(private val player: Player) {
             else null,
           groupTitle = obj.optString("groupTitle").takeIf { it.isNotEmpty() },
           live = if (obj.has("live") && !obj.isNull("live")) obj.getBoolean("live") else null,
+          // Not persisted: on resumption the contextual URL is re-browsed
+          // (expandQueueFromContextualUrl), which re-parses each track's request
+          // from the API's current response and re-caches it.
+          request = null,
           imageRow = null, // Not persisted
         )
       }