react-native-nitro-player 1.7.0-alpha.4 → 1.7.0-alpha.5

package/android/src/main/java/com/margelo/nitro/nitroplayer/download/DownloadDatabase.kt

@@ -1,6 +1,7 @@
 package com.margelo.nitro.nitroplayer.download
 
 import android.content.Context
+import com.margelo.nitro.JNIOnLoad
 import com.margelo.nitro.core.AnyMap
 import com.margelo.nitro.core.NullType
 import com.margelo.nitro.nitroplayer.*
@@ -56,6 +57,8 @@ class DownloadDatabase private constructor(
     private val ioScope = CoroutineScope(Dispatchers.IO.limitedParallelism(1) + SupervisorJob())
 
     init {
+        // Persisted extraPayloads are AnyMaps; a process started without JS has not loaded Nitro's JNI yet
+        JNIOnLoad.initializeNativeNitro()
         loadFromDisk()
     }
 

package/android/src/main/java/com/margelo/nitro/nitroplayer/download/TrackItemJson.kt

@@ -1,5 +1,6 @@
 package com.margelo.nitro.nitroplayer.download
 
+import com.margelo.nitro.JNIOnLoad
 import com.margelo.nitro.core.AnyMap
 import com.margelo.nitro.nitroplayer.TrackItem
 import com.margelo.nitro.nitroplayer.Variant_NullType_String
@@ -8,6 +9,11 @@ import org.json.JSONObject
 // Survives process death inside the worker's inputData so a completed
 // download can be recorded even when the in-memory metadata maps are gone.
 internal object TrackItemJson {
+    // extraPayload is an AnyMap; downloads can run in a process JS never started
+    init {
+        JNIOnLoad.initializeNativeNitro()
+    }
+
     fun toJson(track: TrackItem): String =
         JSONObject()
             .apply {

package/android/src/main/java/com/margelo/nitro/nitroplayer/media/CastSessionController.kt

@@ -35,6 +35,8 @@ class CastSessionController(
     private val castContext: CastContext,
     val castPlayer: CastPlayer,
     val localPlayer: Player,
+    /** What the session drives locally — wraps [localPlayer] to route remote commands through the core. */
+    val localSessionPlayer: Player,
     val mediaSession: MediaSession,
     private val mainHandler: Handler,
 ) {

package/android/src/main/java/com/margelo/nitro/nitroplayer/media/MediaBrowserService.kt

@@ -7,11 +7,13 @@ import android.net.Uri
 import android.os.Bundle
 import android.support.v4.media.MediaBrowserCompat
 import android.support.v4.media.MediaDescriptionCompat
+import android.support.v4.media.session.MediaSessionCompat
 import androidx.media.MediaBrowserServiceCompat
 import androidx.media.utils.MediaConstants
 import com.margelo.nitro.nitroplayer.TrackItem
 import com.margelo.nitro.nitroplayer.core.NitroPlayerLogger
 import com.margelo.nitro.nitroplayer.core.TrackPlayerCore
+import com.margelo.nitro.nitroplayer.core.onAndroidAutoBrowserConnected
 import com.margelo.nitro.nitroplayer.playlist.Playlist
 import kotlinx.coroutines.CoroutineScope
 import kotlinx.coroutines.Dispatchers
@@ -22,45 +24,59 @@ import kotlinx.coroutines.launch
 class NitroPlayerMediaBrowserService : MediaBrowserServiceCompat() {
     companion object {
         private const val ROOT_ID = "root"
-        private const val EMPTY_ROOT_ID = "empty_root"
         private const val PLAYLIST_PREFIX = "playlist_"
+        private const val ANDROID_AUTO_PACKAGE = "com.google.android.projection.gearhead"
+        private const val PREFS_NAME = "NitroPlayerAndroidAuto"
+        private const val KEY_ENABLED = "enabled"
+        private const val KEY_SEARCH = "search"
 
-        var trackPlayerCore: TrackPlayerCore? = null
-        var mediaSessionManager: MediaSessionManager? = null
-        var isAndroidAutoEnabled: Boolean = false
         var isAndroidAutoConnected: Boolean = false
 
         @Volatile
         private var instance: NitroPlayerMediaBrowserService? = null
 
         fun getInstance(): NitroPlayerMediaBrowserService? = instance
+
+        // Persisted so a cold start from the car, before JS runs configure, still serves the library
+        fun setAndroidAutoEnabled(
+            context: Context,
+            enabled: Boolean,
+        ) {
+            prefs(context).edit().putBoolean(KEY_ENABLED, enabled).apply()
+            instance?.onPlaylistsUpdated()
+        }
+
+        // Persisted too: the car reads the root (and hides search for the whole connection) before JS registers a handler
+        fun setSearchSupported(
+            context: Context,
+            supported: Boolean,
+        ) {
+            prefs(context).edit().putBoolean(KEY_SEARCH, supported).apply()
+        }
+
+        private fun prefs(context: Context) = context.getSharedPreferences(PREFS_NAME, Context.MODE_PRIVATE)
     }
 
     private val serviceScope = CoroutineScope(Dispatchers.Main + SupervisorJob())
     private lateinit var mediaLibraryManager: MediaLibraryManager
+    private lateinit var core: TrackPlayerCore
+
+    private val isAndroidAutoEnabled: Boolean
+        get() = prefs(this).getBoolean(KEY_ENABLED, false)
 
     override fun onCreate() {
         super.onCreate()
 
         instance = this
         mediaLibraryManager = MediaLibraryManager.getInstance(applicationContext)
-
-        // Use the existing MediaSession from MediaSessionManager
-        // This ensures the session is already connected to the ExoPlayer
-        try {
-            val session = mediaSessionManager?.mediaSession
-            if (session != null) {
-                // Convert Media3 MediaSession to MediaSessionCompat for MediaBrowserService
-                sessionToken =
-                    android.support.v4.media.session.MediaSessionCompat.Token
-                        .fromToken(session.platformToken)
-                NitroPlayerLogger.log("MediaBrowserService", "🎵 NitroPlayerMediaBrowserService: MediaSession token set successfully")
-            } else {
-                NitroPlayerLogger.log("MediaBrowserService", "⚠️ NitroPlayerMediaBrowserService: MediaSession not available yet")
-            }
-        } catch (e: Exception) {
-            NitroPlayerLogger.log("MediaBrowserService", "❌ NitroPlayerMediaBrowserService: Error setting session token - ${e.message}")
-            e.printStackTrace()
+        mediaLibraryManager.onLateChildren = { parentId -> notifyChildrenChanged(parentId) }
+
+        // A cold start has no session yet; the connection stays pending until the token is set
+        core = TrackPlayerCore.getInstance(applicationContext)
+        serviceScope.launch {
+            val token = core.withPlayerContext { core.mediaSessionManager?.mediaSession?.platformToken } ?: return@launch
+            if (sessionToken == null) sessionToken = MediaSessionCompat.Token.fromToken(token)
+            NitroPlayerLogger.log("MediaBrowserService", "🎵 NitroPlayerMediaBrowserService: MediaSession token set")
         }
 
         NitroPlayerLogger.log("MediaBrowserService", "🚀 NitroPlayerMediaBrowserService: Service created")
@@ -69,6 +85,7 @@ class NitroPlayerMediaBrowserService : MediaBrowserServiceCompat() {
     override fun onDestroy() {
         super.onDestroy()
         instance = null
+        mediaLibraryManager.onLateChildren = null
         serviceScope.cancel()
         NitroPlayerLogger.log("MediaBrowserService", "🛑 NitroPlayerMediaBrowserService: Service destroyed")
     }
@@ -77,25 +94,27 @@ class NitroPlayerMediaBrowserService : MediaBrowserServiceCompat() {
         clientPackageName: String,
         clientUid: Int,
         rootHints: Bundle?,
-    ): BrowserRoot? {
+    ): BrowserRoot {
         NitroPlayerLogger.log("MediaBrowserService", "📂 NitroPlayerMediaBrowserService: onGetRoot called from $clientPackageName")
 
-        // Check if Android Auto is enabled
-        if (!isAndroidAutoEnabled) {
-            NitroPlayerLogger.log("MediaBrowserService", "⚠️ NitroPlayerMediaBrowserService: Android Auto not enabled")
-            return BrowserRoot(EMPTY_ROOT_ID, null)
-        }
+        if (clientPackageName == ANDROID_AUTO_PACKAGE) core.onAndroidAutoBrowserConnected()
 
-        // Allow Android Auto and other media browsers to connect
-        // Enable grid layout for playlists at root level
+        // Always the real root: enabling later only has to refresh it, not reconnect the car
         val extras =
             Bundle().apply {
                 putInt(
                     MediaConstants.DESCRIPTION_EXTRAS_KEY_CONTENT_STYLE_BROWSABLE,
                     MediaConstants.DESCRIPTION_EXTRAS_VALUE_CONTENT_STYLE_GRID_ITEM,
                 )
+                putInt(
+                    MediaConstants.DESCRIPTION_EXTRAS_KEY_CONTENT_STYLE_PLAYABLE,
+                    MediaConstants.DESCRIPTION_EXTRAS_VALUE_CONTENT_STYLE_LIST_ITEM,
+                )
+                putBoolean(
+                    MediaConstants.BROWSER_SERVICE_EXTRAS_KEY_SEARCH_SUPPORTED,
+                    prefs(this@NitroPlayerMediaBrowserService).getBoolean(KEY_SEARCH, false),
+                )
             }
-        NitroPlayerLogger.log("MediaBrowserService", "✅ NitroPlayerMediaBrowserService: Allowing connection from $clientPackageName with grid layout")
         return BrowserRoot(ROOT_ID, extras)
     }
 
@@ -104,6 +123,7 @@ class NitroPlayerMediaBrowserService : MediaBrowserServiceCompat() {
         result: Result<MutableList<MediaBrowserCompat.MediaItem>>,
     ) {
         NitroPlayerLogger.log("MediaBrowserService", "📂 NitroPlayerMediaBrowserService: onLoadChildren called for parentId: $parentId")
+        startJsOnDemand()
 
         if (!isAndroidAutoEnabled) {
             NitroPlayerLogger.log("MediaBrowserService", "⚠️ NitroPlayerMediaBrowserService: Android Auto not enabled, returning empty")
@@ -118,9 +138,11 @@ class NitroPlayerMediaBrowserService : MediaBrowserServiceCompat() {
 
                 serviceScope.launch {
                     try {
+                        if (mediaLibraryManager.getMediaLibrary() == null) mediaLibraryManager.awaitFirstPublish(MediaLibraryManager.FIRST_PUBLISH_WAIT_MS)
                         val library = mediaLibraryManager.getMediaLibrary()
+                        val rootItems = library?.rootItems?.filter { it.hasContent() }.orEmpty()
 
-                        if (library == null) {
+                        if (library == null || rootItems.isEmpty()) {
                             // Fallback: show playlists if no media library is set
                             NitroPlayerLogger.log("MediaBrowserService", "⚠️ NitroPlayerMediaBrowserService: No media library set, using fallback playlists")
                             val mediaItems = loadFallbackPlaylists()
@@ -128,11 +150,7 @@ class NitroPlayerMediaBrowserService : MediaBrowserServiceCompat() {
                             return@launch
                         }
 
-                        val mediaItems = mutableListOf<MediaBrowserCompat.MediaItem>()
-
-                        library.rootItems.forEach { item ->
-                            mediaItems.add(convertToMediaBrowserItem(item, library.layoutType))
-                        }
+                        val mediaItems = rootItems.map { convertToMediaBrowserItem(it, library.layoutType) }.toMutableList()
 
                         NitroPlayerLogger.log("MediaBrowserService", "✅ NitroPlayerMediaBrowserService: Returning ${mediaItems.size} root items")
                         result.sendResult(mediaItems)
@@ -152,7 +170,7 @@ class NitroPlayerMediaBrowserService : MediaBrowserServiceCompat() {
 
                 serviceScope.launch {
                     try {
-                        val playlist = trackPlayerCore?.getPlaylistManager()?.getPlaylist(playlistId)
+                        val playlist = core.playlistManager.getPlaylist(playlistId)
 
                         if (playlist == null) {
                             NitroPlayerLogger.log("MediaBrowserService", "⚠️ NitroPlayerMediaBrowserService: Playlist '$playlistId' not found")
@@ -162,7 +180,10 @@ class NitroPlayerMediaBrowserService : MediaBrowserServiceCompat() {
 
                         val mediaItems = mutableListOf<MediaBrowserCompat.MediaItem>()
 
+                        val seen = mutableSetOf<String>()
                         playlist.tracks.forEachIndexed { index, track ->
+                            // A repeated track gets its own id so picking that row plays that occurrence
+                            val trackRef = if (seen.add(track.id)) track.id else "${track.id}#$index"
                             val extras =
                                 Bundle().apply {
                                     putString("playlistId", playlistId)
@@ -173,7 +194,7 @@ class NitroPlayerMediaBrowserService : MediaBrowserServiceCompat() {
                             val description =
                                 MediaDescriptionCompat
                                     .Builder()
-                                    .setMediaId("$playlistId:${track.id}")
+                                    .setMediaId("$playlistId:$trackRef")
                                     .setTitle(track.title)
                                     .setSubtitle(track.artist)
                                     .setDescription(track.album)
@@ -199,17 +220,14 @@ class NitroPlayerMediaBrowserService : MediaBrowserServiceCompat() {
                 }
             }
 
-            parentId == EMPTY_ROOT_ID -> {
-                result.sendResult(mutableListOf())
-            }
-
             else -> {
                 // Handle custom folder IDs from media library
                 result.detach()
 
                 serviceScope.launch {
                     try {
-                        val children = mediaLibraryManager.getChildrenById(parentId)
+                        if (mediaLibraryManager.getMediaLibrary() == null) mediaLibraryManager.awaitFirstPublish(MediaLibraryManager.FIRST_PUBLISH_WAIT_MS)
+                        val children = mediaLibraryManager.getChildrenById(parentId) ?: mediaLibraryManager.loadChildren(parentId)
 
                         if (children == null) {
                             NitroPlayerLogger.log("MediaBrowserService", "⚠️ NitroPlayerMediaBrowserService: No children found for parentId: $parentId")
@@ -221,6 +239,7 @@ class NitroPlayerMediaBrowserService : MediaBrowserServiceCompat() {
                         val defaultLayout = library?.layoutType ?: LayoutType.LIST
                         val mediaItems =
                             children
+                                .filter { it.hasContent() }
                                 .map { item ->
                                     convertToMediaBrowserItem(item, defaultLayout)
                                 }.toMutableList()
@@ -237,6 +256,31 @@ class NitroPlayerMediaBrowserService : MediaBrowserServiceCompat() {
         }
     }
 
+    override fun onSearch(
+        query: String,
+        extras: Bundle?,
+        result: Result<MutableList<MediaBrowserCompat.MediaItem>>,
+    ) {
+        startJsOnDemand()
+        result.detach()
+        serviceScope.launch {
+            val items = mediaLibraryManager.search(query).orEmpty().filter { it.hasContent() }
+            val layout = mediaLibraryManager.getMediaLibrary()?.layoutType ?: LayoutType.LIST
+            result.sendResult(items.map { convertToMediaBrowserItem(it, layout) }.toMutableList())
+        }
+    }
+
+    // The car binds every media app on connect; JS starts only once content is asked for, never for SystemUI's recent-media probe
+    private fun startJsOnDemand() {
+        if (browserRootHints?.getBoolean(BrowserRoot.EXTRA_RECENT) != true) core.startJsRuntimeIfNeeded()
+    }
+
+    // Folders a client has open keep their stale children unless refreshed too
+    fun onLibraryUpdated(folderIds: List<String>) {
+        onPlaylistsUpdated()
+        folderIds.distinct().forEach { notifyChildrenChanged(it) }
+    }
+
     fun onPlaylistsUpdated() {
         try {
             notifyChildrenChanged(ROOT_ID)
@@ -255,6 +299,12 @@ class NitroPlayerMediaBrowserService : MediaBrowserServiceCompat() {
         }
     }
 
+    // Apps may delete the playlists a published library points at; hide those, but keep empty ones so the user still finds them
+    private fun MediaItem.hasContent(): Boolean {
+        if (mediaType != MediaType.PLAYLIST || playlistId == null) return true
+        return core.playlistManager.getPlaylist(playlistId) != null
+    }
+
     /**
      * Convert MediaLibrary MediaItem to Android Auto MediaBrowserCompat.MediaItem
      */
@@ -275,6 +325,7 @@ class NitroPlayerMediaBrowserService : MediaBrowserServiceCompat() {
                     MediaConstants.DESCRIPTION_EXTRAS_KEY_CONTENT_STYLE_BROWSABLE,
                     contentStyle,
                 )
+                item.groupTitle?.let { putString(MediaConstants.DESCRIPTION_EXTRAS_KEY_CONTENT_STYLE_GROUP_TITLE, it) }
             }
 
         // Determine the media ID based on item type
@@ -328,8 +379,8 @@ class NitroPlayerMediaBrowserService : MediaBrowserServiceCompat() {
         // and prefer surfacing the currently-loaded playlist first so the user
         // always has access to "what's playing now" while the JS side hasn't
         // published a media library yet.
-        val rawPlaylists = trackPlayerCore?.getAllPlaylists() ?: emptyList()
-        val currentId = trackPlayerCore?.getCurrentPlaylistId()
+        val rawPlaylists = core.getAllPlaylists()
+        val currentId = core.getCurrentPlaylistId()
         val uuidRegex = Regex("^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$")
 
         val dedupedByName = linkedMapOf<String, com.margelo.nitro.nitroplayer.playlist.Playlist>()

package/android/src/main/java/com/margelo/nitro/nitroplayer/media/MediaLibrary.kt

@@ -41,6 +41,8 @@ data class MediaItem(
     val children: List<MediaItem>? = null,
     /** Layout type for folder items (overrides library default) */
     val layoutType: LayoutType? = null,
+    /** Group header; contiguous items sharing one are listed under it */
+    val groupTitle: String? = null,
 )
 
 /**

package/android/src/main/java/com/margelo/nitro/nitroplayer/media/MediaLibraryManager.kt

@@ -2,6 +2,12 @@ package com.margelo.nitro.nitroplayer.media
 
 import android.content.Context
 import com.margelo.nitro.nitroplayer.core.NitroPlayerLogger
+import kotlinx.coroutines.CompletableDeferred
+import kotlinx.coroutines.ExperimentalCoroutinesApi
+import kotlinx.coroutines.withTimeoutOrNull
+import org.json.JSONException
+import java.util.UUID
+import java.util.concurrent.ConcurrentHashMap
 
 /**
  * Manages the Android Auto media library structure
@@ -12,11 +18,150 @@ class MediaLibraryManager private constructor(
     @Volatile
     private var mediaLibrary: MediaLibrary? = null
 
+    // The app answers these through resolve(): folders loaded on demand, and searches
+    @Volatile
+    var childrenRequester: ((requestId: String, parentId: String) -> Unit)? = null
+        set(value) {
+            field = value
+            if (value != null) loaderRegistered.complete(Unit)
+        }
+
+    private val loaderRegistered = CompletableDeferred<Unit>()
+
+    private var resumptionRequester: (() -> Unit)? = null
+    private var resumptionPending = false
+
+    // A resumption asked for before the app's JS registered its handler is delivered once it does
+    fun setResumptionRequester(requester: () -> Unit) {
+        val deliver =
+            synchronized(this) {
+                resumptionRequester = requester
+                resumptionPending.also { resumptionPending = false }
+            }
+        if (deliver) requester()
+    }
+
+    fun requestResumption() {
+        val requester = synchronized(this) { resumptionRequester.also { if (it == null) resumptionPending = true } }
+        requester?.invoke()
+    }
+
+    @Volatile
+    var searchRequester: ((requestId: String, query: String) -> Unit)? = null
+
+    private val pending = ConcurrentHashMap<String, CompletableDeferred<String>>()
+
+    private val firstPublish = CompletableDeferred<Unit>()
+
+    // A car-only start asks for the root before the app's JS has published; wait once instead of showing "No items"
+    suspend fun awaitFirstPublish(timeoutMs: Long) {
+        withTimeoutOrNull(timeoutMs) { firstPublish.await() }
+        firstPublish.complete(Unit)
+    }
+
+    /** Children of a folder the published library leaves empty, or null when the app has none to give. */
+    private val inFlightChildren = ConcurrentHashMap<String, CompletableDeferred<List<MediaItem>?>>()
+
+    // Folders loaded on demand are refreshed with the library, so the car never keeps a stale or failed answer
+    val loadedFolderIds: MutableSet<String> = ConcurrentHashMap.newKeySet()
+
+    // An answer that missed the timeout is kept briefly and the car told to reload that folder
+    private val lateChildren = ConcurrentHashMap<String, Pair<Long, List<MediaItem>>>()
+
+    @Volatile
+    var onLateChildren: ((parentId: String) -> Unit)? = null
+
+    suspend fun loadChildren(parentId: String): List<MediaItem>? {
+        // The car reopens remembered folders on connect, before a car-only start's JS has registered its loader
+        if (childrenRequester == null) withTimeoutOrNull(FIRST_PUBLISH_WAIT_MS) { loaderRegistered.await() }
+        loaderRegistered.complete(Unit)
+        loadedFolderIds.add(parentId)
+        lateChildren.remove(parentId)?.let { (at, items) -> if (System.currentTimeMillis() - at < LATE_CHILDREN_TTL_MS) return items }
+        // The car asks for the same folder several times at once; answer them all from one app call
+        val result = CompletableDeferred<List<MediaItem>?>()
+        inFlightChildren.putIfAbsent(parentId, result)?.let { return it.await() }
+        try {
+            result.complete(request(childrenRequester, parentId, LOAD_CHILDREN_TIMEOUT_MS, lateFolder = parentId))
+        } catch (e: Throwable) {
+            result.completeExceptionally(e)
+            throw e
+        } finally {
+            inFlightChildren.remove(parentId, result)
+        }
+        return result.await()
+    }
+
+    suspend fun search(query: String): List<MediaItem>? = request(searchRequester, query, SEARCH_TIMEOUT_MS)
+
+    fun resolve(
+        requestId: String,
+        itemsJson: String,
+    ) {
+        pending.remove(requestId)?.complete(itemsJson)
+    }
+
+    @OptIn(ExperimentalCoroutinesApi::class)
+    private suspend fun request(
+        requester: ((String, String) -> Unit)?,
+        argument: String,
+        timeoutMs: Long,
+        lateFolder: String? = null,
+    ): List<MediaItem>? {
+        val ask = requester ?: return null
+        val requestId = UUID.randomUUID().toString()
+        val answer = CompletableDeferred<String>()
+        pending[requestId] = answer
+        try {
+            ask(requestId, argument)
+        } catch (e: Throwable) {
+            pending.remove(requestId)
+            throw e
+        }
+        // A driver is waiting at the screen: past this the folder reads as empty
+        val askedAt = System.currentTimeMillis()
+        val json = withTimeoutOrNull(timeoutMs) { answer.await() }
+        NitroPlayerLogger.log("MediaLibraryManager") { "'$argument' ${if (json == null) "timed out" else "answered"} after ${System.currentTimeMillis() - askedAt}ms" }
+        if (json == null && lateFolder != null) {
+            if (pending.size > MAX_PENDING) pending.clear()
+            answer.invokeOnCompletion { error -> if (error == null) deliverLate(lateFolder, answer.getCompleted()) }
+            return null
+        }
+        pending.remove(requestId)
+        return json?.let { parseItems(it, argument) }
+    }
+
+    private fun deliverLate(
+        parentId: String,
+        json: String,
+    ) {
+        val items = parseItems(json, parentId) ?: return
+        NitroPlayerLogger.log("MediaLibraryManager") { "Late answer for '$parentId', asking the car to reload it" }
+        lateChildren[parentId] = System.currentTimeMillis() to items
+        onLateChildren?.invoke(parentId)
+    }
+
+    private fun parseItems(
+        json: String,
+        argument: String,
+    ): List<MediaItem>? =
+        try {
+            MediaLibraryParser.itemsFromJson(json)
+        } catch (e: JSONException) {
+            NitroPlayerLogger.log("MediaLibraryManager") { "Bad items JSON for '$argument': ${e.message}" }
+            null
+        }
+
     companion object {
         @Volatile
         @Suppress("ktlint:standard:property-naming")
         private var INSTANCE: MediaLibraryManager? = null
 
+        private const val LOAD_CHILDREN_TIMEOUT_MS = 10_000L
+        private const val LATE_CHILDREN_TTL_MS = 60_000L
+        private const val MAX_PENDING = 64
+        private const val SEARCH_TIMEOUT_MS = 7_000L
+        internal const val FIRST_PUBLISH_WAIT_MS = 3_000L
+
         fun getInstance(context: Context): MediaLibraryManager =
             INSTANCE ?: synchronized(this) {
                 INSTANCE ?: MediaLibraryManager(context).also { INSTANCE = it }
@@ -28,6 +173,7 @@ class MediaLibraryManager private constructor(
      */
     fun setMediaLibrary(library: MediaLibrary) {
         mediaLibrary = library
+        firstPublish.complete(Unit)
         NitroPlayerLogger.log("MediaLibraryManager", "📚 MediaLibraryManager: Media library set with ${library.rootItems.size} root items")
     }
 
@@ -73,6 +219,7 @@ class MediaLibraryManager private constructor(
      */
     fun clear() {
         mediaLibrary = null
+        firstPublish.complete(Unit)
         NitroPlayerLogger.log("MediaLibraryManager", "📚 MediaLibraryManager: Media library cleared")
     }
 }

package/android/src/main/java/com/margelo/nitro/nitroplayer/media/MediaLibraryParser.kt

@@ -7,6 +7,8 @@ import org.json.JSONObject
  * Parser for MediaLibrary JSON structure
  */
 object MediaLibraryParser {
+    fun itemsFromJson(json: String): List<MediaItem> = parseMediaItems(JSONArray(json))
+
     fun fromJson(json: String): MediaLibrary {
         val jsonObject = JSONObject(json)
 
@@ -68,6 +70,7 @@ object MediaLibraryParser {
             playlistId = jsonObject.optString("playlistId").takeIf { it.isNotEmpty() },
             children = children.takeIf { it.isNotEmpty() },
             layoutType = layoutType,
+            groupTitle = jsonObject.optString("groupTitle").takeIf { it.isNotEmpty() },
         )
     }
 }