@rntp/player 5.0.0 → 5.1.1

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

@@ -22,6 +22,7 @@ class PlayerConfigTest {
 
         assertEquals("music", config.contentType)
         assertTrue(config.handleAudioBecomingNoisy)
+        assertTrue(config.autoUpdateMetadataFromStream)
         assertEquals(WakeMode.NONE, config.wakeMode)
         assertFalse(config.skipSilenceEnabled)
         assertEquals(listOf(PlayerCommand.PLAY_PAUSE), config.availableCommands)
@@ -48,6 +49,7 @@ class PlayerConfigTest {
         val config = PlayerConfig(
             contentType = "speech",
             handleAudioBecomingNoisy = false,
+            autoUpdateMetadataFromStream = false,
             wakeMode = WakeMode.NETWORK,
             skipSilenceEnabled = true,
             forwardInterval = 30L,
@@ -66,6 +68,7 @@ class PlayerConfigTest {
 
         assertEquals("speech", loaded.contentType)
         assertFalse(loaded.handleAudioBecomingNoisy)
+        assertFalse(loaded.autoUpdateMetadataFromStream)
         assertEquals(WakeMode.NETWORK, loaded.wakeMode)
         assertTrue(loaded.skipSilenceEnabled)
         assertEquals(30L, loaded.forwardInterval)
@@ -382,6 +385,36 @@ class PlayerConfigTest {
         assertEquals(RemoteControlHandling.JS, config.remoteControlHandling)
     }
 
+    @Test
+    fun `fromReadableMap defaults autoUpdateMetadataFromStream to true`() {
+        val map = mockk<ReadableMap>(relaxed = true) {
+            every { getString("contentType") } returns null
+            every { getMap("android") } returns null
+            every { getMap("cache") } returns null
+            every { getMap("progressSync") } returns null
+            every { hasKey(any()) } returns false
+        }
+
+        val config = PlayerConfig.fromReadableMap(map)
+        assertTrue(config.autoUpdateMetadataFromStream)
+    }
+
+    @Test
+    fun `fromReadableMap parses autoUpdateMetadataFromStream when false`() {
+        val map = mockk<ReadableMap>(relaxed = true) {
+            every { getString("contentType") } returns null
+            every { getMap("android") } returns null
+            every { getMap("cache") } returns null
+            every { getMap("progressSync") } returns null
+            every { hasKey(any()) } returns false
+            every { hasKey("autoUpdateMetadataFromStream") } returns true
+            every { getBoolean("autoUpdateMetadataFromStream") } returns false
+        }
+
+        val config = PlayerConfig.fromReadableMap(map)
+        assertFalse(config.autoUpdateMetadataFromStream)
+    }
+
     @Test
     fun `fromReadableMap with null android section defaults wakeMode to NONE`() {
         val map = mockk<ReadableMap>(relaxed = true) {

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

@@ -0,0 +1,254 @@
+/*
+ * Copyright (c) Double Symmetry GmbH
+ * Commercial use requires a license. See https://rntp.dev/pricing
+ */
+
+package com.doublesymmetry.trackplayer.models
+
+import androidx.media3.common.Format
+import androidx.media3.common.Metadata
+import androidx.media3.extractor.metadata.MetadataInputBuffer
+import androidx.media3.extractor.metadata.icy.IcyDecoder
+import androidx.media3.extractor.metadata.icy.IcyHeaders
+import androidx.media3.extractor.metadata.icy.IcyInfo
+import androidx.media3.extractor.metadata.id3.TextInformationFrame
+import com.google.common.collect.ImmutableList
+import java.nio.ByteBuffer
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertNotNull
+import org.junit.Assert.assertNull
+import org.junit.Test
+import org.junit.runner.RunWith
+import org.robolectric.RobolectricTestRunner
+
+/**
+ * Validates that the same parser path that ExoPlayer's
+ * [androidx.media3.exoplayer.source.ProgressiveMediaPeriod] uses for live ICY
+ * streams produces the metadata our JS layer expects. We feed the real
+ * [IcyDecoder] raw byte payloads in the exact wire format radio.co /
+ * klubradio.hu (Shoutcast/Icecast) emit, and assert the aggregated
+ * [MetadataReceivedEvent].
+ *
+ * Repro context — https://github.com/doublesymmetry/react-native-track-player/issues/2638
+ *  - https://streamer.radio.co/s51a438b13/listen
+ *  - https://stream.klubradio.hu:8443/
+ */
+@RunWith(RobolectricTestRunner::class)
+class StreamMetadataExtractorTest {
+
+  // ---- parseStreamTitle ----
+
+  @Test
+  fun `parseStreamTitle splits Artist - Title`() {
+    val (title, artist) = StreamMetadataExtractor.parseStreamTitle("Daft Punk - Get Lucky")
+    assertEquals("Get Lucky", title)
+    assertEquals("Daft Punk", artist)
+  }
+
+  @Test
+  fun `parseStreamTitle keeps single string as title`() {
+    val (title, artist) = StreamMetadataExtractor.parseStreamTitle("Morning News")
+    assertEquals("Morning News", title)
+    assertNull(artist)
+  }
+
+  @Test
+  fun `parseStreamTitle splits only on first separator`() {
+    val (title, artist) =
+      StreamMetadataExtractor.parseStreamTitle("Daft Punk - Get Lucky - Radio Edit")
+    assertEquals("Get Lucky - Radio Edit", title)
+    assertEquals("Daft Punk", artist)
+  }
+
+  @Test
+  fun `parseStreamTitle trims surrounding whitespace`() {
+    val (title, artist) = StreamMetadataExtractor.parseStreamTitle("  Artist  -  Song  ")
+    assertEquals("Song", title)
+    assertEquals("Artist", artist)
+  }
+
+  @Test
+  fun `parseStreamTitle returns nulls for blank input`() {
+    val (title, artist) = StreamMetadataExtractor.parseStreamTitle("   ")
+    assertNull(title)
+    assertNull(artist)
+  }
+
+  @Test
+  fun `parseStreamTitle does not split on dash without surrounding spaces`() {
+    // "U-Turn" should NOT be split — Shoutcast convention uses " - " (spaces).
+    val (title, artist) = StreamMetadataExtractor.parseStreamTitle("U-Turn")
+    assertEquals("U-Turn", title)
+    assertNull(artist)
+  }
+
+  // ---- extract: synthetic IcyInfo entries ----
+
+  @Test
+  fun `extract from IcyInfo with Artist - Title splits both fields`() {
+    val info = IcyInfo(ByteArray(0), "Daft Punk - Get Lucky", null)
+    val event = StreamMetadataExtractor.extract(Metadata(info))
+
+    assertNotNull(event)
+    assertEquals("Get Lucky", event!!.title)
+    assertEquals("Daft Punk", event.artist)
+    assertNull(event.albumTitle)
+    assertNull(event.artworkUri)
+    assertNull(event.genre)
+  }
+
+  @Test
+  fun `extract from IcyInfo with single title leaves artist null`() {
+    val info = IcyInfo(ByteArray(0), "Morning Talk Show", null)
+    val event = StreamMetadataExtractor.extract(Metadata(info))
+
+    assertNotNull(event)
+    assertEquals("Morning Talk Show", event!!.title)
+    assertNull(event.artist)
+  }
+
+  @Test
+  fun `extract from IcyInfo with null title returns null event`() {
+    val info = IcyInfo(ByteArray(0), null, null)
+    val event = StreamMetadataExtractor.extract(Metadata(info))
+    assertNull(event)
+  }
+
+  @Test
+  fun `extract from empty Metadata returns null`() {
+    val event = StreamMetadataExtractor.extract(Metadata())
+    assertNull(event)
+  }
+
+  @Test
+  fun `extract maps IcyInfo url into artworkUri`() {
+    val info = IcyInfo(ByteArray(0), "Artist - Song", "https://example.com/cover.jpg")
+    val event = StreamMetadataExtractor.extract(Metadata(info))
+
+    assertNotNull(event)
+    assertEquals("https://example.com/cover.jpg", event!!.artworkUri)
+  }
+
+  @Test
+  fun `extract ignores empty IcyInfo url`() {
+    val info = IcyInfo(ByteArray(0), "Artist - Song", "")
+    val event = StreamMetadataExtractor.extract(Metadata(info))
+
+    assertNotNull(event)
+    assertNull(event!!.artworkUri)
+  }
+
+  // ---- extract: combined IcyInfo + IcyHeaders ----
+
+  @Test
+  fun `extract pulls genre from IcyHeaders alongside IcyInfo title`() {
+    // ProgressiveMediaPeriod emits IcyHeaders + IcyInfo together on first metadata
+    // for radio.co / klubradio.hu (icy-genre header from the response).
+    val info = IcyInfo(ByteArray(0), "Radiohead - No Surprises", null)
+    val headers = IcyHeaders(
+      /* bitrate = */ 128_000,
+      /* genre = */ "Indie Rock",
+      /* name = */ "Test Radio",
+      /* url = */ null,
+      /* isPublic = */ true,
+      /* metadataInterval = */ 16_000,
+    )
+    val event = StreamMetadataExtractor.extract(Metadata(info, headers))
+
+    assertNotNull(event)
+    assertEquals("No Surprises", event!!.title)
+    assertEquals("Radiohead", event.artist)
+    assertEquals("Indie Rock", event.genre)
+  }
+
+  // ---- extract: ID3 frames (covers podcasts / MP3 streams w/ embedded ID3) ----
+
+  @Test
+  fun `extract from ID3 frames sets title and artist without splitting`() {
+    // TIT2 = title, TPE1 = lead artist. When both arrive populated, the
+    // Shoutcast " - " heuristic must NOT split the title.
+    val title = TextInformationFrame("TIT2", null, ImmutableList.of("Song - With Dash"))
+    val artist = TextInformationFrame("TPE1", null, ImmutableList.of("Artist Name"))
+    val event = StreamMetadataExtractor.extract(Metadata(title, artist))
+
+    assertNotNull(event)
+    assertEquals("Song - With Dash", event!!.title)
+    assertEquals("Artist Name", event.artist)
+  }
+
+  // ---- extract: real captured ICY payloads from the reported streams ----
+  //
+  // The strings below are NOT illustrative examples — they are the literal
+  // bytes returned by the two stations the original bug report links to,
+  // captured live from production endpoints.
+  //
+  // Capture procedure (reproducible from `scripts/capture_icy.py`):
+  //   $ scripts/capture_icy.py https://streamer.radio.co/s51a438b13/listen out.txt
+  //   $ scripts/capture_icy.py https://stream.klubradio.hu:8443/        out.txt
+  // Both servers respond with `icy-metaint: 16000` and emit Shoutcast-style
+  // `StreamTitle='…';` blocks. NUL padding to the 16-byte block boundary has
+  // been stripped (matching IcyDecoder's behavior on the real device).
+
+  @Test
+  fun `extract real radio_co track-change payload (Sonia Odisho - Eked D Bayet)`() {
+    // Captured 2026-05-20 from https://streamer.radio.co/s51a438b13/listen
+    // Raw bytes (hex): 53 74 72 65 61 6d 54 69 74 6c 65 3d 27 53 6f 6e 69 61 …
+    val event = decodeAndExtract("StreamTitle='Sonia Odisho - Eked D Bayet';")
+    assertNotNull(event)
+    assertEquals("Eked D Bayet", event!!.title)
+    assertEquals("Sonia Odisho", event.artist)
+    assertNull(event.artworkUri)
+  }
+
+  @Test
+  fun `extract real radio_co between-songs empty StreamTitle`() {
+    // Same source, captured immediately before the track-change block above.
+    // Servers commonly emit `StreamTitle='';` during silence/transitions —
+    // the extractor must NOT synthesize a bogus event in that case.
+    val event = decodeAndExtract("StreamTitle='';")
+    assertNull(event)
+  }
+
+  @Test
+  fun `extract real klubradio_hu talk-segment empty StreamTitle`() {
+    // Captured 2026-05-20 from https://stream.klubradio.hu:8443/ (redirects
+    // to hu-stream03.klubradio.hu:8443/bpstream). The Hungarian talk station
+    // sends ICY metadata frames but with empty StreamTitle during talk
+    // segments — over a 60s window only this empty payload was observed.
+    val event = decodeAndExtract("StreamTitle='';")
+    assertNull(event)
+  }
+
+  @Test
+  fun `extract handles UTF-8 multibyte chars in real-world StreamTitle`() {
+    // Both endpoints serve UTF-8; while the captured radio.co block above
+    // was pure ASCII, exercising the high-byte path is critical because
+    // IcyDecoder falls back to ISO-8859-1 on UTF-8 decode failure (would
+    // mangle Hungarian/Icelandic/etc characters).
+    val event = decodeAndExtract("StreamTitle='Sigur Rós - Hoppípolla';")
+    assertNotNull(event)
+    assertEquals("Hoppípolla", event!!.title)
+    assertEquals("Sigur Rós", event.artist)
+  }
+
+  // ---- helpers ----
+
+  /**
+   * Drives the real [IcyDecoder] used by ExoPlayer's [ProgressiveMediaPeriod]
+   * with the given Shoutcast metadata string, then runs the result through
+   * [StreamMetadataExtractor]. This exercises the same code path live streams
+   * hit at runtime.
+   */
+  private fun decodeAndExtract(icyString: String): MetadataReceivedEvent? {
+    val bytes = icyString.toByteArray(Charsets.UTF_8)
+    val buffer = MetadataInputBuffer().apply {
+      data = ByteBuffer.allocate(bytes.size).apply {
+        put(bytes)
+        flip()
+      }
+    }
+    val decoded = IcyDecoder().decode(buffer)
+    assertNotNull("IcyDecoder should produce a Metadata bundle", decoded)
+    return StreamMetadataExtractor.extract(decoded!!)
+  }
+}

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

@@ -26,6 +26,40 @@ class TrackPlayerMediaItemTest {
         // Arguments.createMap() and createArray() call into native code; replace with JavaOnlyMap.
         mockkStatic(Arguments::class)
         every { Arguments.createMap() } answers { JavaOnlyMap() }
+        // toBundle / fromBundle traverse the map with native helpers; for tests, hand-roll
+        // a small subset that covers the JSON-shaped values our extras use.
+        every { Arguments.toBundle(any()) } answers {
+            val src = firstArg<ReadableMap?>() ?: return@answers null
+            val bundle = android.os.Bundle()
+            val it = src.keySetIterator()
+            while (it.hasNextKey()) {
+                val k = it.nextKey()
+                when (src.getType(k)) {
+                    ReadableType.Null -> bundle.putString(k, null)
+                    ReadableType.Boolean -> bundle.putBoolean(k, src.getBoolean(k))
+                    ReadableType.Number -> bundle.putDouble(k, src.getDouble(k))
+                    ReadableType.String -> bundle.putString(k, src.getString(k))
+                    else -> {} // skip nested maps/arrays for these tests
+                }
+            }
+            bundle
+        }
+        every { Arguments.fromBundle(any()) } answers {
+            // Arguments.fromBundle(Bundle): WritableMap is non-null in current RN.
+            val src = firstArg<android.os.Bundle>()
+            val map = JavaOnlyMap()
+            for (k in src.keySet()) {
+                when (val v = src.get(k)) {
+                    null -> map.putNull(k)
+                    is Boolean -> map.putBoolean(k, v)
+                    is Double -> map.putDouble(k, v)
+                    is Int -> map.putInt(k, v)
+                    is String -> map.putString(k, v)
+                    else -> {} // skip nested types for these tests
+                }
+            }
+            map
+        }
     }
 
     @After
@@ -377,4 +411,172 @@ class TrackPlayerMediaItemTest {
         assertEquals("cast-item-id", item.url)
         assertEquals("Cast Track", item.title)
     }
+
+    // ---- extras (app-defined payload) ----
+
+    @Test
+    fun `fromReadableMap parses extras when present`() {
+        val extrasMap = mockk<ReadableMap>(relaxed = true) {
+            every { keySetIterator() } returns mockk {
+                every { hasNextKey() } returnsMany listOf(true, true, true, false)
+                every { nextKey() } returnsMany listOf("source", "isrc", "weight")
+            }
+            every { getType("source") } returns ReadableType.String
+            every { getString("source") } returns "recommendations"
+            every { getType("isrc") } returns ReadableType.String
+            every { getString("isrc") } returns "USRC17607839"
+            every { getType("weight") } returns ReadableType.Number
+            every { getDouble("weight") } returns 0.85
+        }
+
+        val map = mockk<ReadableMap>(relaxed = true) {
+            every { hasKey("url") } returns true
+            every { getType("url") } returns mockk { every { name } returns "String" }
+            every { getString("url") } returns "https://example.com/track.mp3"
+            every { hasKey("mediaId") } returns false
+            every { hasKey("title") } returns false
+            every { hasKey("artist") } returns false
+            every { hasKey("albumTitle") } returns false
+            every { hasKey("artworkUrl") } returns false
+            every { hasKey("duration") } returns false
+            every { hasKey("isLive") } returns false
+            every { hasKey("mimeType") } returns false
+            every { hasKey("extras") } returns true
+            every { getMap("extras") } returns extrasMap
+        }
+
+        val item = TrackPlayerMediaItem.fromReadableMap(map)
+
+        assertNotNull(item.extras)
+        assertEquals("recommendations", item.extras!!.getString("source"))
+        assertEquals("USRC17607839", item.extras!!.getString("isrc"))
+        assertEquals(0.85, item.extras!!.getDouble("weight"), 0.001)
+    }
+
+    @Test
+    fun `fromReadableMap leaves extras null when absent`() {
+        val map = mockk<ReadableMap>(relaxed = true) {
+            every { hasKey("url") } returns true
+            every { getType("url") } returns mockk { every { name } returns "String" }
+            every { getString("url") } returns "https://example.com/track.mp3"
+            every { hasKey("mediaId") } returns false
+            every { hasKey("title") } returns false
+            every { hasKey("artist") } returns false
+            every { hasKey("albumTitle") } returns false
+            every { hasKey("artworkUrl") } returns false
+            every { hasKey("duration") } returns false
+            every { hasKey("isLive") } returns false
+            every { hasKey("mimeType") } returns false
+            every { hasKey("extras") } returns false
+        }
+
+        val item = TrackPlayerMediaItem.fromReadableMap(map)
+        assertNull(item.extras)
+    }
+
+    @Test
+    fun `asMediaItem stores extras under a namespaced key without polluting known fields`() {
+        val payload = android.os.Bundle().apply {
+            putString("source", "recommendations")
+            putString("isrc", "USRC17607839")
+        }
+        val item = TrackPlayerMediaItem(
+            url = "https://example.com/track.mp3",
+            duration = 120.0,
+            isLive = false,
+            extras = payload,
+        )
+
+        val mediaItem = item.asMediaItem()
+        val metadataExtras = mediaItem.mediaMetadata.extras
+
+        assertNotNull(metadataExtras)
+        // Known fields still live at the top level of the metadata extras bundle…
+        assertEquals(120.0, metadataExtras!!.getDouble("duration"), 0.001)
+        assertFalse(metadataExtras.getBoolean("isLive"))
+        // …and the app payload is nested under our namespaced key.
+        val nested = metadataExtras.getBundle("rntp.extras")
+        assertNotNull(nested)
+        assertEquals("recommendations", nested!!.getString("source"))
+        assertEquals("USRC17607839", nested.getString("isrc"))
+    }
+
+    @Test
+    fun `asMediaItem omits extras bundle when no extras provided`() {
+        val item = TrackPlayerMediaItem(
+            url = "https://example.com/track.mp3",
+        )
+
+        val mediaItem = item.asMediaItem()
+        val metadataExtras = mediaItem.mediaMetadata.extras
+
+        // The metadata extras bundle is always created (for duration/isLive),
+        // but our namespaced key should be absent.
+        assertNotNull(metadataExtras)
+        assertFalse(metadataExtras!!.containsKey("rntp.extras"))
+    }
+
+    @Test
+    fun `toWritableMap includes extras when present`() {
+        val payload = android.os.Bundle().apply {
+            putString("source", "recommendations")
+            putDouble("weight", 0.85)
+        }
+        val item = TrackPlayerMediaItem(
+            url = "https://example.com/track.mp3",
+            extras = payload,
+        )
+
+        val map = item.toWritableMap()
+        assertTrue(map.hasKey("extras"))
+        val extras = map.getMap("extras")
+        assertNotNull(extras)
+        assertEquals("recommendations", extras!!.getString("source"))
+        assertEquals(0.85, extras.getDouble("weight"), 0.001)
+    }
+
+    @Test
+    fun `toWritableMap omits extras when absent`() {
+        val item = TrackPlayerMediaItem(
+            url = "https://example.com/track.mp3",
+        )
+
+        val map = item.toWritableMap()
+        assertFalse(map.hasKey("extras"))
+    }
+
+    @Test
+    fun `extras survive full round-trip through Media3 MediaItem`() {
+        val payload = android.os.Bundle().apply {
+            putString("source", "recommendations")
+            putString("isrc", "USRC17607839")
+            putDouble("weight", 0.85)
+            putBoolean("explicit", true)
+        }
+        val original = TrackPlayerMediaItem(
+            mediaId = "t-1",
+            url = "https://example.com/track.mp3",
+            title = "Song",
+            duration = 60.0,
+            extras = payload,
+        )
+
+        val restored = TrackPlayerMediaItem.fromMediaItem(original.asMediaItem())
+
+        assertEquals("t-1", restored.mediaId)
+        assertEquals("Song", restored.title)
+        assertEquals(60.0, restored.duration!!, 0.001)
+        assertNotNull(restored.extras)
+        assertEquals("recommendations", restored.extras!!.getString("source"))
+        assertEquals("USRC17607839", restored.extras!!.getString("isrc"))
+        assertEquals(0.85, restored.extras!!.getDouble("weight"), 0.001)
+        assertTrue(restored.extras!!.getBoolean("explicit"))
+    }
+
+    @Test
+    fun `fromMediaItem leaves extras null when source has none`() {
+        val original = TrackPlayerMediaItem(url = "https://example.com/track.mp3")
+        val restored = TrackPlayerMediaItem.fromMediaItem(original.asMediaItem())
+        assertNull(restored.extras)
+    }
 }

package/ios/TrackPlayer.swift

@@ -20,6 +20,8 @@ class TrackPlayer: RCTEventEmitter {
   private var progressSyncTimer: Timer?
   private var progressSyncIntervalSeconds: Double = 0
   private var progressSyncHttpUrl: String?
+  private var autoUpdateMetadataFromStream: Bool = true
+  private var lastEmittedMediaMetadata: MediaMetadataChangedEvent?
   private var progressSyncHttpHeaders: [String: String]?
 
   private var sleepTimerController: SleepTimerController?
@@ -76,6 +78,7 @@ class TrackPlayer: RCTEventEmitter {
     audioCache = cache
 
     let handleNoisy = config["handleAudioBecomingNoisy"] as? Bool ?? true
+    autoUpdateMetadataFromStream = config["autoUpdateMetadataFromStream"] as? Bool ?? true
     player = AudioPlayer(handleAudioBecomingNoisy: handleNoisy, cache: cache)
     player.preloadWindow = preloadWindow
     bindPlayerCallbacks()
@@ -312,6 +315,9 @@ class TrackPlayer: RCTEventEmitter {
     )
 
     player.updateMetadata(at: idx, with: updated)
+    if idx == player.currentIndex {
+      emitMediaMetadataChangedIfNeeded(for: updated)
+    }
   }
 
   // MARK: - State Getters (sync)
@@ -540,14 +546,18 @@ class TrackPlayer: RCTEventEmitter {
     let mediaItem = item as? MediaItem
     let dict = mediaItem?.toDictionary()
     BrowseTreeStore.shared.updateNowPlaying(mediaId: mediaItem?.mediaId)
+    lastEmittedMediaMetadata = nil
     emitEvent(event: MediaItemTransitionEvent(item: dict, index: index))
+    emitMediaMetadataChangedIfNeeded(for: mediaItem)
   }
 
   func handleMetadataReceived(_ metadata: StreamMetadata) {
+    emitEvent(event: MetadataReceivedEvent(metadata: metadata))
+
+    guard autoUpdateMetadataFromStream else { return }
     let idx = player.currentIndex
     guard idx >= 0 && idx < player.items.count,
           let existing = player.items[idx] as? MediaItem else { return }
-
     let updated = existing.withMetadata(
       title: metadata.title.map { .some($0) },
       artist: metadata.artist.map { .some($0) },
@@ -555,7 +565,23 @@ class TrackPlayer: RCTEventEmitter {
       artworkUrl: metadata.artworkUri.flatMap { MediaURL(object: $0) }.map { .some($0) }
     )
     player.updateMetadata(at: idx, with: updated)
-    emitEvent(event: MetadataReceivedEvent(metadata: metadata))
+    emitMediaMetadataChangedIfNeeded(for: updated)
+  }
+
+  /// iOS MediaItem has no `genre`; Android may include it in this event.
+  private func emitMediaMetadataChangedIfNeeded(for item: MediaItem?) {
+    guard let item else { return }
+    let event = MediaMetadataChangedEvent(
+      title: item.title,
+      artist: item.artist,
+      albumTitle: item.albumTitle,
+      artworkUrl: item.artworkUrl.map { $0.isLocal ? $0.value.path : $0.value.absoluteString },
+      genre: nil
+    )
+    if event.isEmpty { return }
+    if event == lastEmittedMediaMetadata { return }
+    lastEmittedMediaMetadata = event
+    emitEvent(event: event)
   }
 
   // MARK: - Progress Sync

package/ios/models/EmitEvent.swift

@@ -16,6 +16,7 @@ enum EmitEventType: String, CaseIterable {
   case RemoteStop = "event.remote-stop"
   case RemoteSeek = "event.remote-seek"
   case MetadataReceived = "event.metadata-received"
+  case MediaMetadataChanged = "event.media-metadata-changed"
   case RemoteSkipForward = "event.remote-skip-forward"
   case RemoteSkipBackward = "event.remote-skip-backward"
   case PlaybackProgressUpdated = "event.playback-progress-updated"
@@ -127,6 +128,33 @@ struct MetadataReceivedEvent: EmitEvent {
   }
 }
 
+/// Effective metadata of the currently active MediaItem after any merge of
+/// stream-derived metadata onto user-supplied fields. Mirrors Android's
+/// `MediaMetadataChangedEvent` and the JS `Event.MediaMetadataChanged`.
+struct MediaMetadataChangedEvent: EmitEvent, Equatable {
+  let title: String?
+  let artist: String?
+  let albumTitle: String?
+  let artworkUrl: String?
+  let genre: String?
+
+  var eventType: EmitEventType { .MediaMetadataChanged }
+  var body: [String: Any] {
+    var result: [String: Any] = [:]
+    if let title { result["title"] = title }
+    if let artist { result["artist"] = artist }
+    if let albumTitle { result["albumTitle"] = albumTitle }
+    if let artworkUrl { result["artworkUrl"] = artworkUrl }
+    if let genre { result["genre"] = genre }
+    return result
+  }
+
+  var isEmpty: Bool {
+    return title == nil && artist == nil && albumTitle == nil &&
+      artworkUrl == nil && genre == nil
+  }
+}
+
 struct RemoteSkipForwardEvent: EmitEvent {
   let interval: Double
 

package/ios/models/MediaItem.swift

@@ -16,8 +16,9 @@ struct MediaItem {
   let artworkUrl: MediaURL?
   let duration: Double?
   let isLiveStream: Bool?
+  let extras: [String: Any]?
 
-  init(mediaId: String, url: MediaURL, title: String?, artist: String?, albumTitle: String?, artworkUrl: MediaURL?, duration: Double? = nil, isLiveStream: Bool? = nil) {
+  init(mediaId: String, url: MediaURL, title: String?, artist: String?, albumTitle: String?, artworkUrl: MediaURL?, duration: Double? = nil, isLiveStream: Bool? = nil, extras: [String: Any]? = nil) {
     self.mediaId = mediaId
     self.url = url
     self.title = title
@@ -26,6 +27,7 @@ struct MediaItem {
     self.artworkUrl = artworkUrl
     self.duration = duration
     self.isLiveStream = isLiveStream
+    self.extras = extras
   }
 
   init(data: [String: Any]) {
@@ -40,8 +42,9 @@ struct MediaItem {
     let artworkUrl = MediaURL(object: data["artworkUrl"])
     let duration = data["duration"] as? Double
     let isLiveStream = data["isLive"] as? Bool
+    let extras = data["extras"] as? [String: Any]
 
-    self.init(mediaId: mediaId, url: url, title: title, artist: artist, albumTitle: albumTitle, artworkUrl: artworkUrl, duration: duration, isLiveStream: isLiveStream)
+    self.init(mediaId: mediaId, url: url, title: title, artist: artist, albumTitle: albumTitle, artworkUrl: artworkUrl, duration: duration, isLiveStream: isLiveStream, extras: extras)
   }
 }
 
@@ -60,7 +63,8 @@ extension MediaItem {
       albumTitle: albumTitle ?? self.albumTitle,
       artworkUrl: artworkUrl ?? self.artworkUrl,
       duration: self.duration,
-      isLiveStream: self.isLiveStream
+      isLiveStream: self.isLiveStream,
+      extras: self.extras
     )
   }
 
@@ -77,6 +81,7 @@ extension MediaItem {
     }
     if let duration = duration { dict["duration"] = duration }
     if let isLiveStream = isLiveStream { dict["isLive"] = isLiveStream }
+    if let extras = extras { dict["extras"] = extras }
     return dict
   }
 }