@rntp/player 5.0.0 → 5.1.0

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

@@ -34,7 +34,11 @@ class HeaderInjectingDataSourceFactory(
     override fun open(dataSpec: DataSpec): Long {
       val perItemHeaders = MediaHeaders.get(dataSpec.uri.toString())
       if (perItemHeaders != null) {
-        val merged = perItemHeaders + dataSpec.httpRequestHeaders
+        // Per-item headers must win over defaults so callers can override headers
+        // injected by ExoPlayer (e.g. `Icy-MetaData: 1` from ProgressiveMediaPeriod
+        // can be turned off by passing `Icy-MetaData: 0` per item to avoid the
+        // server interleaving metadata into a stream the player can't strip).
+        val merged = dataSpec.httpRequestHeaders + perItemHeaders
         val newSpec = dataSpec.buildUpon()
           .setHttpRequestHeaders(merged)
           .build()

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

@@ -9,6 +9,7 @@ import android.content.ComponentName
 import android.os.Bundle
 import androidx.media3.common.MediaItem
 import androidx.media3.common.MediaMetadata
+import androidx.media3.common.Metadata
 import androidx.media3.common.PlaybackException
 import androidx.media3.common.Player
 import androidx.media3.session.MediaController
@@ -29,12 +30,15 @@ import com.doublesymmetry.trackplayer.models.BrowseTree
 import com.doublesymmetry.trackplayer.models.MediaHeaders
 import com.doublesymmetry.trackplayer.models.IsPlayingChangedEvent
 import com.doublesymmetry.trackplayer.models.MediaItemTransitionEvent
+import com.doublesymmetry.trackplayer.models.MediaMetadataChangedEvent
 import com.doublesymmetry.trackplayer.models.MetadataReceivedEvent
 import com.doublesymmetry.trackplayer.models.PlaybackErrorEvent
 import com.doublesymmetry.trackplayer.models.PlaybackStateChangedEvent
 import com.doublesymmetry.trackplayer.models.QueueChangedEvent
+import com.doublesymmetry.trackplayer.models.MetadataApplier
 import com.doublesymmetry.trackplayer.models.PlayerConfig
 import com.doublesymmetry.trackplayer.models.PlaybackProgressUpdatedEvent
+import com.doublesymmetry.trackplayer.models.StreamMetadataExtractor
 import org.json.JSONObject
 
 class TrackPlayerModule internal constructor(private val context: ReactApplicationContext) : TrackPlayerSpec(context), Player.Listener {
@@ -43,6 +47,12 @@ class TrackPlayerModule internal constructor(private val context: ReactApplicati
 
   private val controller = MainThreadMediaController()
   private var lastStreamMetadata: MetadataReceivedEvent? = null
+  private var lastMediaMetadata: MediaMetadataChangedEvent? = null
+  // Cached PlayerConfig.autoUpdateMetadataFromStream — refreshed in setupPlayer.
+  // When true, ICY/ID3 updates rewrite the queued MediaItem so Now Playing /
+  // getActiveMediaItem follow the live title even without JS. When false, we
+  // only emit MetadataReceived and let the app mutate the queue itself.
+  @Volatile private var autoUpdateMetadataFromStream: Boolean = true
 
   // endregion
 
@@ -60,6 +70,7 @@ class TrackPlayerModule internal constructor(private val context: ReactApplicati
   override fun setupPlayer(map: ReadableMap) {
     val config = PlayerConfig.fromReadableMap(map)
     config.store(context)
+    autoUpdateMetadataFromStream = config.autoUpdateMetadataFromStream
 
     controller.run {
       val sessionToken = SessionToken(context, ComponentName(context, TrackPlayerPlaybackService::class.java))
@@ -636,6 +647,7 @@ class TrackPlayerModule internal constructor(private val context: ReactApplicati
 
   override fun onMediaItemTransition(mediaItem: MediaItem?, reason: Int) {
     lastStreamMetadata = null
+    lastMediaMetadata = null
     val mc = controller.get() ?: return
     val item = if (mediaItem != null) TrackPlayerMediaItem.fromMediaItem(mediaItem).toWritableMap() else null
     context.emitEvent(MediaItemTransitionEvent(item, mc.currentMediaItemIndex))
@@ -659,8 +671,12 @@ class TrackPlayerModule internal constructor(private val context: ReactApplicati
     context.emitEvent(PlaybackStateChangedEvent(state))
   }
 
+  // Effective MediaItem metadata changed (queue transitioned, an
+  // updateMetadata call landed, or the auto-update path rewrote the active
+  // item). This is what backs `getActiveMediaItem()` and the system Now
+  // Playing info, so this is the surface most apps want to observe.
   override fun onMediaMetadataChanged(mediaMetadata: MediaMetadata) {
-    val event = MetadataReceivedEvent(
+    val event = MediaMetadataChangedEvent(
       title = mediaMetadata.title?.toString(),
       artist = mediaMetadata.artist?.toString(),
       albumTitle = mediaMetadata.albumTitle?.toString(),
@@ -669,11 +685,35 @@ class TrackPlayerModule internal constructor(private val context: ReactApplicati
     )
     if (event.title == null && event.artist == null && event.albumTitle == null
       && event.artworkUri == null && event.genre == null) return
-    if (event == lastStreamMetadata) return
-    lastStreamMetadata = event
+    if (event == lastMediaMetadata) return
+    lastMediaMetadata = event
     context.emitEvent(event)
   }
 
+  // Raw stream-derived metadata (ICY blocks, ID3 frames, ...). Always emit
+  // the pre-merge view so consumers that need stream-truth (e.g. analytics
+  // or sanitization pipelines) see every frame.
+  //
+  // When `autoUpdateMetadataFromStream` is enabled (default), additionally
+  // rewrite the active MediaItem so the merged effective view picks up the
+  // change. That replaceMediaItem call triggers `onMediaMetadataChanged`,
+  // which then emits `MediaMetadataChanged` with the merged result —
+  // preserving any user-supplied fields (genre, album, etc.) the stream
+  // didn't include. The two events are intentionally separate: one for
+  // "what came in" (synchronous), one for "what the active item is now"
+  // (after the binder roundtrip lands).
+  override fun onMetadata(metadata: Metadata) {
+    val event = StreamMetadataExtractor.extract(metadata) ?: return
+    if (event != lastStreamMetadata) {
+      lastStreamMetadata = event
+      context.emitEvent(event)
+    }
+    if (autoUpdateMetadataFromStream) {
+      val mc = controller.get() ?: return
+      MetadataApplier.applyToCurrentMediaItem(mc, event)
+    }
+  }
+
   // endregion
 
   // region Helpers

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

@@ -9,6 +9,7 @@ enum class EmitEventType(val value: String) {
   PLAYBACK_STATE_CHANGED("event.playback-state-changed"),
   IS_PLAYING_CHANGED("event.is-playing-changed"),
   MEDIA_ITEM_TRANSITION("event.media-item-transition"),
+  MEDIA_METADATA_CHANGED("event.media-metadata-changed"),
   METADATA_RECEIVED("event.metadata-received"),
   PLAYBACK_ERROR("event.playback-error"),
   QUEUE_CHANGED("event.queue-changed"),
@@ -84,6 +85,35 @@ data class MetadataReceivedEvent(
   }
 }
 
+/**
+ * Carries the *effective* metadata of the currently active MediaItem after
+ * any merge between stream-derived metadata and user-supplied fields. Fires
+ * on track transitions, explicit updateMetadata calls, and (when
+ * autoUpdateMetadataFromStream is enabled) after the native side rewrites
+ * the active item in response to stream metadata.
+ *
+ * Mirrors Media3's Player.Listener.onMediaMetadataChanged callback.
+ */
+data class MediaMetadataChangedEvent(
+  val title: String?,
+  val artist: String?,
+  val albumTitle: String? = null,
+  val artworkUri: String? = null,
+  val genre: String? = null,
+): EmitEvent {
+  override val type = EmitEventType.MEDIA_METADATA_CHANGED
+
+  override fun pairs(): Array<Pair<String, Any>> {
+    val result = mutableListOf<Pair<String, Any>>()
+    title?.let { result.add("title" to it) }
+    artist?.let { result.add("artist" to it) }
+    albumTitle?.let { result.add("albumTitle" to it) }
+    artworkUri?.let { result.add("artworkUrl" to it) }
+    genre?.let { result.add("genre" to it) }
+    return result.toTypedArray()
+  }
+}
+
 class QueueChangedEvent : EmitEvent {
   override val type = EmitEventType.QUEUE_CHANGED
   override fun pairs(): Array<Pair<String, Any>> = arrayOf()

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

@@ -0,0 +1,59 @@
+/*
+ * Copyright (c) Double Symmetry GmbH
+ * Commercial use requires a license. See https://rntp.dev/pricing
+ */
+
+package com.doublesymmetry.trackplayer.models
+
+import android.net.Uri
+import androidx.media3.common.MediaMetadata
+import androidx.media3.common.Player
+
+/**
+ * Pure helper that writes a stream-derived [MetadataReceivedEvent] back into
+ * the [Player]'s current MediaItem.
+ *
+ * Used by [com.doublesymmetry.trackplayer.TrackPlayerModule.onMetadata] when
+ * `PlayerConfig.autoUpdateMetadataFromStream` is enabled (the default), so
+ * that:
+ *  - `getActiveMediaItem()` reflects the live ICY title.
+ *  - `MPNowPlayingInfoCenter`'s Android analogue (Media3 session → system
+ *    notification, Bluetooth, Android Auto) follows along.
+ *
+ * Lives outside [com.doublesymmetry.trackplayer.TrackPlayerModule] so it can
+ * be unit-tested against a real [androidx.media3.exoplayer.ExoPlayer] under
+ * Robolectric without spinning up a [androidx.media3.session.MediaController]
+ * + service.
+ */
+internal object MetadataApplier {
+
+  /**
+   * Merges [event]'s non-null fields onto the current item's [MediaMetadata]
+   * and dispatches a [Player.replaceMediaItem]. The new MediaItem reuses the
+   * existing URI so Media3 keeps playback uninterrupted.
+   *
+   * @return `true` if the mutation was dispatched, `false` if there is no
+   *         current item to update.
+   */
+  fun applyToCurrentMediaItem(player: Player, event: MetadataReceivedEvent): Boolean {
+    val idx = player.currentMediaItemIndex
+    if (idx < 0 || idx >= player.mediaItemCount) return false
+
+    val existing = player.getMediaItemAt(idx)
+    val newMeta = MediaMetadata.Builder()
+      .populate(existing.mediaMetadata)
+      .apply {
+        event.title?.let { setTitle(it) }
+        event.artist?.let { setArtist(it) }
+        event.albumTitle?.let { setAlbumTitle(it) }
+        event.artworkUri?.let { setArtworkUri(Uri.parse(it)) }
+        event.genre?.let { setGenre(it) }
+      }
+      .build()
+    val updated = existing.buildUpon()
+      .setMediaMetadata(newMeta)
+      .build()
+    player.replaceMediaItem(idx, updated)
+    return true
+  }
+}

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

@@ -31,6 +31,15 @@ data class PlayerConfig(
    */
   val handleAudioBecomingNoisy: Boolean = true,
 
+  /**
+   * When true (default), stream-derived metadata (ICY/ID3) is written back into
+   * the queued MediaItem so getActiveMediaItem() and the system Now Playing
+   * info (notification, Bluetooth, Android Auto) follow the live title — even
+   * when the JS bundle isn't running. When false, only the MetadataReceived
+   * event fires; apps mutate the queue themselves via updateMetadata().
+   */
+  val autoUpdateMetadataFromStream: Boolean = true,
+
   /**
    * The wake mode to use for the player.
    */
@@ -188,6 +197,7 @@ data class PlayerConfig(
       return PlayerConfig(
         contentType = map.getString("contentType") ?: "music",
         handleAudioBecomingNoisy = if (map.hasKey("handleAudioBecomingNoisy")) map.getBoolean("handleAudioBecomingNoisy") else true,
+        autoUpdateMetadataFromStream = if (map.hasKey("autoUpdateMetadataFromStream")) map.getBoolean("autoUpdateMetadataFromStream") else true,
         wakeMode = when (android?.getString("wakeMode")) {
           "none" -> WakeMode.NONE
           "local" -> WakeMode.LOCAL

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

@@ -0,0 +1,98 @@
+/*
+ * Copyright (c) Double Symmetry GmbH
+ * Commercial use requires a license. See https://rntp.dev/pricing
+ */
+
+package com.doublesymmetry.trackplayer.models
+
+import androidx.media3.common.MediaMetadata
+import androidx.media3.common.Metadata
+import androidx.media3.common.util.UnstableApi
+import androidx.media3.extractor.metadata.icy.IcyInfo
+
+/**
+ * Pure helper that turns a media3 [Metadata] bundle (delivered via
+ * [androidx.media3.common.Player.Listener.onMetadata]) into a
+ * [MetadataReceivedEvent] suitable for emitting to JS.
+ *
+ * Lives outside [com.doublesymmetry.trackplayer.TrackPlayerModule] so it can be
+ * unit-tested without spinning up a player.
+ */
+@UnstableApi
+internal object StreamMetadataExtractor {
+
+  /**
+   * Returns a [MetadataReceivedEvent] aggregated from all entries in [metadata],
+   * or `null` if none of the entries contributed any user-visible fields.
+   *
+   * Behavior:
+   * - Each entry's [Metadata.Entry.populateMediaMetadata] is invoked. media3's
+   *   built-in handlers cover ID3 ([androidx.media3.extractor.metadata.id3.TextInformationFrame]
+   *   `TIT2`/`TPE1`/`TALB`/`TCON`/…), ICY ([IcyInfo] → title), Vorbis
+   *   comments, MP4 MDTA, and more.
+   * - ICY's `StreamTitle` is conventionally formatted as `"Artist - Title"`
+   *   (Shoutcast/Icecast practice, not a spec). When [populateMediaMetadata]
+   *   leaves `artist` unset, we attempt to split on the first ` - ` to recover
+   *   artist + title separately. Same heuristic V4 and the iOS engine use.
+   * - [IcyInfo.url] is mapped into `artworkUri` to mirror the iOS behavior of
+   *   surfacing ICY `StreamUrl` (which some stations use to ship the current
+   *   track's artwork).
+   */
+  fun extract(metadata: Metadata): MetadataReceivedEvent? {
+    val builder = MediaMetadata.Builder()
+    var icyUrl: String? = null
+    for (i in 0 until metadata.length()) {
+      val entry = metadata.get(i)
+      entry.populateMediaMetadata(builder)
+      if (entry is IcyInfo) {
+        entry.url?.takeIf { it.isNotEmpty() }?.let { icyUrl = it }
+      }
+    }
+    val built = builder.build()
+    var title = built.title?.toString()
+    var artist = built.artist?.toString()
+
+    if (artist == null && title != null) {
+      val (parsedTitle, parsedArtist) = parseStreamTitle(title!!)
+      title = parsedTitle
+      artist = parsedArtist
+    }
+
+    val albumTitle = built.albumTitle?.toString()
+    val artworkUri = built.artworkUri?.toString() ?: icyUrl
+    val genre = built.genre?.toString()
+
+    if (title == null && artist == null && albumTitle == null && artworkUri == null && genre == null) {
+      return null
+    }
+    return MetadataReceivedEvent(
+      title = title,
+      artist = artist,
+      albumTitle = albumTitle,
+      artworkUri = artworkUri,
+      genre = genre,
+    )
+  }
+
+  /**
+   * Splits an ICY `StreamTitle` payload into `(title, artist)` using the
+   * de-facto Shoutcast convention `"Artist - Title"`.
+   *
+   * Returns `(trimmed, null)` when no ` - ` separator is present (e.g. talk
+   * radio with a single show title), and `(null, null)` for blank input.
+   * Only the first occurrence of ` - ` is treated as the separator, so a
+   * title containing additional `" - "` substrings (e.g. `"Artist - Song - Remix"`)
+   * yields `artist="Artist"`, `title="Song - Remix"`.
+   */
+  fun parseStreamTitle(raw: String): Pair<String?, String?> {
+    val trimmed = raw.trim()
+    if (trimmed.isEmpty()) return null to null
+    val sep = trimmed.indexOf(" - ")
+    if (sep >= 0) {
+      val artist = trimmed.substring(0, sep).trim()
+      val title = trimmed.substring(sep + 3).trim()
+      return title.ifEmpty { null } to artist.ifEmpty { null }
+    }
+    return trimmed to null
+  }
+}

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

@@ -23,21 +23,23 @@ data class TrackPlayerMediaItem(
   val duration: Double? = null,
   val isLive: Boolean? = null,
   val mimeType: String? = null,
-  val headers: Map<String, String>? = null
+  val headers: Map<String, String>? = null,
+  val extras: Bundle? = null
 ) {
   fun asMediaItem(): MediaItem {
     val id = mediaId ?: url
 
-    val extras = Bundle()
-    duration?.let { extras.putDouble("duration", it) }
-    isLive?.let { extras.putBoolean("isLive", it) }
+    val metadataExtras = Bundle()
+    duration?.let { metadataExtras.putDouble("duration", it) }
+    isLive?.let { metadataExtras.putBoolean("isLive", it) }
+    extras?.let { metadataExtras.putBundle(EXTRAS_KEY, it) }
 
     val metadata = MediaMetadata.Builder()
       .setTitle(title)
       .setArtist(artist)
       .setAlbumTitle(albumTitle)
       .setArtworkUri(artworkUrl?.let { Uri.parse(it) })
-      .setExtras(extras)
+      .setExtras(metadataExtras)
       .build()
 
     val requestExtras = Bundle()
@@ -81,10 +83,14 @@ data class TrackPlayerMediaItem(
     artworkUrl?.let { map.putString("artworkUrl", it) }
     duration?.let { map.putDouble("duration", it) }
     isLive?.let { map.putBoolean("isLive", it) }
+    extras?.let { map.putMap("extras", Arguments.fromBundle(it)) }
     return map
   }
 
   companion object {
+    /** Key under MediaMetadata.extras used to store the app-provided extras Bundle. */
+    private const val EXTRAS_KEY = "rntp.extras"
+
     private fun parseUrl(map: ReadableMap): Pair<String, Map<String, String>?> {
       if (!map.hasKey("url")) return "" to null
 
@@ -109,6 +115,10 @@ data class TrackPlayerMediaItem(
     fun fromReadableMap(map: ReadableMap): TrackPlayerMediaItem {
       val (url, headers) = parseUrl(map)
 
+      val extras = if (map.hasKey("extras")) {
+        map.getMap("extras")?.let { Arguments.toBundle(it) }
+      } else null
+
       return TrackPlayerMediaItem(
         mediaId = if (map.hasKey("mediaId")) map.getString("mediaId") else null,
         url = url,
@@ -120,12 +130,13 @@ data class TrackPlayerMediaItem(
         isLive = if (map.hasKey("isLive")) map.getBoolean("isLive") else null,
         mimeType = if (map.hasKey("mimeType")) map.getString("mimeType") else null,
         headers = headers,
+        extras = extras,
       )
     }
 
     fun fromMediaItem(mediaItem: MediaItem): TrackPlayerMediaItem {
       val metadata = mediaItem.mediaMetadata
-      val extras = metadata.extras
+      val metadataExtras = metadata.extras
       return TrackPlayerMediaItem(
         mediaId = mediaItem.mediaId,
         url = mediaItem.localConfiguration?.uri?.toString() ?: mediaItem.mediaId,
@@ -133,8 +144,9 @@ data class TrackPlayerMediaItem(
         artist = metadata.artist?.toString(),
         albumTitle = metadata.albumTitle?.toString(),
         artworkUrl = metadata.artworkUri?.toString(),
-        duration = extras?.getDouble("duration"),
-        isLive = if (extras?.containsKey("isLive") == true) extras.getBoolean("isLive") else null,
+        duration = metadataExtras?.getDouble("duration"),
+        isLive = if (metadataExtras?.containsKey("isLive") == true) metadataExtras.getBoolean("isLive") else null,
+        extras = metadataExtras?.getBundle(EXTRAS_KEY),
       )
     }
   }

package/android/src/test/java/com/doublesymmetry/trackplayer/models/EmitEventTest.kt

@@ -55,6 +55,39 @@ class EmitEventTest {
         assertEquals("title" to "Song", event.pairs()[0])
     }
 
+    @Test
+    fun `MediaMetadataChangedEvent uses media-metadata-changed event type`() {
+        val event = MediaMetadataChangedEvent(title = "Song", artist = "Artist")
+        assertEquals(EmitEventType.MEDIA_METADATA_CHANGED, event.type)
+        assertEquals("event.media-metadata-changed", event.type.value)
+    }
+
+    @Test
+    fun `MediaMetadataChangedEvent emits all set fields with normalized keys`() {
+        val event = MediaMetadataChangedEvent(
+            title = "Song",
+            artist = "Artist",
+            albumTitle = "Album",
+            artworkUri = "https://art",
+            genre = "Jazz",
+        )
+        val pairs = event.pairs().toMap()
+        assertEquals("Song", pairs["title"])
+        assertEquals("Artist", pairs["artist"])
+        assertEquals("Album", pairs["albumTitle"])
+        // artwork is published under the JS-facing `artworkUrl` key, matching
+        // the public MediaItem schema (not the Media3 `artworkUri`).
+        assertEquals("https://art", pairs["artworkUrl"])
+        assertEquals("Jazz", pairs["genre"])
+    }
+
+    @Test
+    fun `MediaMetadataChangedEvent only emits non-null fields`() {
+        val event = MediaMetadataChangedEvent(title = "Song", artist = null)
+        assertEquals(1, event.pairs().size)
+        assertEquals("title" to "Song", event.pairs()[0])
+    }
+
     @Test
     fun `QueueChangedEvent has empty pairs`() {
         assertEquals(0, QueueChangedEvent().pairs().size)