react-native-audio-browser 0.2.0-next.15 → 0.2.0-next.17

package/android/src/main/java/com/audiobrowser/AudioBrowser.kt

@@ -224,7 +224,11 @@ class AudioBrowser : HybridAudioBrowserSpec(), ServiceConnection {
   private var updateOptions: PlayerUpdateOptions = PlayerUpdateOptions()
   private var mediaBrowserFuture: ListenableFuture<MediaBrowser>? = null
   private var setupOptions = PlayerSetupOptions()
-  private var connectedService: Service? = null
+  // Written only on the main thread (ServiceConnection callbacks, dispose); read from main or,
+  // in a few places, straight from the JS thread. @Volatile gives those reads visibility — they
+  // must still tolerate staleness in both directions (a just-detached service, or null while
+  // onServiceConnected is pending). Keep writes on main; no read-modify-write.
+  @Volatile private var connectedService: Service? = null
 
   private val serviceBinding = ServiceBinding(context)
 

package/android/src/main/java/com/audiobrowser/browser/BrowserManager.kt

@@ -359,6 +359,7 @@ class BrowserManager {
           disabled = null,
           favorited = null,
           live = null,
+          icyCharset = null,
         )
       )
     }
@@ -1005,6 +1006,7 @@ class BrowserManager {
           disabled = null,
           favorited = null,
           live = null,
+          icyCharset = null,
         )
 
       // Cache search results for getCachedSearchResults()
@@ -1044,6 +1046,7 @@ class BrowserManager {
           disabled = null,
           favorited = null,
           live = null,
+          icyCharset = null,
         )
 
       return emptySearchResult

package/android/src/main/java/com/audiobrowser/browser/JsonModels.kt

@@ -65,6 +65,7 @@ data class JsonResolvedTrack(
   val style: JsonElement? = null,
   val disabled: Boolean? = null,
   val live: Boolean? = null,
+  val icyCharset: String? = null,
   val carPlaySiriListButton: String? = null,
 )
 
@@ -87,6 +88,7 @@ data class JsonTrack(
   val style: JsonElement? = null,
   val disabled: Boolean? = null,
   val live: Boolean? = null,
+  val icyCharset: String? = null,
 )
 
 /**
@@ -179,6 +181,7 @@ fun JsonResolvedTrack.toNitro(): ResolvedTrack {
     disabled = disabled,
     favorited = null,
     live = live,
+    icyCharset = icyCharset,
   )
 }
 
@@ -202,5 +205,6 @@ fun JsonTrack.toNitro(): Track {
     disabled = disabled,
     favorited = null,
     live = live,
+    icyCharset = icyCharset,
   )
 }

package/android/src/main/java/com/audiobrowser/extension/ResolvedTrackExt.kt

@@ -44,4 +44,5 @@ fun ResolvedTrack.toTrack(): Track =
     disabled = disabled,
     favorited = favorited,
     live = live,
+    icyCharset = icyCharset,
   )

package/android/src/main/java/com/audiobrowser/model/IcyTitle.kt

@@ -0,0 +1,24 @@
+package com.audiobrowser.model
+
+import java.nio.charset.Charset
+
+/** Re-decodes an ICY `StreamTitle` with the charset the track declares. */
+internal object IcyTitle {
+  /**
+   * [title] re-decoded through ISO-8859-1 with [charset] when it is Latin-1 shaped: every char at
+   * or below U+00FF, at least one at or above U+0080. That shape is what media3's ISO-8859-1
+   * fallback yields for bytes that are not UTF-8, and also what a station that UTF-8-encoded its
+   * legacy bytes yields; ISO-8859-1 is lossless, so both re-decode. Returns [title] as is when it
+   * has another shape, is pure ASCII, or [charset] is not one the runtime can decode with.
+   */
+  fun redecode(title: String, charset: String): String {
+    var high = false
+    for (c in title) {
+      if (c.code > 0xFF) return title
+      if (c.code >= 0x80) high = true
+    }
+    if (!high) return title
+    val cs = runCatching { Charset.forName(charset) }.getOrNull() ?: return title
+    return String(title.toByteArray(Charsets.ISO_8859_1), cs)
+  }
+}

