react-native-nitro-player 1.5.0 → 1.6.0-alpha.0

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

@@ -8,7 +8,7 @@ import com.margelo.nitro.NitroModules
 import com.margelo.nitro.core.NullType
 import com.margelo.nitro.core.Promise
 import com.margelo.nitro.nitroplayer.core.TrackPlayerCore
-import com.margelo.nitro.nitroplayer.core.loadPlaylist
+import com.margelo.nitro.nitroplayer.core.loadPlaylistOnQueue
 import com.margelo.nitro.nitroplayer.core.updatePlaylist
 import com.margelo.nitro.nitroplayer.playlist.PlaylistManager
 import java.util.UUID
@@ -109,13 +109,24 @@ class HybridPlayerQueue : HybridPlayerQueueSpec() {
 
     // ── Playback control ──────────────────────────────────────────────────────
 
-    override fun loadPlaylist(playlistId: String, index: Double?): Promise<Unit> =
-        Promise.async {
-            val startIndex = index?.toInt()
-            val loaded = playlistManager.loadPlaylist(playlistId, startIndex)
-            if (!loaded) return@async
-            core.loadPlaylist(playlistId, startIndex)
+    /**
+     * Enqueued synchronously on the player looper so a `loadPlaylist()` followed by
+     * `play()` from JS cannot be reordered — see HybridTrackPlayer.enqueue.
+     */
+    override fun loadPlaylist(
+        playlistId: String,
+        index: Double?,
+    ): Promise<Unit> {
+        val startIndex = index?.toInt()
+        val promise = Promise<Unit>()
+        core.enqueue {
+            if (playlistManager.loadPlaylist(playlistId, startIndex)) {
+                core.loadPlaylistOnQueue(playlistId, startIndex)
+            }
+            promise.resolve(Unit)
         }
+        return promise
+    }
 
     override fun getCurrentPlaylistId(): Variant_NullType_String {
         val id = core.getCurrentPlaylistId()

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

@@ -7,35 +7,30 @@ import com.facebook.proguard.annotations.DoNotStrip
 import com.margelo.nitro.NitroModules
 import com.margelo.nitro.core.Promise
 import com.margelo.nitro.nitroplayer.core.TrackPlayerCore
-import com.margelo.nitro.nitroplayer.core.addToUpNext
-import com.margelo.nitro.nitroplayer.core.clearPlayNext
-import com.margelo.nitro.nitroplayer.core.clearUpNext
-import com.margelo.nitro.nitroplayer.core.configure
-import com.margelo.nitro.nitroplayer.core.getActualQueue
-import com.margelo.nitro.nitroplayer.core.getCurrentTrackIndex
-import com.margelo.nitro.nitroplayer.core.getNextTracks
-import com.margelo.nitro.nitroplayer.core.getPlayBackSpeed
-import com.margelo.nitro.nitroplayer.core.getPlayNextQueue
+import com.margelo.nitro.nitroplayer.core.addToUpNextInternal
+import com.margelo.nitro.nitroplayer.core.clearPlayNextOnQueue
+import com.margelo.nitro.nitroplayer.core.clearUpNextOnQueue
+import com.margelo.nitro.nitroplayer.core.configureOnQueue
+import com.margelo.nitro.nitroplayer.core.getActualQueueInternal
+import com.margelo.nitro.nitroplayer.core.getNextTracksInternal
 import com.margelo.nitro.nitroplayer.core.getRepeatMode
-import com.margelo.nitro.nitroplayer.core.getState
-import com.margelo.nitro.nitroplayer.core.getTracksById
-import com.margelo.nitro.nitroplayer.core.getTracksNeedingUrls
-import com.margelo.nitro.nitroplayer.core.getUpNextQueue
-import com.margelo.nitro.nitroplayer.core.pause
-import com.margelo.nitro.nitroplayer.core.play
-import com.margelo.nitro.nitroplayer.core.playNext
-import com.margelo.nitro.nitroplayer.core.playSong
-import com.margelo.nitro.nitroplayer.core.removeFromPlayNext
-import com.margelo.nitro.nitroplayer.core.removeFromUpNext
-import com.margelo.nitro.nitroplayer.core.reorderTemporaryTrack
-import com.margelo.nitro.nitroplayer.core.seek
-import com.margelo.nitro.nitroplayer.core.setPlayBackSpeed
-import com.margelo.nitro.nitroplayer.core.setRepeatMode
-import com.margelo.nitro.nitroplayer.core.setVolume
-import com.margelo.nitro.nitroplayer.core.skipToIndex
-import com.margelo.nitro.nitroplayer.core.skipToNext
-import com.margelo.nitro.nitroplayer.core.skipToPrevious
-import com.margelo.nitro.nitroplayer.core.updateTracks
+import com.margelo.nitro.nitroplayer.core.getStateInternal
+import com.margelo.nitro.nitroplayer.core.getTracksNeedingUrlsInternal
+import com.margelo.nitro.nitroplayer.core.pauseOnQueue
+import com.margelo.nitro.nitroplayer.core.playNextInternal
+import com.margelo.nitro.nitroplayer.core.playOnQueue
+import com.margelo.nitro.nitroplayer.core.playSongInternal
+import com.margelo.nitro.nitroplayer.core.removeFromPlayNextOnQueue
+import com.margelo.nitro.nitroplayer.core.removeFromUpNextOnQueue
+import com.margelo.nitro.nitroplayer.core.reorderTemporaryTrackOnQueue
+import com.margelo.nitro.nitroplayer.core.seekOnQueue
+import com.margelo.nitro.nitroplayer.core.setPlayBackSpeedOnQueue
+import com.margelo.nitro.nitroplayer.core.setRepeatModeOnQueue
+import com.margelo.nitro.nitroplayer.core.setVolumeOnQueue
+import com.margelo.nitro.nitroplayer.core.skipToIndexInternal
+import com.margelo.nitro.nitroplayer.core.skipToNextOnQueue
+import com.margelo.nitro.nitroplayer.core.skipToPreviousOnQueue
+import com.margelo.nitro.nitroplayer.core.updateTracksOnQueue
 
 @DoNotStrip
 @Keep
@@ -52,79 +47,99 @@ class HybridTrackPlayer : HybridTrackPlayerSpec() {
         core = TrackPlayerCore.getInstance(context)
     }
 
+    // ── Ordered dispatch ──────────────────────────────────────────────────────
+    //
+    // `Promise.async { … }` launches an unordered coroutine, so the hop onto the player
+    // looper happened at an arbitrary later point: two calls made in order from JS could
+    // reach the player in reverse order (play-then-pause landing as pause-then-play).
+    // `core.enqueue` appends synchronously, on the JS thread at call time, so execution
+    // order equals JS call order.
+
+    private fun <T> enqueue(block: () -> T): Promise<T> {
+        val promise = Promise<T>()
+        core.enqueue {
+            try {
+                promise.resolve(block())
+            } catch (e: Throwable) {
+                promise.reject(e)
+            }
+        }
+        return promise
+    }
+
     // ── Playback ─────────────────────────────────────────────────────────────
 
-    override fun play(): Promise<Unit> = Promise.async { core.play() }
+    override fun play(): Promise<Unit> = enqueue { core.playOnQueue() }
 
-    override fun pause(): Promise<Unit> = Promise.async { core.pause() }
+    override fun pause(): Promise<Unit> = enqueue { core.pauseOnQueue() }
 
-    override fun seek(position: Double): Promise<Unit> = Promise.async { core.seek(position) }
+    override fun seek(position: Double): Promise<Unit> = enqueue { core.seekOnQueue(position) }
 
-    override fun skipToNext(): Promise<Unit> = Promise.async { core.skipToNext() }
+    override fun skipToNext(): Promise<Unit> = enqueue { core.skipToNextOnQueue() }
 
-    override fun skipToPrevious(): Promise<Unit> = Promise.async { core.skipToPrevious() }
+    override fun skipToPrevious(): Promise<Unit> = enqueue { core.skipToPreviousOnQueue() }
 
     override fun playSong(
         songId: String,
         fromPlaylist: String?,
-    ): Promise<Unit> = Promise.async { core.playSong(songId, fromPlaylist) }
+    ): Promise<Unit> = enqueue { core.playSongInternal(songId, fromPlaylist) }
 
-    override fun skipToIndex(index: Double): Promise<Boolean> = Promise.async { core.skipToIndex(index.toInt()) }
+    override fun skipToIndex(index: Double): Promise<Boolean> = enqueue { core.skipToIndexInternal(index.toInt()) }
 
-    override fun setRepeatMode(mode: RepeatMode): Promise<Unit> = Promise.async { core.setRepeatMode(mode) }
+    override fun setRepeatMode(mode: RepeatMode): Promise<Unit> = enqueue { core.setRepeatModeOnQueue(mode) }
 
     override fun getRepeatMode(): RepeatMode = core.getRepeatMode()
 
-    override fun setVolume(volume: Double): Promise<Unit> = Promise.async { core.setVolume(volume) }
+    override fun setVolume(volume: Double): Promise<Unit> = enqueue { core.setVolumeOnQueue(volume) }
 
-    override fun configure(config: PlayerConfig): Promise<Unit> = Promise.async { core.configure(config) }
+    override fun configure(config: PlayerConfig): Promise<Unit> = enqueue { core.configureOnQueue(config) }
 
     // ── Queue / state reads ───────────────────────────────────────────────────
 
-    override fun getActualQueue(): Promise<Array<TrackItem>> = Promise.async { core.getActualQueue().toTypedArray() }
+    override fun getActualQueue(): Promise<Array<TrackItem>> = enqueue { core.getActualQueueInternal().toTypedArray() }
 
-    override fun getState(): Promise<PlayerState> = Promise.async { core.getState() }
+    override fun getState(): Promise<PlayerState> = enqueue { core.getStateInternal() }
 
-    override fun getTracksById(trackIds: Array<String>): Promise<Array<TrackItem>> = Promise.async { core.getTracksById(trackIds.toList()).toTypedArray() }
+    override fun getTracksById(trackIds: Array<String>): Promise<Array<TrackItem>> = enqueue { core.getPlaylistManager().getTracksById(trackIds.toList()).toTypedArray() }
 
-    override fun getTracksNeedingUrls(): Promise<Array<TrackItem>> = Promise.async { core.getTracksNeedingUrls().toTypedArray() }
+    override fun getTracksNeedingUrls(): Promise<Array<TrackItem>> = enqueue { core.getTracksNeedingUrlsInternal().toTypedArray() }
 
-    override fun getNextTracks(count: Double): Promise<Array<TrackItem>> = Promise.async { core.getNextTracks(count.toInt()).toTypedArray() }
+    override fun getNextTracks(count: Double): Promise<Array<TrackItem>> = enqueue { core.getNextTracksInternal(count.toInt()).toTypedArray() }
 
-    override fun getCurrentTrackIndex(): Promise<Double> = Promise.async { core.getCurrentTrackIndex().toDouble() }
+    override fun getCurrentTrackIndex(): Promise<Double> = enqueue { core.currentTrackIndex.toDouble() }
 
     // ── URL updates ───────────────────────────────────────────────────────────
 
-    override fun updateTracks(tracks: Array<TrackItem>): Promise<Unit> = Promise.async { core.updateTracks(tracks.toList()) }
+    override fun updateTracks(tracks: Array<TrackItem>): Promise<Unit> = enqueue { core.updateTracksOnQueue(tracks.toList()) }
 
     // ── Temporary queue ───────────────────────────────────────────────────────
 
-    override fun addToUpNext(trackId: String): Promise<Unit> = Promise.async { core.addToUpNext(trackId) }
+    override fun addToUpNext(trackId: String): Promise<Unit> = enqueue { core.addToUpNextInternal(trackId) }
 
-    override fun playNext(trackId: String): Promise<Unit> = Promise.async { core.playNext(trackId) }
+    override fun playNext(trackId: String): Promise<Unit> = enqueue { core.playNextInternal(trackId) }
 
-    override fun removeFromPlayNext(trackId: String): Promise<Boolean> = Promise.async { core.removeFromPlayNext(trackId) }
+    override fun removeFromPlayNext(trackId: String): Promise<Boolean> = enqueue { core.removeFromPlayNextOnQueue(trackId) }
 
-    override fun removeFromUpNext(trackId: String): Promise<Boolean> = Promise.async { core.removeFromUpNext(trackId) }
+    override fun removeFromUpNext(trackId: String): Promise<Boolean> = enqueue { core.removeFromUpNextOnQueue(trackId) }
 
-    override fun clearPlayNext(): Promise<Unit> = Promise.async { core.clearPlayNext() }
+    override fun clearPlayNext(): Promise<Unit> = enqueue { core.clearPlayNextOnQueue() }
 
-    override fun clearUpNext(): Promise<Unit> = Promise.async { core.clearUpNext() }
+    override fun clearUpNext(): Promise<Unit> = enqueue { core.clearUpNextOnQueue() }
 
     override fun reorderTemporaryTrack(
         trackId: String,
         newIndex: Double,
-    ): Promise<Boolean> = Promise.async { core.reorderTemporaryTrack(trackId, newIndex.toInt()) }
+    ): Promise<Boolean> = enqueue { core.reorderTemporaryTrackOnQueue(trackId, newIndex.toInt()) }
 
-    override fun getPlayNextQueue(): Promise<Array<TrackItem>> = Promise.async { core.getPlayNextQueue().toTypedArray() }
+    override fun getPlayNextQueue(): Promise<Array<TrackItem>> = enqueue { core.playNextStack.toTypedArray() }
 
-    override fun getUpNextQueue(): Promise<Array<TrackItem>> = Promise.async { core.getUpNextQueue().toTypedArray() }
+    override fun getUpNextQueue(): Promise<Array<TrackItem>> = enqueue { core.upNextQueue.toTypedArray() }
 
     // ── Playback speed ────────────────────────────────────────────────────────
 
-    override fun setPlaybackSpeed(speed: Double): Promise<Unit> = Promise.async { core.setPlayBackSpeed(speed) }
+    override fun setPlaybackSpeed(speed: Double): Promise<Unit> = enqueue { core.setPlayBackSpeedOnQueue(speed) }
 
-    override fun getPlaybackSpeed(): Promise<Double> = Promise.async { core.getPlayBackSpeed() }
+    override fun getPlaybackSpeed(): Promise<Double> = enqueue { if (core.isExoInitialized) core.exo.getPlaybackSpeed().toDouble() else 1.0 }
 
     // ── Android Auto ──────────────────────────────────────────────────────────
 
@@ -171,6 +186,11 @@ class HybridTrackPlayer : HybridTrackPlayerSpec() {
         listenerIds += "onTracksNeedUpdate" to id
     }
 
+    override fun onTimedMetadata(callback: (metadata: TimedMetadata) -> Unit) {
+        val id = core.addOnTimedMetadataListener(callback)
+        listenerIds += "onTimedMetadata" to id
+    }
+
     override fun onTemporaryQueueChange(callback: (playNextQueue: Array<TrackItem>, upNextQueue: Array<TrackItem>) -> Unit) {
         val id =
             core.addOnTemporaryQueueChangeListener { pn, un ->
@@ -192,6 +212,7 @@ class HybridTrackPlayer : HybridTrackPlayerSpec() {
                 "onAndroidAutoConnectionChange" -> core.removeOnAndroidAutoConnectionListener(id)
                 "onTracksNeedUpdate" -> core.removeOnTracksNeedUpdateListener(id)
                 "onTemporaryQueueChange" -> core.removeOnTemporaryQueueChangeListener(id)
+                "onTimedMetadata" -> core.removeOnTimedMetadataListener(id)
             }
         }
         listenerIds.clear()

package/android/src/main/java/com/margelo/nitro/nitroplayer/core/TrackPlayerCore.kt

@@ -11,6 +11,7 @@ import android.os.IBinder
 import android.os.Looper
 import com.margelo.nitro.nitroplayer.Reason
 import com.margelo.nitro.nitroplayer.RepeatMode
+import com.margelo.nitro.nitroplayer.TimedMetadata
 import com.margelo.nitro.nitroplayer.TrackItem
 import com.margelo.nitro.nitroplayer.TrackPlayerState
 import com.margelo.nitro.nitroplayer.connection.AndroidAutoConnectionDetector
@@ -90,10 +91,13 @@ class TrackPlayerCore private constructor(
         ListenerRegistry<(List<TrackItem>, List<TrackItem>) -> Unit>()
     internal val onAndroidAutoConnectionListeners =
         ListenerRegistry<(Boolean) -> Unit>()
+    internal val onTimedMetadataListeners =
+        ListenerRegistry<(TimedMetadata) -> Unit>()
     internal val onCastStateChangeListeners =
         ListenerRegistry<(com.margelo.nitro.nitroplayer.CastState, String?) -> Unit>()
 
     // ── Google Cast ──────────────────────────────────────────────────────────
+
     /** Set once the playback service has a usable CastContext; null when Cast is unavailable. */
     internal var castSessionController: com.margelo.nitro.nitroplayer.media.CastSessionController? = null
 
@@ -104,18 +108,23 @@ class TrackPlayerCore private constructor(
     internal var lastCastWaitTrackId: String? = null
 
     // ── Progress & playlist-update runnables ───────────────────────────────
+
+    /**
+     * Emits progress once per second while actually playing (matching iOS), instead of
+     * four times a second regardless of state. A paused player has nothing to report,
+     * and every tick is a JS callback that re-renders every `useNowPlaying` consumer.
+     * A seek still reports immediately via `onPositionDiscontinuity`.
+     */
     internal val progressUpdateRunnable =
         object : Runnable {
             override fun run() {
-                if (::exo.isInitialized &&
-                    exo.playbackState != androidx.media3.common.Player.STATE_IDLE
-                ) {
+                if (::exo.isInitialized && exo.isPlaying) {
                     val pos = exo.currentPosition / 1000.0
                     val dur = if (exo.duration > 0) exo.duration / 1000.0 else 0.0
                     notifyPlaybackProgress(pos, dur, if (isManuallySeeked) true else null)
                     isManuallySeeked = false
                 }
-                playerHandler.postDelayed(this, 250)
+                playerHandler.postDelayed(this, PROGRESS_INTERVAL_MS)
             }
         }
 
@@ -155,7 +164,8 @@ class TrackPlayerCore private constructor(
                     }
                     try {
                         context.unbindService(this)
-                    } catch (_: Exception) {}
+                    } catch (_: Exception) {
+                    }
                     serviceBound = false
                     if (rebindAttempts < 3) {
                         rebindAttempts++
@@ -192,6 +202,8 @@ class TrackPlayerCore private constructor(
 
     // ── Singleton ──────────────────────────────────────────────────────────
     companion object {
+        internal const val PROGRESS_INTERVAL_MS = 1000L
+
         @Volatile
         @Suppress("ktlint:standard:property-naming")
         private var INSTANCE: TrackPlayerCore? = null
@@ -206,8 +218,18 @@ class TrackPlayerCore private constructor(
         // Defer service start/bind to the main thread so it doesn't run
         // synchronously on the JNI thread during HybridObject creation.
         handler.post {
-            val intent = Intent(context, NitroPlayerPlaybackService::class.java)
-            context.startService(intent)
+            // startService throws BackgroundServiceStartNotAllowedException on Android 12+
+            // when the process is in the background — which is exactly what happens when JS
+            // loads the module from a headless/backgrounded start. It is only here to keep
+            // the service alive across unbind; BIND_AUTO_CREATE below already creates it,
+            // and the service promotes itself to foreground once playback starts.
+            try {
+                context.startService(Intent(context, NitroPlayerPlaybackService::class.java))
+            } catch (e: Exception) {
+                NitroPlayerLogger.log("TrackPlayerCore") {
+                    "startService skipped (app in background): ${e.message}"
+                }
+            }
 
             val bindIntent =
                 Intent(context, NitroPlayerPlaybackService::class.java).apply {
@@ -219,6 +241,58 @@ class TrackPlayerCore private constructor(
 
     // ── Coroutine bridge to player looper (main thread) ────────────────────
 
+    // ── Ordered command dispatch ───────────────────────────────────────────
+    //
+    // `Promise.async { … }` launches an unordered coroutine, so the hop onto the
+    // player looper used to happen at an arbitrary later point: two calls made in
+    // order from JS could reach the player in reverse order (play-then-pause landing
+    // as pause-then-play). `enqueue` appends to a queue synchronously, on the JS
+    // thread at call time, so execution order equals JS call order — including for
+    // commands issued before the playback service has bound.
+
+    private val pendingCommands = ArrayDeque<() -> Unit>()
+    private var commandsDraining = false
+
+    /**
+     * Runs [block] on the player looper, preserving the order in which callers
+     * enqueued. Safe to call before the service binds — commands buffer until then.
+     */
+    internal fun enqueue(block: () -> Unit) {
+        synchronized(pendingCommands) {
+            pendingCommands.addLast(block)
+            if (commandsDraining) return
+            if (!::playerHandler.isInitialized) return
+            commandsDraining = true
+        }
+        playerHandler.post { drainCommands() }
+    }
+
+    private fun drainCommands() {
+        while (true) {
+            val next =
+                synchronized(pendingCommands) {
+                    val head = pendingCommands.removeFirstOrNull()
+                    if (head == null) commandsDraining = false
+                    head
+                } ?: return
+            next()
+        }
+    }
+
+    /** Called once the player looper exists — flushes anything queued before binding. */
+    internal fun startCommandDraining() {
+        val shouldPost =
+            synchronized(pendingCommands) {
+                if (commandsDraining || pendingCommands.isEmpty()) {
+                    false
+                } else {
+                    commandsDraining = true
+                    true
+                }
+            }
+        if (shouldPost) playerHandler.post { drainCommands() }
+    }
+
     internal suspend fun <T> withPlayerContext(block: () -> T): T {
         // Wait until the service is bound and player is initialized
         serviceReady.await()
@@ -256,13 +330,15 @@ class TrackPlayerCore private constructor(
             }
         }
         scope.cancel()
-        com.margelo.nitro.nitroplayer.media.AuthAwareHttpDataSourceFactory.clear()
+        com.margelo.nitro.nitroplayer.media.AuthAwareHttpDataSourceFactory
+            .clear()
         // Do NOT stop the service — it owns the player.
         // Unbind so Android can clean up if needed.
         if (serviceBound) {
             try {
                 context.unbindService(serviceConnection)
-            } catch (_: Exception) {}
+            } catch (_: Exception) {
+            }
             serviceBound = false
         }
     }
@@ -303,6 +379,10 @@ class TrackPlayerCore private constructor(
 
     fun removeOnTemporaryQueueChangeListener(id: Long): Boolean = onTemporaryQueueChangeListeners.remove(id)
 
+    fun addOnTimedMetadataListener(cb: (TimedMetadata) -> Unit): Long = onTimedMetadataListeners.add(cb)
+
+    fun removeOnTimedMetadataListener(id: Long): Boolean = onTimedMetadataListeners.remove(id)
+
     fun addOnAndroidAutoConnectionListener(cb: (Boolean) -> Unit): Long = onAndroidAutoConnectionListeners.add(cb)
 
     fun removeOnAndroidAutoConnectionListener(id: Long): Boolean = onAndroidAutoConnectionListeners.remove(id)

package/android/src/main/java/com/margelo/nitro/nitroplayer/core/TrackPlayerListener.kt

@@ -3,9 +3,13 @@
 package com.margelo.nitro.nitroplayer.core
 
 import androidx.media3.common.MediaItem
+import androidx.media3.common.MediaMetadata
+import androidx.media3.common.Metadata
 import androidx.media3.common.Player
+import androidx.media3.common.util.UnstableApi
 import com.margelo.nitro.nitroplayer.Reason
 import com.margelo.nitro.nitroplayer.RepeatMode
+import com.margelo.nitro.nitroplayer.TimedMetadata
 import com.margelo.nitro.nitroplayer.equalizer.EqualizerCore
 import com.margelo.nitro.nitroplayer.media.NitroPlayerMediaBrowserService
 
@@ -57,6 +61,16 @@ internal class TrackPlayerEventListener(
                 if (newIdx >= 0 && newIdx != currentTrackIndex) currentTrackIndex = newIdx
             }
 
+            // Top up the windowed timeline — the item we just left freed a slot.
+            // Only when it is actually short: rebuildQueueFromCurrentPosition can fall
+            // into the substitute-jump path (setMediaItems), which re-enters this very
+            // callback. The length check makes any such re-entry a no-op and terminate.
+            if (mediaItem != null &&
+                exo.mediaItemCount - exo.currentMediaItemIndex - 1 < QUEUE_WINDOW_SIZE
+            ) {
+                rebuildQueueFromCurrentPosition()
+            }
+
             val track = getCurrentTrack() ?: return
             val r =
                 when (reason) {
@@ -72,6 +86,22 @@ internal class TrackPlayerEventListener(
         }
     }
 
+    /** In-stream metadata (ICY StreamTitle, ID3 frames) arriving mid-playback. */
+    @UnstableApi
+    override fun onMetadata(metadata: Metadata) {
+        val builder = MediaMetadata.Builder()
+        for (i in 0 until metadata.length()) {
+            metadata.get(i).populateMediaMetadata(builder)
+        }
+        val merged = builder.build()
+        val title = merged.title?.toString()
+        val artist = merged.artist?.toString()
+        val album = merged.albumTitle?.toString()
+        val artworkUrl = merged.artworkUri?.toString()
+        if (title == null && artist == null && album == null && artworkUrl == null) return
+        core.notifyTimedMetadata(TimedMetadata(title, artist, album, artworkUrl))
+    }
+
     override fun onTimelineChanged(
         timeline: androidx.media3.common.Timeline,
         reason: Int,

package/android/src/main/java/com/margelo/nitro/nitroplayer/core/TrackPlayerNotify.kt

@@ -1,6 +1,7 @@
 package com.margelo.nitro.nitroplayer.core
 
 import com.margelo.nitro.nitroplayer.Reason
+import com.margelo.nitro.nitroplayer.TimedMetadata
 import com.margelo.nitro.nitroplayer.TrackItem
 import com.margelo.nitro.nitroplayer.TrackPlayerState
 
@@ -45,6 +46,10 @@ internal fun TrackPlayerCore.notifyTracksNeedUpdate(
     onTracksNeedUpdateListeners.forEach { it(tracks, lookahead) }
 }
 
+internal fun TrackPlayerCore.notifyTimedMetadata(metadata: TimedMetadata) {
+    onTimedMetadataListeners.forEach { it(metadata) }
+}
+
 internal fun TrackPlayerCore.notifyTemporaryQueueChange() {
     val pn = playNextStack.toList()
     val un = upNextQueue.toList()