@rntp/player 5.0.0-beta.3 → 5.0.0-beta.5

package/android/build.gradle

@@ -107,6 +107,13 @@ dependencies {
   implementation "androidx.media3:media3-session:1.9.2"
   implementation "androidx.media3:media3-cast:1.9.2"
   implementation "androidx.mediarouter:mediarouter:1.7.0"
+
+  // Testing
+  testImplementation "junit:junit:4.13.2"
+  testImplementation "org.robolectric:robolectric:4.11.1"
+  testImplementation "io.mockk:mockk:1.13.8"
+  testImplementation "androidx.test:core:1.5.0"
+  testImplementation "androidx.media3:media3-test-utils:1.9.2"
 }
 
 react {

package/android/src/main/java/com/doublesymmetry/trackplayer/SleepTimerController.kt

@@ -0,0 +1,128 @@
+/*
+ * Copyright (c) Double Symmetry GmbH
+ * Commercial use requires a license. See https://rntp.dev/pricing
+ */
+
+package com.doublesymmetry.trackplayer
+
+import androidx.media3.common.Player
+
+class SleepTimerController(private val player: Player) {
+
+    var onTriggered: ((type: String) -> Unit)? = null
+    var onStateChanged: (() -> Unit)? = null
+
+    var sleepTimerType: String? = null
+        private set
+    var sleepTimerRemainingSeconds: Double = 0.0
+        private set
+    var sleepTimerFadeOutSeconds: Double = 0.0
+        private set
+    var sleepTimerTargetIndex: Int? = null
+        private set
+    var sleepTimerPreviousIndex: Int? = null
+        private set
+    private var sleepTimerPreFadeVolume: Float? = null
+
+    fun sleepAfterTime(seconds: Double, fadeOutSeconds: Double) {
+        cancelInternal(restoreVolume = true)
+        sleepTimerType = "time"
+        sleepTimerRemainingSeconds = seconds
+        sleepTimerFadeOutSeconds = fadeOutSeconds.coerceAtMost(seconds)
+        onStateChanged?.invoke()
+
+        if (seconds <= 0) {
+            player.pause()
+            onTriggered?.invoke("time")
+            cancelInternal(restoreVolume = true)
+            return
+        }
+    }
+
+    fun sleepAfterMediaItemAtIndex(index: Int) {
+        cancelInternal(restoreVolume = true)
+        sleepTimerType = "mediaItem"
+        sleepTimerTargetIndex = index
+        sleepTimerPreviousIndex = player.currentMediaItemIndex
+        onStateChanged?.invoke()
+    }
+
+    fun cancel() {
+        cancelInternal(restoreVolume = true)
+    }
+
+    fun getState(): Map<String, Any>? {
+        val type = sleepTimerType ?: return null
+        return if (type == "time") {
+            mapOf(
+                "type" to "time",
+                "remainingSeconds" to sleepTimerRemainingSeconds,
+                "fadeOutSeconds" to sleepTimerFadeOutSeconds
+            )
+        } else {
+            mapOf(
+                "type" to "mediaItem",
+                "index" to (sleepTimerTargetIndex ?: 0)
+            )
+        }
+    }
+
+    /**
+     * Call when a media item transition occurs.
+     * Returns true if the timer fired.
+     */
+    fun handleItemTransition(newIndex: Int): Boolean {
+        if (sleepTimerType == "mediaItem") {
+            val targetIndex = sleepTimerTargetIndex
+            if (targetIndex != null && sleepTimerPreviousIndex == targetIndex && newIndex != targetIndex) {
+                onTriggered?.invoke("mediaItem")
+                cancelInternal(restoreVolume = false)
+                sleepTimerPreviousIndex = newIndex
+                return true
+            }
+        }
+        sleepTimerPreviousIndex = newIndex
+        return false
+    }
+
+    /**
+     * Simulate one wall-clock second passing.
+     * In production, called by a Timer on the main thread.
+     * Exposed for testing.
+     */
+    fun tick() {
+        if (sleepTimerType != "time") return
+
+        sleepTimerRemainingSeconds -= 1.0
+        onStateChanged?.invoke()
+
+        if (sleepTimerFadeOutSeconds > 0 && sleepTimerRemainingSeconds < sleepTimerFadeOutSeconds) {
+            if (sleepTimerPreFadeVolume == null) {
+                sleepTimerPreFadeVolume = player.volume
+            }
+            val progress = maxOf(0.0, sleepTimerRemainingSeconds / sleepTimerFadeOutSeconds).toFloat()
+            player.volume = (sleepTimerPreFadeVolume ?: 1f) * progress
+        }
+
+        if (sleepTimerRemainingSeconds <= 0) {
+            sleepTimerRemainingSeconds = 0.0
+            player.pause()
+            onTriggered?.invoke("time")
+            cancelInternal(restoreVolume = true)
+            return
+        }
+    }
+
+    fun cancelInternal(restoreVolume: Boolean) {
+        if (restoreVolume) {
+            sleepTimerPreFadeVolume?.let { player.volume = it }
+        }
+        sleepTimerPreFadeVolume = null
+        sleepTimerType = null
+        sleepTimerRemainingSeconds = 0.0
+        sleepTimerFadeOutSeconds = 0.0
+        sleepTimerTargetIndex = null
+        sleepTimerPreviousIndex = null
+        onStateChanged?.invoke()
+    }
+}

package/android/src/main/java/com/doublesymmetry/trackplayer/TrackPlayerModule.kt

@@ -562,6 +562,46 @@ class TrackPlayerModule internal constructor(private val context: ReactApplicati
 
   // endregion
 
+  // region Preloading
+
+  @ReactMethod
+  override fun preload(item: ReadableMap, duration: Double) {
+    val url = extractUrl(item) ?: return
+    controller.run { mc ->
+      val args = Bundle().apply { putString("uri", url) }
+      mc?.sendCustomCommand(
+        SessionCommand(TrackPlayerPlaybackService.COMMAND_PRELOAD, Bundle.EMPTY),
+        args
+      )
+    }
+  }
+
+  @ReactMethod
+  override fun cancelPreload(item: ReadableMap) {
+    val url = extractUrl(item) ?: return
+    controller.run { mc ->
+      val args = Bundle().apply { putString("uri", url) }
+      mc?.sendCustomCommand(
+        SessionCommand(TrackPlayerPlaybackService.COMMAND_CANCEL_PRELOAD, Bundle.EMPTY),
+        args
+      )
+    }
+  }
+
+  private fun extractUrl(item: ReadableMap): String? {
+    if (item.hasKey("url")) {
+      val urlValue = item.getDynamic("url")
+      return when (urlValue.type) {
+        com.facebook.react.bridge.ReadableType.String -> urlValue.asString()
+        com.facebook.react.bridge.ReadableType.Map -> item.getMap("url")?.getString("uri")
+        else -> null
+      }
+    }
+    return null
+  }
+
+  // endregion
+
   // region Destroy
 
   @ReactMethod

package/android/src/main/java/com/doublesymmetry/trackplayer/TrackPlayerPlaybackService.kt

@@ -22,8 +22,10 @@ import androidx.media3.common.MediaMetadata
 import androidx.media3.common.Player
 import androidx.media3.common.util.UnstableApi
 import androidx.media3.datasource.DataSource
+import androidx.media3.datasource.DataSpec
 import androidx.media3.datasource.DefaultHttpDataSource
 import androidx.media3.datasource.cache.CacheDataSource
+import androidx.media3.datasource.cache.CacheWriter
 import androidx.media3.datasource.cache.LeastRecentlyUsedCacheEvictor
 import androidx.media3.datasource.cache.SimpleCache
 import androidx.media3.exoplayer.ExoPlayer
@@ -69,13 +71,11 @@ class TrackPlayerPlaybackService: MediaLibraryService(), MediaLibraryService.Med
   private var progressSyncTimer: java.util.Timer? = null
   private var progressSyncExecutor: java.util.concurrent.ExecutorService? = null
 
-  private var sleepTimerType: String? = null // "time" or "mediaItem"
-  private var sleepTimerRemainingSeconds: Double = 0.0
-  private var sleepTimerFadeOutSeconds: Double = 0.0
-  private var sleepTimerTargetIndex: Int? = null
+  private var sleepTimerController: SleepTimerController? = null
   private var sleepTimer: java.util.Timer? = null
-  private var sleepTimerPreFadeVolume: Float? = null
-  private var sleepTimerPreviousIndex: Int? = null
+
+  private val activePreloads = mutableMapOf<String, java.util.concurrent.Future<*>>()
+  private val preloadExecutor = java.util.concurrent.Executors.newFixedThreadPool(2)
 
   @OptIn(UnstableApi::class)
   override fun onCreate() {
@@ -124,6 +124,12 @@ class TrackPlayerPlaybackService: MediaLibraryService(), MediaLibraryService.Med
       .build()
     exoPlayer = built
 
+    if (config.preloadWindow > 0 && config.cacheMaxSizeBytes != null) {
+      built.preloadConfiguration = ExoPlayer.PreloadConfiguration(
+        /* targetPreloadDurationUs= */ Long.MAX_VALUE  // Full file for auto preloading
+      )
+    }
+
     // If Cast is enabled, wrap ExoPlayer inside CastPlayer — Media3 automatically
     // routes playback to the Chromecast when a session is active, and back to
     // ExoPlayer when it ends. No manual player swapping needed.
@@ -141,6 +147,18 @@ class TrackPlayerPlaybackService: MediaLibraryService(), MediaLibraryService.Med
     } ?: built.also { android.util.Log.d("TrackPlayer", "Cast disabled, using ExoPlayer only") }
 
     this.activePlayer = activePlayer
+
+    val controller = SleepTimerController(activePlayer)
+    sleepTimerController = controller
+    controller.onTriggered = { type ->
+      this@TrackPlayerPlaybackService.emitEvent(SleepTimerTriggeredEvent(type))
+      if (type == "mediaItem") {
+        // Defer pause to next run loop — calling during transition gets overridden
+        Handler(Looper.getMainLooper()).post { activePlayer.pause() }
+      }
+    }
+    controller.onStateChanged = { persistSleepTimerState() }
+
     activePlayer.addListener(object : Player.Listener {
       override fun onIsPlayingChanged(isPlaying: Boolean) {
         if (isPlaying) startProgressSyncTimer() else stopProgressSyncTimer(fireFinalTick = true)
@@ -148,21 +166,12 @@ class TrackPlayerPlaybackService: MediaLibraryService(), MediaLibraryService.Med
 
       override fun onMediaItemTransition(mediaItem: MediaItem?, reason: Int) {
         val currentIndex = activePlayer?.currentMediaItemIndex ?: 0
-        if (sleepTimerType == "mediaItem") {
-          val targetIndex = sleepTimerTargetIndex
-          if (targetIndex != null && sleepTimerPreviousIndex == targetIndex && currentIndex != targetIndex) {
-            this@TrackPlayerPlaybackService.emitEvent(SleepTimerTriggeredEvent("mediaItem"))
-            cancelSleepTimerInternal(restoreVolume = false)
-            // Defer pause to next run loop — calling during transition gets overridden
-            Handler(Looper.getMainLooper()).post { activePlayer?.pause() }
-          }
-        }
-        sleepTimerPreviousIndex = currentIndex
+        sleepTimerController?.handleItemTransition(currentIndex)
       }
 
       override fun onTimelineChanged(timeline: androidx.media3.common.Timeline, reason: Int) {
-        if (sleepTimerType == "mediaItem" && (activePlayer?.mediaItemCount ?: 0) == 0) {
-          cancelSleepTimerInternal(restoreVolume = false)
+        if (sleepTimerController?.sleepTimerType == "mediaItem" && (activePlayer?.mediaItemCount ?: 0) == 0) {
+          sleepTimerController?.cancelInternal(restoreVolume = false)
         }
       }
     })
@@ -304,7 +313,13 @@ class TrackPlayerPlaybackService: MediaLibraryService(), MediaLibraryService.Med
     simpleCache?.release()
     simpleCache = null
     sharedCache = null
-    cancelSleepTimerInternal(restoreVolume = false)
+    sleepTimerController?.cancelInternal(restoreVolume = false)
+    sleepTimerController = null
+    sleepTimer?.cancel()
+    sleepTimer = null
+    activePreloads.values.forEach { it.cancel(true) }
+    activePreloads.clear()
+    preloadExecutor.shutdownNow()
     stopProgressSyncTimer(fireFinalTick = false)
     progressSyncExecutor?.shutdown()
     progressSyncExecutor = null
@@ -388,32 +403,29 @@ class TrackPlayerPlaybackService: MediaLibraryService(), MediaLibraryService.Med
       COMMAND_SLEEP_AFTER_TIME -> {
         val seconds = args.getDouble("seconds")
         val fadeOutSeconds = args.getDouble("fadeOutSeconds")
-        cancelSleepTimerInternal(restoreVolume = true)
-        sleepTimerType = "time"
-        sleepTimerRemainingSeconds = seconds
-        sleepTimerFadeOutSeconds = fadeOutSeconds.coerceAtMost(seconds)
-        persistSleepTimerState()
-
-        if (seconds <= 0) {
-          activePlayer?.pause()
-          this@TrackPlayerPlaybackService.emitEvent(SleepTimerTriggeredEvent("time"))
-          cancelSleepTimerInternal(restoreVolume = true)
-        } else {
-          startSleepCountdownTimer()
-        }
+        sleepTimerController?.sleepAfterTime(seconds, fadeOutSeconds)
+        if (seconds > 0) startSleepCountdownTimer()
         return Futures.immediateFuture(SessionResult(SessionResult.RESULT_SUCCESS))
       }
       COMMAND_SLEEP_AFTER_MEDIA_ITEM -> {
         val index = args.getInt("index")
-        cancelSleepTimerInternal(restoreVolume = true)
-        sleepTimerType = "mediaItem"
-        sleepTimerTargetIndex = index
-        sleepTimerPreviousIndex = activePlayer?.currentMediaItemIndex
-        persistSleepTimerState()
+        sleepTimerController?.sleepAfterMediaItemAtIndex(index)
         return Futures.immediateFuture(SessionResult(SessionResult.RESULT_SUCCESS))
       }
       COMMAND_CANCEL_SLEEP_TIMER -> {
-        cancelSleepTimerInternal(restoreVolume = true)
+        sleepTimerController?.cancel()
+        sleepTimer?.cancel()
+        sleepTimer = null
+        return Futures.immediateFuture(SessionResult(SessionResult.RESULT_SUCCESS))
+      }
+      COMMAND_PRELOAD -> {
+        val uri = args.getString("uri") ?: return Futures.immediateFuture(SessionResult(SessionResult.RESULT_ERROR_UNKNOWN))
+        preloadUri(uri)
+        return Futures.immediateFuture(SessionResult(SessionResult.RESULT_SUCCESS))
+      }
+      COMMAND_CANCEL_PRELOAD -> {
+        val uri = args.getString("uri") ?: return Futures.immediateFuture(SessionResult(SessionResult.RESULT_ERROR_UNKNOWN))
+        cancelPreloadUri(uri)
         return Futures.immediateFuture(SessionResult(SessionResult.RESULT_SUCCESS))
       }
     }
@@ -465,12 +477,20 @@ class TrackPlayerPlaybackService: MediaLibraryService(), MediaLibraryService.Med
       return Futures.immediateFuture(LibraryResult.ofItemList(ImmutableList.copyOf(categoryItems), params))
     }
 
+    // Check if it's a category
     val category = browseTree.findCategory(parentId)
     if (category != null) {
       val mediaItems = category.items.map { it.toMediaItem() }
       return Futures.immediateFuture(LibraryResult.ofItemList(ImmutableList.copyOf(mediaItems), params))
     }
 
+    // Check if it's a browsable item with children
+    val browseItem = browseTree.findItem(parentId)
+    if (browseItem != null && browseItem.children != null) {
+      val mediaItems = browseItem.children.map { it.toMediaItem() }
+      return Futures.immediateFuture(LibraryResult.ofItemList(ImmutableList.copyOf(mediaItems), params))
+    }
+
     return Futures.immediateFuture(LibraryResult.ofError(LibraryResult.RESULT_ERROR_BAD_VALUE))
   }
 
@@ -539,6 +559,8 @@ class TrackPlayerPlaybackService: MediaLibraryService(), MediaLibraryService.Med
       .add(SessionCommand(COMMAND_SLEEP_AFTER_TIME, Bundle.EMPTY))
       .add(SessionCommand(COMMAND_SLEEP_AFTER_MEDIA_ITEM, Bundle.EMPTY))
       .add(SessionCommand(COMMAND_CANCEL_SLEEP_TIMER, Bundle.EMPTY))
+      .add(SessionCommand(COMMAND_PRELOAD, Bundle.EMPTY))
+      .add(SessionCommand(COMMAND_CANCEL_PRELOAD, Bundle.EMPTY))
       .build()
 
   // endregion
@@ -620,75 +642,33 @@ class TrackPlayerPlaybackService: MediaLibraryService(), MediaLibraryService.Med
 
   // region Sleep Timer
 
-  private fun cancelSleepTimerInternal(restoreVolume: Boolean) {
-    sleepTimer?.cancel()
-    sleepTimer = null
-    if (restoreVolume) {
-      sleepTimerPreFadeVolume?.let { activePlayer?.volume = it }
-    }
-    sleepTimerPreFadeVolume = null
-    sleepTimerType = null
-    sleepTimerRemainingSeconds = 0.0
-    sleepTimerFadeOutSeconds = 0.0
-    sleepTimerTargetIndex = null
-    sleepTimerPreviousIndex = null
-    persistSleepTimerState()
-  }
-
-  private fun onSleepTimerTick() {
-    sleepTimerRemainingSeconds -= 1.0
-    persistSleepTimerState()
-
-    // Handle fade-out (before zero-check so final tick sets volume to 0)
-    if (sleepTimerFadeOutSeconds > 0 && sleepTimerRemainingSeconds < sleepTimerFadeOutSeconds) {
-      if (sleepTimerPreFadeVolume == null) {
-        sleepTimerPreFadeVolume = activePlayer?.volume ?: 1f
-      }
-      val progress = maxOf(0.0, sleepTimerRemainingSeconds / sleepTimerFadeOutSeconds).toFloat()
-      activePlayer?.volume = (sleepTimerPreFadeVolume ?: 1f) * progress
-    }
-
-    if (sleepTimerRemainingSeconds <= 0) {
-      sleepTimerRemainingSeconds = 0.0
-      activePlayer?.pause()
-      this@TrackPlayerPlaybackService.emitEvent(SleepTimerTriggeredEvent("time"))
-      // Restore volume after pausing so next playback isn't muted
-      cancelSleepTimerInternal(restoreVolume = true)
-      return
-    }
-  }
-
   private fun startSleepCountdownTimer() {
     sleepTimer?.cancel()
     val handler = Handler(Looper.getMainLooper())
     sleepTimer = java.util.Timer().apply {
       scheduleAtFixedRate(object : java.util.TimerTask() {
         override fun run() {
-          handler.post { onSleepTimerTick() }
+          handler.post { sleepTimerController?.tick() }
         }
       }, 1000L, 1000L)
     }
   }
 
-  private fun pauseSleepCountdownTimer() {
-    sleepTimer?.cancel()
-    sleepTimer = null
-  }
-
   private fun persistSleepTimerState() {
     val prefs = getSharedPreferences(TrackPlayerModule.PLAYER_PREFS_NAME, MODE_PRIVATE)
     val editor = prefs.edit()
-    val type = sleepTimerType
-    if (type == null) {
+    val state = sleepTimerController?.getState()
+    if (state == null) {
       editor.remove(SLEEP_TIMER_STATE_KEY)
     } else {
+      val type = state["type"] as String
       val json = JSONObject().apply {
         put("type", type)
         if (type == "time") {
-          put("remainingSeconds", sleepTimerRemainingSeconds)
-          put("fadeOutSeconds", sleepTimerFadeOutSeconds)
+          put("remainingSeconds", state["remainingSeconds"] as Double)
+          put("fadeOutSeconds", state["fadeOutSeconds"] as Double)
         } else {
-          put("index", sleepTimerTargetIndex ?: 0)
+          put("index", state["index"] as Int)
         }
       }
       editor.putString(SLEEP_TIMER_STATE_KEY, json.toString())
@@ -698,6 +678,44 @@ class TrackPlayerPlaybackService: MediaLibraryService(), MediaLibraryService.Med
 
   // endregion
 
+  // region Preloading
+
+  @OptIn(UnstableApi::class)
+  private fun preloadUri(uri: String) {
+    val cache = simpleCache ?: return
+    if (activePreloads.containsKey(uri)) return
+
+    val upstreamFactory = DefaultHttpDataSource.Factory()
+    val dataSourceFactory = CacheDataSource.Factory()
+      .setCache(cache)
+      .setUpstreamDataSourceFactory(upstreamFactory)
+
+    val dataSpec = DataSpec(Uri.parse(uri))
+
+    val future = preloadExecutor.submit {
+      try {
+        val cacheWriter = CacheWriter(
+          dataSourceFactory.createDataSource(),
+          dataSpec,
+          /* temporaryBuffer= */ null,
+          /* progressListener= */ null
+        )
+        cacheWriter.cache()
+      } catch (e: Exception) {
+        // Cancelled or failed — silently ignore
+      } finally {
+        activePreloads.remove(uri)
+      }
+    }
+    activePreloads[uri] = future
+  }
+
+  private fun cancelPreloadUri(uri: String) {
+    activePreloads.remove(uri)?.cancel(true)
+  }
+
+  // endregion
+
   // region Progress Sync
 
   private fun startProgressSyncTimer() {
@@ -799,6 +817,8 @@ class TrackPlayerPlaybackService: MediaLibraryService(), MediaLibraryService.Med
     const val COMMAND_SLEEP_AFTER_MEDIA_ITEM = "trackplayer.sleep_after_media_item"
     const val COMMAND_CANCEL_SLEEP_TIMER = "trackplayer.cancel_sleep_timer"
     const val SLEEP_TIMER_STATE_KEY = "sleep_timer_state"
+    const val COMMAND_PRELOAD = "trackplayer.preload"
+    const val COMMAND_CANCEL_PRELOAD = "trackplayer.cancel_preload"
 
     @Volatile
     var sharedCache: SimpleCache? = null

package/android/src/main/java/com/doublesymmetry/trackplayer/models/BrowseTree.kt

@@ -26,14 +26,18 @@ data class BrowseCategory(
 @Serializable
 data class BrowseMediaItem(
   val mediaId: String,
-  val url: String,
+  val url: String? = null,
   val title: String? = null,
   val artist: String? = null,
   val albumTitle: String? = null,
   val artworkUrl: String? = null,
   val duration: Double? = null,
   val isLive: Boolean? = null,
+  val children: List<BrowseMediaItem>? = null,
 ) {
+  val isPlayable: Boolean get() = url != null
+  val isBrowsable: Boolean get() = children != null && url == null
+
   fun toMediaItem(): MediaItem {
     val extras = Bundle()
     duration?.let { extras.putDouble("duration", it) }
@@ -44,16 +48,20 @@ data class BrowseMediaItem(
       .setArtist(artist)
       .setAlbumTitle(albumTitle)
       .setArtworkUri(artworkUrl?.let { Uri.parse(it) })
-      .setIsBrowsable(false)
-      .setIsPlayable(true)
+      .setIsBrowsable(isBrowsable)
+      .setIsPlayable(isPlayable)
+      .setMediaType(if (isBrowsable) MediaMetadata.MEDIA_TYPE_FOLDER_MIXED else MediaMetadata.MEDIA_TYPE_MUSIC)
       .setExtras(extras)
       .build()
 
     val builder = MediaItem.Builder()
       .setMediaId(mediaId)
-      .setUri(url)
       .setMediaMetadata(metadata)
 
+    if (url != null) {
+      builder.setUri(url)
+    }
+
     if (isLive == true) {
       builder.setLiveConfiguration(MediaItem.LiveConfiguration.Builder().build())
     }
@@ -75,7 +83,7 @@ data class BrowseTree(
     categories.find { it.mediaId == mediaId }
 
   fun findItem(mediaId: String): BrowseMediaItem? =
-    categories.flatMap { it.items }.find { it.mediaId == mediaId }
+    categories.flatMap { findItemRecursive(it.items, mediaId) }.firstOrNull()
 
   companion object {
     private const val BROWSE_TREE_KEY = "browse_tree"
@@ -98,24 +106,47 @@ data class BrowseTree(
         val title = catMap.getString("title") ?: continue
         val itemsArray = catMap.getArray("items") ?: continue
 
-        val items = mutableListOf<BrowseMediaItem>()
-        for (j in 0 until itemsArray.size()) {
-          val itemMap = itemsArray.getMap(j) ?: continue
-          items.add(BrowseMediaItem(
-            mediaId = itemMap.getString("mediaId") ?: continue,
-            url = itemMap.getString("url") as? String ?: continue,
-            title = if (itemMap.hasKey("title")) itemMap.getString("title") else null,
-            artist = if (itemMap.hasKey("artist")) itemMap.getString("artist") else null,
-            albumTitle = if (itemMap.hasKey("albumTitle")) itemMap.getString("albumTitle") else null,
-            artworkUrl = if (itemMap.hasKey("artworkUrl")) itemMap.getString("artworkUrl") else null,
-            duration = if (itemMap.hasKey("duration")) itemMap.getDouble("duration") else null,
-            isLive = if (itemMap.hasKey("isLive")) itemMap.getBoolean("isLive") else null,
-          ))
-        }
-
+        val items = parseItems(itemsArray)
         categories.add(BrowseCategory(mediaId = mediaId, title = title, items = items))
       }
       return BrowseTree(categories)
     }
+
+    private fun parseItems(data: ReadableArray): List<BrowseMediaItem> {
+      val items = mutableListOf<BrowseMediaItem>()
+      for (i in 0 until data.size()) {
+        val itemMap = data.getMap(i) ?: continue
+        val mediaId = itemMap.getString("mediaId") ?: continue
+
+        val children = if (itemMap.hasKey("children")) {
+          itemMap.getArray("children")?.let { parseItems(it) }
+        } else null
+
+        items.add(BrowseMediaItem(
+          mediaId = mediaId,
+          url = if (itemMap.hasKey("url")) itemMap.getString("url") else null,
+          title = if (itemMap.hasKey("title")) itemMap.getString("title") else null,
+          artist = if (itemMap.hasKey("artist")) itemMap.getString("artist") else null,
+          albumTitle = if (itemMap.hasKey("albumTitle")) itemMap.getString("albumTitle") else null,
+          artworkUrl = if (itemMap.hasKey("artworkUrl")) itemMap.getString("artworkUrl") else null,
+          duration = if (itemMap.hasKey("duration")) itemMap.getDouble("duration") else null,
+          isLive = if (itemMap.hasKey("isLive")) itemMap.getBoolean("isLive") else null,
+          children = children,
+        ))
+      }
+      return items
+    }
+
+    private fun findItemRecursive(items: List<BrowseMediaItem>, mediaId: String): List<BrowseMediaItem> {
+      for (item in items) {
+        if (item.mediaId == mediaId) return listOf(item)
+        val children = item.children
+        if (children != null) {
+          val found = findItemRecursive(children, mediaId)
+          if (found.isNotEmpty()) return found
+        }
+      }
+      return emptyList()
+    }
   }
 }

package/android/src/main/java/com/doublesymmetry/trackplayer/models/PlayerConfig.kt

@@ -88,6 +88,11 @@ data class PlayerConfig(
    */
   val cacheMaxSizeBytes: Long? = null,
 
+  /**
+   * Auto-preload window — preload next N tracks. 0 means disabled.
+   */
+  val preloadWindow: Int = 0,
+
   /**
    * Cast receiver app ID. Null means Cast is disabled.
    * Use CastMediaControlIntent.DEFAULT_MEDIA_RECEIVER_APPLICATION_ID for the default receiver.
@@ -194,8 +199,14 @@ data class PlayerConfig(
         notificationChannelName = notification?.getString("channelName"),
         notificationSmallIcon = notification?.getString("smallIcon"),
         cacheMaxSizeBytes = cacheMap?.let {
-          if (it.hasKey("maxSizeBytes")) it.getDouble("maxSizeBytes").toLong() else 100L * 1024 * 1024
+          if (it.hasKey("maxSizeBytes")) it.getDouble("maxSizeBytes").toLong() else 500L * 1024 * 1024
         },
+        preloadWindow = cacheMap?.let {
+          val preloadMap = if (it.hasKey("preloading")) it.getMap("preloading") else null
+          preloadMap?.let { pm ->
+            if (pm.hasKey("window")) pm.getInt("window") else 0
+          } ?: 0
+        } ?: 0,
         castReceiverAppId = if (android?.hasKey("cast") == true) android.getString("cast") else null,
         progressSyncIntervalSeconds = map.getMap("progressSync")?.let {
           if (it.hasKey("intervalSeconds")) it.getDouble("intervalSeconds") else 0.0