package/android/src/main/java/com/audiobrowser/model/PlaybackMetadata.kt

@@ -15,11 +15,12 @@ data class PlaybackMetadata(
   companion object {
     /**
      * Creates PlaybackMetadata from raw Metadata entries. Handles ICY streams specially, uses
-     * Media3's unified approach for everything else.
+     * Media3's unified approach for everything else. [icyCharset] is the track's declared charset
+     * for ICY titles media3 decoded as Latin-1; it never touches other metadata.
      */
-    fun from(metadata: Metadata): PlaybackMetadata? {
+    fun from(metadata: Metadata, icyCharset: String? = null): PlaybackMetadata? {
       // Try ICY first (streaming-specific)
-      fromIcy(metadata)?.let {
+      fromIcy(metadata, icyCharset)?.let {
         return it
       }
 
@@ -32,12 +33,15 @@ data class PlaybackMetadata(
     }
 
     /** Shoutcast / Icecast metadata (ICY protocol) https://cast.readme.io/docs/icy */
-    private fun fromIcy(metadata: Metadata): PlaybackMetadata? {
+    private fun fromIcy(metadata: Metadata, icyCharset: String?): PlaybackMetadata? {
       for (i in 0 until metadata.length()) {
         when (val entry = metadata[i]) {
           is IcyInfo -> {
-            if (entry.title != null) {
-              return PlaybackMetadata(title = entry.title)
+            val title = entry.title
+            if (title != null) {
+              return PlaybackMetadata(
+                title = icyCharset?.let { IcyTitle.redecode(title, it) } ?: title
+              )
             }
           }
         }

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

@@ -45,8 +45,12 @@ import kotlinx.coroutines.withContext
 import timber.log.Timber
 
 /**
- * MediaLibrarySession callback that handles all media session interactions. All logic is handled
- * directly by the AudioBrowser.
+ * Everything the MediaLibrarySession serves except transport: browse, search, item lookup, queue
+ * building, playback resumption, and the favorite and rating commands. Transport does not arrive
+ * here — it reaches the player through [InterceptingPlayer], and Assistant's play-from-search
+ * arrives as an intent handled in the service. The callbacks that answer through [scope] run on IO,
+ * so anything touching the ExoPlayer instance hops back to [Dispatchers.Main]; the rest answer
+ * synchronously on the Media3 application thread.
  */
 class MediaSessionCallback(private val player: Player) :
   MediaLibraryService.MediaLibrarySession.Callback {
@@ -69,14 +73,10 @@ class MediaSessionCallback(private val player: Player) :
     private set
 
   init {
-    // Observe network state changes and notify subscribers
     player.networkMonitor.observeOnline(scope) { _ -> notifySubscribedChildrenChanged() }
   }
 
-  /**
-   * Apply pagination to a list of items. If pageSize is 0 or MAX_VALUE (Android Auto default),
-   * returns the full list.
-   */
+  /** Media3's legacy browse bridge asks for a whole list with pageSize [Int.MAX_VALUE]. */
   private fun <T> List<T>.paginate(page: Int, pageSize: Int): List<T> {
     return if (pageSize in 1 until Int.MAX_VALUE) {
       this.drop(page * pageSize).take(pageSize)
@@ -85,7 +85,6 @@ class MediaSessionCallback(private val player: Player) :
     }
   }
 
-  /** Creates an offline error MediaItem. */
   private fun createOfflineMediaItem(): MediaItem =
     createErrorMediaItem(
       mediaId = BrowserPathHelper.OFFLINE_PATH,
@@ -99,6 +98,12 @@ class MediaSessionCallback(private val player: Player) :
    * Auto / AAOS browse list. Rendered as a greyed-out, non-interactive tile, which is the only
    * side-effect-free way to communicate a browse failure to legacy controllers (Media3 drops
    * [LibraryResult.ofError] on the legacy browse bridge, leaving an empty "No items" screen).
+   *
+   * Tiles are the only in-browse error signal that exists. Verified on a head unit (2026-06): the
+   * Android Auto browse list renders no error text for a transient [SessionError], for sticky
+   * non-fatal replication, or for fatal replication (setLibraryErrorReplicationMode). Fatal
+   * replication does surface the message on the playback screen, but at the cost of presenting the
+   * session as STATE_ERROR with no actions, hiding the now-playing item and transport controls.
    */
   private fun createErrorMediaItem(mediaId: String, title: String, subtitle: String): MediaItem =
     MediaItem.Builder()
@@ -107,23 +112,15 @@ class MediaSessionCallback(private val player: Player) :
         MediaMetadata.Builder()
           .setTitle(title)
           .setSubtitle(subtitle)
-          // Non-browsable, non-playable. Android Auto ignores these flags and still drills into a
-          // tapped tile, but onGetChildren returns an empty list for the sentinel paths so it's a
-          // harmless "No Items" dead-end rather than an endless stack of error pages.
+          // Android Auto ignores these flags and drills into a tapped tile anyway; onGetChildren
+          // returns an empty list for the sentinel paths, so it dead-ends at "No Items" rather
+          // than stacking error pages.
           .setIsBrowsable(false)
           .setIsPlayable(false)
           .build()
       )
       .build()
 
-  /**
-   * Builds the gate tile from a per-request chrome: while a gate is active, tabs stay visible but a
-   * gated browse/search level serves this single tile (see the gate checks in [onGetChildren] /
-   * [onGetSearchResult]). Same shape as the error tiles — non-browsable, non-playable — and
-   * deliberately NOT accompanied by a SessionError: a gate is deliberate app state, not a failure.
-   * The message renders as the tile's subtitle (newlines collapse to spaces — list rows are
-   * single-line).
-   */
   /**
    * Wraps a raw external-search query string into the structured [SearchParams] the gate request
    * carries. The car search surfaces only give a free-text query, so the other fields stay null —
@@ -141,6 +138,14 @@ class MediaSessionCallback(private val player: Player) :
       reference = MediaReference.UNKNOWN,
     )
 
+  /**
+   * Builds the gate tile from a per-request chrome: while a gate is active, tabs stay visible but a
+   * gated browse/search level serves this single tile (see the gate checks in [onGetChildren] /
+   * [onGetSearchResult]). Same shape as the error tiles — non-browsable, non-playable — and
+   * deliberately NOT accompanied by a SessionError: a gate is deliberate app state, not a failure.
+   * The message renders as the tile's subtitle (newlines collapse to spaces — list rows are
+   * single-line).
+   */
   private fun createGateMediaItem(gate: Gate): MediaItem =
     createErrorMediaItem(
       mediaId = BrowserPathHelper.GATE_PATH,
@@ -150,7 +155,7 @@ class MediaSessionCallback(private val player: Player) :
 
   /**
    * Builds a generic "something went wrong" error tile for a browse failure. The true offline case
-   * is handled separately by the [networkMonitor] guard in [onGetChildren]; anything reaching the
+   * is handled separately by the networkMonitor guard in [onGetChildren]; anything reaching the
    * catch block is an online-but-failed request (e.g. server down, bad status), so it must NOT be
    * labelled "no internet connection".
    */
@@ -170,7 +175,6 @@ class MediaSessionCallback(private val player: Player) :
     forwardJumpInterval: Double,
     backwardJumpInterval: Double,
   ) {
-    // Store as MediaLibrarySession for notifyChildrenChanged support
     this.mediaLibrarySession = mediaSession as? MediaLibraryService.MediaLibrarySession
     commandManager.updateMediaSession(
       mediaSession,
@@ -196,9 +200,8 @@ class MediaSessionCallback(private val player: Player) :
     command: SessionCommand,
     args: Bundle,
   ): ListenableFuture<SessionResult> {
-    // Handle favorite button tap. Report an honest result: a success here makes
-    // the controller flip its heart optimistically, so a no-op (no current
-    // track) must say INVALID_STATE instead of success-then-revert.
+    // A success here makes the controller flip its heart optimistically, so a no-op (no current
+    // track) must report INVALID_STATE instead of success-then-revert.
     if (command.customAction == MediaSessionCommandManager.CUSTOM_ACTION_FAVORITE) {
       val applied = player.toggleActiveTrackFavorited()
       Timber.d("Favorite button tapped - toggle applied=$applied")
@@ -241,13 +244,6 @@ class MediaSessionCallback(private val player: Player) :
     browser: MediaSession.ControllerInfo,
     params: MediaLibraryService.LibraryParams?,
   ): ListenableFuture<LibraryResult<MediaItem>> {
-    // Extract artwork size hint from root hints (e.g., from Android Auto)
-    // TODO: Also consider these other root hints in the future:
-    // - KEY_ROOT_HINT_MEDIA_HOST_VERSION
-    // - KEY_ROOT_HINT_MEDIA_SESSION_API
-    // - BROWSER_ROOT_HINTS_KEY_CUSTOM_BROWSER_ACTION_LIMIT
-    // - BROWSER_ROOT_HINTS_KEY_ROOT_CHILDREN_LIMIT
-    // - KEY_ROOT_HINT_MAX_QUEUE_ITEMS_WHILE_RESTRICTED
     params?.extras?.getInt(MediaConstants.EXTRAS_KEY_MEDIA_ART_SIZE_PIXELS, 0)?.let { size ->
       if (size > 0) {
         artworkSizeHintPixels = size
@@ -290,7 +286,6 @@ class MediaSessionCallback(private val player: Player) :
       "onGetChildren: {parentId: $parentId, page: $page, pageSize: $pageSize, isSpecialPath: ${BrowserPathHelper.isSpecialPath(parentId)} }"
     )
     return scope.future {
-      // Wait for browser to be registered if it's not available yet
       val audioBrowser =
         player.awaitBrowser().also { Timber.d("Browser ready, proceeding with onGetChildren") }
       val browserManager = audioBrowser.browserManager
@@ -330,7 +325,6 @@ class MediaSessionCallback(private val player: Player) :
         return@future LibraryResult.ofItemList(ImmutableList.of<MediaItem>(), params)
       }
 
-      // Show offline error when offline:
       if (
         !player.networkMonitor.isOnline.value && browserManager.config.androidControllerOfflineError
       ) {
@@ -342,10 +336,8 @@ class MediaSessionCallback(private val player: Player) :
       try {
         val children =
           if (parentId == BrowserPathHelper.ROOT_PATH) {
-            // Return tabs as root children (limited to 4 for automotive platform compatibility)
-            // TODO: Check what Android Auto does with empty tabs list - may need to return error?
-            // Disabled tabs hide (Track.disabled) — filtered before the cap so
-            // an unavailable tab never costs an available one its slot.
+            // Disabled tabs hide (Track.disabled) — filtered before the four-tab cap so an
+            // unavailable tab never costs an available one its slot.
             val tabs = browserManager.queryTabs().filterNot { it.disabled == true }
             if (tabs.size > 4) {
               Timber.w(
@@ -354,9 +346,7 @@ class MediaSessionCallback(private val player: Player) :
             }
             toFlatMediaItems(tabs.take(4))
           } else {
-            // Resolve the specific path and flatten its sections to MediaItems
-            // (paths are already set to contextual paths). Section styles come
-            // page-folded (`section ?? page`, ADR 0011).
+            // Section styles arrive page-folded (`section ?? page`, ADR 0011).
             val resolvedTrack = browserManager.resolve(parentId)
             val sections =
               resolvedTrack.styleResolvedSections()
@@ -371,16 +361,8 @@ class MediaSessionCallback(private val player: Player) :
         // error tile. awaitBrowser's TimeoutCancellationException IS a real failure, keep that.
         if (e is CancellationException && e !is TimeoutCancellationException) throw e
         Timber.e(e, "Error getting children for parentId: $parentId")
-        // Surface an error tile instead of a bare ofError(): Media3 drops the error message on the
-        // legacy browse bridge, which would otherwise leave an empty "No items" screen in Android
-        // Auto. See https://github.com/androidx/media/issues/2901
-        //
-        // Verified on a head unit (2026-06): the AA browse list NEVER renders error text — not for
-        // transient sendError, sticky non-fatal replication, or fatal replication
-        // (setLibraryErrorReplicationMode). Fatal replication does show the message on the
-        // playback screen, but presents the session as STATE_ERROR with no actions, hiding the
-        // now-playing item and transport controls — not worth it. Tiles remain the only in-browse
-        // signal we control.
+        // A tile rather than a bare ofError() — see createErrorMediaItem and
+        // https://github.com/androidx/media/issues/2901
         sendBrowseError(session, browser, offline = false)
         LibraryResult.ofItemList(ImmutableList.of(createBrowseErrorMediaItem()), params)
       }
@@ -393,8 +375,8 @@ class MediaSessionCallback(private val player: Player) :
    * Media3 transiently attaches the error code/message to the platform session's playback state
    * without entering STATE_ERROR.
    *
-   * NOTE: current Android Auto renders NOTHING for this (verified on a head unit — see
-   * androidx/media#2901; the transient state is cleared microseconds after being set). It is kept
+   * NOTE: current Android Auto renders nothing for this — its transient state is cleared
+   * microseconds after being set (see [createErrorMediaItem], androidx/media#2901). It is kept
    * because it is the correct Media3-API error signal, costs nothing, and becomes user-visible if
    * Android Auto moves to consuming SessionError via the Media3 controller API.
    *
@@ -462,13 +444,12 @@ class MediaSessionCallback(private val player: Player) :
   ): ListenableFuture<LibraryResult<MediaItem>> {
     Timber.Forest.d("onGetItem: ${browser.packageName}, mediaId = $mediaId")
     return scope.future {
-      // Handle special paths first (these don't need browser)
+      // Offline, error and root answer ahead of awaitBrowser: they need no browser. The gate
+      // sentinel below still does, for gateDecision.
       if (mediaId == BrowserPathHelper.OFFLINE_PATH) {
         return@future LibraryResult.ofItem(createOfflineMediaItem(), null)
       }
 
-      // Return the error tile as a non-browsable item so tapping it can't re-browse into a
-      // failing path (which would push another error page onto the stack).
       if (mediaId == BrowserPathHelper.ERROR_PATH) {
         return@future LibraryResult.ofItem(createBrowseErrorMediaItem(), null)
       }
@@ -503,7 +484,6 @@ class MediaSessionCallback(private val player: Player) :
         )
       }
 
-      // Wait for browser to be registered if it's not available yet
       val browserManager = player.awaitBrowser().browserManager
 
       // Serve tracks from the track cache first (keyed by path and src). Besides avoiding an HTTP
@@ -578,9 +558,6 @@ class MediaSessionCallback(private val player: Player) :
   }
 
   /**
-   * Notifies all subscribed controllers to refresh their content. Called internally when network
-   * state changes to refresh all subscribed paths.
-   *
    * Safe to call from any thread: snapshots the subscribed paths and dispatches the session calls
    * to the main (Media3 application) thread.
    */
@@ -593,10 +570,8 @@ class MediaSessionCallback(private val player: Player) :
   }
 
   /**
-   * Notifies external controllers that content at the given path has changed. Controllers
-   * subscribed to this path will refresh their UI. Safe to call from any thread.
-   *
-   * @param path The path where content has changed
+   * Notifies external controllers that content at the given path has changed, so controllers
+   * subscribed to it refresh their UI. Safe to call from any thread.
    */
   fun notifyContentChanged(path: String) {
     Timber.d("Notifying content changed for path: $path")
@@ -614,10 +589,6 @@ class MediaSessionCallback(private val player: Player) :
     notifySubscribedChildrenChanged()
   }
 
-  /**
-   * Called when the browser becomes available after a cold start. Notifies all subscribed
-   * controllers to refresh their content.
-   */
   fun notifyBrowserReady() {
     Timber.d("Browser ready - notifying all subscribed paths")
     notifySubscribedChildrenChanged()
@@ -636,8 +607,6 @@ class MediaSessionCallback(private val player: Player) :
   ): ListenableFuture<LibraryResult<Void>> {
     Timber.d("onSearch: ${browser.packageName}, query = $query")
     return scope.future {
-      // Wait for browser registration like onGetChildren does, so a cold-start voice search
-      // doesn't fail before JS has configured the browser.
       val audioBrowser =
         try {
           player.awaitBrowser()
@@ -659,14 +628,14 @@ class MediaSessionCallback(private val player: Player) :
         return@future LibraryResult.ofVoid()
       }
 
-      // Check if search is configured
       if (!browserManager.config.hasSearch) {
         Timber.w("Search requested but no search source configured")
         return@future LibraryResult.ofError(SessionError.ERROR_NOT_SUPPORTED)
       }
 
       try {
-        // Execute search (automatically caches results at /__search?q=query)
+        // Caches the result set under the query, which onGetSearchResult reads back through
+        // getCachedSearchResults.
         val searchResults = browserManager.search(query)
         // Count what onGetSearchResult will actually serve: disabled tracks
         // hide on Android Auto, so they must not inflate the announced count.
@@ -677,7 +646,6 @@ class MediaSessionCallback(private val player: Player) :
 
         Timber.d("Search completed: $resultCount results for query '$query'")
 
-        // Notify Media3 of search results
         session.notifySearchResultChanged(browser, query, resultCount, params)
 
         LibraryResult.ofVoid()
@@ -724,10 +692,7 @@ class MediaSessionCallback(private val player: Player) :
       }
 
       try {
-        // Get cached search results from BrowserManager
         browserManager.getCachedSearchResults(query)?.let { tracks ->
-          // Through the shared browse conversion, so search results get the
-          // same artwork routing as browse rows.
           val mediaItems = toFlatMediaItems(tracks.toList())
 
           val paginatedItems = mediaItems.paginate(page, pageSize)
@@ -766,8 +731,9 @@ class MediaSessionCallback(private val player: Player) :
     return scope.future {
       val audioBrowser = player.awaitBrowser()
 
-      // Helper: returns the current player state unchanged so Media3 doesn't modify playback.
-      // ExoPlayer is main-thread confined; this future runs on IO, so hop to Main for the reads.
+      // The "leave playback alone" answer for handleTrackLoad: returning the current state
+      // unchanged is how Media3 is told to do nothing. ExoPlayer is main-thread confined and this
+      // future runs on IO, so the reads hop to Main.
       suspend fun currentPlayerState(): MediaSession.MediaItemsWithStartPosition =
         withContext(Dispatchers.Main) {
           val currentItems = player.tracks.map { TrackFactory.toMedia3(it) }
@@ -788,14 +754,12 @@ class MediaSessionCallback(private val player: Player) :
           ?.takeIf { it.requestMetadata.searchQuery == null }
           ?.let { browserManager.contextualPathFor(it.mediaId) }
 
-      // Check if this is a single item from the current queue source
       if (singleContextualPath != null) {
         val parentPath = BrowserPathHelper.stripTrackId(singleContextualPath)
         val trackId = BrowserPathHelper.extractTrackId(singleContextualPath)
 
-        // Check if queue already came from this parent path - just skip to the
-        // tapped surface (exact path first, identity for index-less paths —
-        // see indexOfTappedTrack)
+        // A tap inside the queue's own source list skips rather than rebuilds (exact path first,
+        // identity for index-less paths — see indexOfTappedTrack).
         if (trackId != null && parentPath == player.queueSourcePath) {
           val queueTracks = withContext(Dispatchers.Main) { player.tracks }
           val index = queueTracks.indexOfTappedTrack(singleContextualPath, trackId)
@@ -809,7 +773,6 @@ class MediaSessionCallback(private val player: Player) :
               index.toDouble(),
               ::currentPlayerState,
             ) {
-              // Return the existing queue items with the new start index
               val existingItems = queueTracks.map { TrackFactory.toMedia3(it) }
               MediaSession.MediaItemsWithStartPosition(existingItems, index, startPositionMs)
             }
@@ -830,8 +793,8 @@ class MediaSessionCallback(private val player: Player) :
         result.startIndex.toDouble(),
         ::currentPlayerState,
       ) {
-        // If this was a contextual path expansion, track the source path (only for default
-        // behavior)
+        // Inside handleTrackLoad's default branch: a consumer that handles the load itself owns
+        // the queue, so queueSourcePath must not claim this path on its behalf.
         if (singleContextualPath != null) {
           val parentPath = BrowserPathHelper.stripTrackId(singleContextualPath)
           withContext(Dispatchers.Main) { player.queueSourcePath = parentPath }
@@ -849,8 +812,6 @@ class MediaSessionCallback(private val player: Player) :
    * using the browse callback. This enables seamless resumption after app restart with the same
    * player settings (repeat mode, shuffle, playback speed).
    *
-   * @param mediaSession The media session
-   * @param controller The controller requesting resumption
    * @param isForPlayback True if this should start playback; false if just gathering info for the
    *   boot-time resumption notification (no network; local metadata only).
    * @see https://developer.android.com/media/media3/session/background-playback#resumption
@@ -881,9 +842,8 @@ class MediaSessionCallback(private val player: Player) :
         throw IllegalStateException("Persisted track is disabled")
       }
 
-      // isForPlayback == false is the device-boot-time notification case: network may be
-      // unavailable and we must not start playback. Return just the locally-stored track with its
-      // already-local metadata; skip the settings restore and network queue expansion below.
+      // Info-gathering returns before the settings restore and the queue expansion below: both
+      // touch the live player or the network, and neither is permitted here.
       if (!isForPlayback) {
         Timber.d("Info-gathering resumption (boot-time); returning stored track without expansion")
         return@future MediaSession.MediaItemsWithStartPosition(
@@ -899,10 +859,8 @@ class MediaSessionCallback(private val player: Player) :
       val path = state.track.path
       Timber.d("Resuming from path=$path, positionMs=${state.positionMs}")
 
-      // Wait for browser to be available (JS needs to have configured it)
       val browserManager = player.awaitBrowser().browserManager
 
-      // Try to expand the path into a full queue
       val expanded = path?.let { browserManager.expandQueueFromContextualPath(it) }
 
       if (expanded != null) {
@@ -911,7 +869,6 @@ class MediaSessionCallback(private val player: Player) :
           "Restored ${tracks.size} tracks, starting at index $selectedIndex at ${state.positionMs}ms"
         )
 
-        // Track the source path if this was a contextual path expansion
         if (BrowserPathHelper.isContextual(path)) {
           val parentPath = BrowserPathHelper.stripTrackId(path)
           withContext(Dispatchers.Main) { player.queueSourcePath = parentPath }
@@ -923,7 +880,6 @@ class MediaSessionCallback(private val player: Player) :
           state.positionMs,
         )
       } else {
-        // Fallback: play just the stored track
         Timber.d("Queue expansion failed, using stored track: ${state.track.title}")
         MediaSession.MediaItemsWithStartPosition(
           ImmutableList.of(TrackFactory.toMedia3(state.track)),

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

@@ -233,6 +233,7 @@ class PlaybackStateStore(private val player: Player) {
           put("disabled", track.disabled)
           put("favorited", track.favorited)
           put("live", track.live)
+          put("icyCharset", track.icyCharset)
         }
         .toString()
 
@@ -281,6 +282,7 @@ class PlaybackStateStore(private val player: Player) {
               if (obj.has("favorited") && !obj.isNull("favorited")) obj.getBoolean("favorited")
               else null,
             live = if (obj.has("live") && !obj.isNull("live")) obj.getBoolean("live") else null,
+            icyCharset = obj.optString("icyCharset").takeIf { it.isNotEmpty() },
             // Not persisted: on resumption the contextual path is re-browsed
             // (expandQueueFromContextualPath), which re-parses each track's request
             // from the API's current response and re-caches it.

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

@@ -59,7 +59,7 @@ class PlayerListener(private val player: Player) : MediaPlayer.Listener {
     }
 
     // Extract and emit timed metadata (ICY, ID3, etc.)
-    PlaybackMetadata.from(metadata)?.let {
+    PlaybackMetadata.from(metadata, player.currentTrack?.icyCharset)?.let {
       val timed = it.toNitro()
       player.callbacks?.onTimedMetadata(timed)
       player.nowPlaying.onTimedMetadataReceived(timed)

package/android/src/main/java/com/audiobrowser/util/TrackFactory.kt

@@ -64,6 +64,7 @@ object TrackFactory {
       disabled = null,
       favorited = null,
       live = null,
+      icyCharset = null,
     )
 
   fun toMedia3(tracks: Array<Track>): List<MediaItem> {

package/android/src/test/java/com/audiobrowser/TestFixtures.kt

@@ -55,6 +55,7 @@ object TestFixtures {
       disabled = disabled,
       favorited = favorited,
       live = null,
+      icyCharset = null,
     )
 
   /** A page [Section] — plain list by default. */
@@ -136,6 +137,7 @@ object TestFixtures {
       disabled = null,
       favorited = null,
       live = null,
+      icyCharset = null,
     )
 
   /** A container [ResolvedTrack] — what a browse route hands back for a path. */
@@ -168,6 +170,7 @@ object TestFixtures {
       disabled = null,
       favorited = null,
       live = null,
+      icyCharset = null,
     )
 
   /**

package/android/src/test/java/com/audiobrowser/model/IcyTitleTest.kt

@@ -0,0 +1,49 @@
+package com.audiobrowser.model
+
+import java.nio.charset.Charset
+import org.junit.Assert.assertEquals
+import org.junit.Test
+
+class IcyTitleTest {
+  /** What media3's ISO-8859-1 fallback yields for [text] sent as [charset]. */
+  private fun latin1Shaped(text: String, charset: String) =
+    String(text.toByteArray(Charset.forName(charset)), Charsets.ISO_8859_1)
+
+  @Test
+  fun `re-decodes a legacy code page title`() {
+    val title = latin1Shaped("Артист - Песня", "windows-1251")
+    assertEquals("Артист - Песня", IcyTitle.redecode(title, "windows-1251"))
+  }
+
+  @Test
+  fun `re-decodes thai`() {
+    val title = latin1Shaped("ศิลปิน - เพลง", "windows-874")
+    assertEquals("ศิลปิน - เพลง", IcyTitle.redecode(title, "windows-874"))
+  }
+
+  @Test
+  fun `re-decodes a title the station utf-8 encoded from legacy bytes`() {
+    // media3 decodes the valid UTF-8 to the same Latin-1-shaped string the fallback would give.
+    val doubleEncoded = latin1Shaped("Artist - เพลง", "windows-874").toByteArray(Charsets.UTF_8)
+    assertEquals(
+      "Artist - เพลง",
+      IcyTitle.redecode(String(doubleEncoded, Charsets.UTF_8), "windows-874"),
+    )
+  }
+
+  @Test
+  fun `leaves a title already in another script`() {
+    assertEquals("Песня", IcyTitle.redecode("Песня", "windows-1251"))
+  }
+
+  @Test
+  fun `leaves ascii`() {
+    assertEquals("Plain Title", IcyTitle.redecode("Plain Title", "windows-1251"))
+  }
+
+  @Test
+  fun `ignores a charset the runtime cannot decode with`() {
+    val title = latin1Shaped("Песня", "windows-1251")
+    assertEquals(title, IcyTitle.redecode(title, "no-such-charset"))
+  }
+}

package/ios/Browser/BrowserManager.swift

@@ -738,6 +738,7 @@ final class BrowserManager {
       disabled: nil,
       favorited: nil,
       live: nil,
+      icyCharset: nil,
     )
   }