React Native Track Player
Get V5 Access

Changelog

A log of notable additions, changes, and fixes shipped in RNTP.

v5.6.0 June 20, 2026

  • First-class web support — the same player API in the browser.
  • HLS (.m3u8) streams are cached like any other audio — no isLive workaround needed.

Added

Web platform — A web implementation of the player, so the same API runs in the browser.

Changed

isLive bypasses the cache — Live streams skip the cache and play directly, so their short-lived segments don’t churn it. iOS detects live HLS automatically (no `#EXT-X-ENDLIST`); on Android set `isLive` for live HLS.

Fixed

HLS caching — Cached HLS no longer fails with “resource unavailable”; segments are cached per-URL on iOS and Android.

Cast button tint — The Android cast button respects its configured tint color.

Foreground refresh — Android playback hooks refresh when the app returns to the foreground.

Active item after clearing the queue — `useActiveMediaItem` updates correctly after the queue is cleared on iOS.

v5.5.0 June 6, 2026

  • audioMixing — play layered over other apps without interrupting them.

Added

audioMixing — `exclusive` (default) interrupts other apps’ audio; `mix` plays layered over them without interrupting. On iOS this uses the AVAudioSession `.mixWithOthers` option; on Android `mix` requests no audio focus, so it won’t auto-pause for calls or resume.

v5.4.0 June 1, 2026

  • android.taskRemovedBehavior — stop playback when the app is removed from recents.
  • Android Auto — picking a track from a folder queues its siblings.

Added

android.taskRemovedBehavior — `continue` (default) keeps playback after the app is swiped from recents; `stop` tears down the service and clears the queue.

Fixed

Android Auto browse playback — Selecting a track inside a browsable folder loads playable siblings as the queue at the correct index.

v5.3.0 May 28, 2026

  • Android background handlers now receive BackgroundEvent objects (type + fields).

Changed

registerBackgroundEventHandler (iOS) — Logs a one-time __DEV__ warning when called on iOS (still a no-op).

Fixed

registerBackgroundEventHandler (Android) — Headless JS now normalizes native { event, payload } into BackgroundEvent before calling your handler, so event.type and payload fields match TypeScript. Apps that relied on the raw Headless shape must switch to BackgroundEvent. Closes #2644.

v5.2.0 May 27, 2026

  • Local file playback — file://, asset://, bare paths, and require() assets all resolve correctly on both platforms.

Added

Local file support — Play audio from the local filesystem (file://), platform assets (asset:// or bare names like "song.mp3"), and Metro-bundled require() references.

MediaUrl.bundle (iOS) — Pass { uri: "song.mp3", bundle: "Sounds" } to load from a .bundle resource directory. Ignored when the URI already has a scheme.

Changed

MediaUrl type — Now accepts bare filesystem paths ("/path/to/song.mp3" → file://), bare asset names ("song.mp3" → asset://), and { uri: number } for require() inside the object form.

Chromecast mediaUri guard (Android) — RequestMetadata.mediaUri is now only set for http/https URLs. Previously it was set for everything except file://, leaking unreachable local URIs to Chromecast.

v5.1.3 May 23, 2026

  • BrowseItem.extras — carry app-defined metadata through CarPlay and Android Auto into the queue.
  • ICY metadata events now fire on Android live streams.
  • ICY metadata is no longer processed as audio on Android.

Added

BrowseItem.extras — Attach app-defined payload to browse-tree items. When a playable item is selected from CarPlay or Android Auto, extras are loaded into the queue and returned unchanged from getActiveMediaItem, getQueue, and MediaItemTransition — same semantics as MediaItem.extras.

Fixed

Event.MetadataReceived (Android) — ICY/ID3 metadata events were not firing on live streams. Closes #2638.

ICY streams (Android) — Stream metadata blocks were being read as audio instead of stripped by the player. Closes #2638.

v5.1.2 May 21, 2026

Fixed

iOS New Architecture (RN 0.80) — Export `./package.json` so RN codegen can resolve the library on React Native 0.80. Fixes missing RNTrackPlayerSpec.h on iOS; RN 0.83+ and Android are unaffected.

v5.1.0 May 21, 2026

  • Stream-driven metadata (ICY/ID3) automatically updates the queued media item, keeping the lock screen and useActiveMediaItem in sync with the live title — no app code required.
  • New MediaMetadataChanged event for the effective merged view, alongside MetadataReceived for raw stream-truth.
  • Carry app-defined metadata alongside each media item with the new MediaItem.extras field.

Added

PlayerConfig.autoUpdateMetadataFromStream — Defaults to true. When enabled, incoming ICY/ID3 metadata is merged into the active MediaItem so getActiveMediaItem() and the system Now Playing info (lock screen, notification, CarPlay/Android Auto) reflect the live title without any JS code running. Set to false to receive MetadataReceived events 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 media item changes — track transitions, explicit updateMetadata calls, or the auto-update path landing a stream rewrite. Use this for UI that mirrors getActiveMediaItem() / the lock screen; reserve MetadataReceived for cases that need raw pre-merge stream-truth (e.g. scrobbling).

MediaItem.extras — Attach an opaque, app-defined payload to any media item. Stored verbatim by the player and returned unchanged from getActiveMediaItem, getQueue, and the MediaItemTransition event. Useful for recommendation source, ISRCs, internal IDs, and other metadata you want to travel with a track without polluting the typed fields. Must be JSON-serializable.

Changed

useActiveMediaItem — Now subscribes to MediaMetadataChanged instead of MetadataReceived. The returned item reflects the merged effective view of the active queue item.

Fixed

Event.MetadataReceived (Android) — Now fires for ICY/ID3 metadata updates on live streams. Combined StreamTitle values ("Artist - Title") are split into separate fields to match iOS. Closes #2638.

MediaItem headers (Android) — Per-item HTTP headers now override defaults injected by the underlying player, consistent with iOS.

v5.0.0 Released

  • Ground-up rewrite on Media3 (Android) and a modernised Swift core (iOS).
  • New TurboModule-friendly API surface and stricter, well-typed interfaces.
  • First-class Android Auto and CarPlay integration via setBrowseTree.

Looking for the raw commit log? See GitHub releases.

ende