doublesymmetry/react-native-track-player v5.1.0

5.1.0

on GitHub

Stream metadata and app-defined payloads get first-class support in this release. Live ICY/ID3 updates can flow straight into the active queue item and system Now Playing UI by default, and you can attach opaque per-track data without stretching the typed MediaItem fields.

Full notes: rntp.dev/changelog#5.1.0

Highlights

• Stream-driven metadata — ICY/ID3 updates automatically merge into the active MediaItem, keeping the lock screen, notification, CarPlay/Android Auto, and useActiveMediaItem in sync with the live title — no app code required (opt out via PlayerConfig.autoUpdateMetadataFromStream).
• MediaMetadataChanged — new event for the effective merged metadata view; use alongside MetadataReceived when you need raw stream-truth (e.g. scrobbling).
• MediaItem.extras — carry app-defined, JSON-serializable metadata with each queue item through getActiveMediaItem, getQueue, and MediaItemTransition.

Added

• PlayerConfig.autoUpdateMetadataFromStream (default: true) — when enabled, incoming ICY/ID3 metadata is merged into the active MediaItem so getActiveMediaItem() and system Now Playing reflect the live title without JS. Set to false to receive MetadataReceived only and update the queue yourself (e.g. to sanitize stream-supplied fields before they reach the UI).
• Event.MediaMetadataChanged — fires when the effective metadata of the active item changes (track transitions, explicit updateMetadata, or auto-update from the stream). Use for UI that mirrors getActiveMediaItem() / the lock screen; reserve MetadataReceived for pre-merge stream-truth.
• MediaItem.extras — opaque, app-defined payload stored verbatim by the player. Useful for recommendation source, ISRCs, internal IDs, and other data that should travel with a track without polluting typed fields.

Changed

• useActiveMediaItem — now subscribes to MediaMetadataChanged instead of MetadataReceived. The hook returns the merged effective view of the active queue item. If you relied on raw stream events in hook-driven UI, switch that logic to MetadataReceived (or disable auto-update and handle metadata yourself).

Fixed

• Event.MetadataReceived (Android) — now fires for ICY/ID3 metadata on live streams. Combined StreamTitle values ("Artist - Title") are split into separate fields to match iOS (#2638).
• MediaItem headers (Android) — per-item HTTP headers now override defaults injected by the underlying player, consistent with iOS.

Upgrade

npm install @rntp/player@5.1.0
# iOS
cd ios && pod install