v5.6.0

First-class web support brings the same player API to the browser. HLS (.m3u8) streams are now cached like any other audio — the isLive cache-bypass workaround is no longer needed.

Full notes: rntp.dev/changelog#5.6.0

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.

Upgrade

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

v5.5.0

audioMixing lets your player play layered over other apps without interrupting them — useful for ambient and meditation audio.

Full notes: rntp.dev/changelog#5.5.0

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).

Upgrade

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

v5.4.0

android.taskRemovedBehavior lets you choose whether playback stops when the app is removed from recents. Android Auto now queues a folder's playable siblings when you pick a track inside it.

Full notes: rntp.dev/changelog#5.4.0

Added

• android.taskRemovedBehavior — continue (default) keeps playback when 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 its playable siblings as the queue at the correct index.

Upgrade

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

v5.3.0

Android background handlers now receive BackgroundEvent objects (event.type + fields), matching the documented TypeScript API. Docs and a one-time iOS dev warning clarify how event delivery differs by platform.

Full notes: rntp.dev/changelog#5.3.0

Fixed

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

Changed

• registerBackgroundEventHandler (iOS) — logs a one-time __DEV__ warning when called (still a no-op). Use addEventListener for all events on iOS, including while audio plays in the background with UIBackgroundModes audio.

Upgrade

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

5.2.0

Local file playback gets first-class support. file://, asset://, bare paths, and require() assets all resolve correctly on both platforms.

Full notes: rntp.dev/changelog#5.2.0

Added

• Local file support — play audio from file:// URLs, platform assets (bare names like "song.mp3"), and require() references.
• MediaUrl.bundle (iOS) — { uri: "song.mp3", bundle: "Sounds" } loads from a .bundle resource directory.

Changed

• MediaUrl type — now accepts bare filesystem paths, bare asset names, and { uri: number } for require() inside the object form.
• Chromecast mediaUri guard (Android) — only set for http/https URLs, preventing unreachable local URIs from being sent to Chromecast.

Upgrade

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

5.1.3

Patch release — browse-tree extras and Android ICY stream metadata fixes.

Full notes: rntp.dev/changelog#5.1.3

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 (#2638).
• ICY streams (Android) — stream metadata blocks were being read as audio instead of stripped by the player (#2638).

Upgrade

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

5.1.2

Patch release for iOS New Architecture on React Native 0.80.

Full notes: rntp.dev/changelog#5.1.2

Fixed

• package.json exports (iOS, RN 0.80) — export ./package.json so RN codegen can resolve @rntp/player and emit RNTrackPlayerSpec.h. RN 0.83+ and Android are unaffected.

Upgrade

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

5.1.0

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

5.0.0

This is the first stable release of a complete rewrite of react-native-track-player, built from the ground up on the New Architecture.

Important

Starting with V5, react-native-track-player is commercially licensed. Personal and educational use remains free; commercial use requires a paid license — see rntp.dev/pricing. V4 (Apache-2.0) is frozen on the v4 branch and will not receive further updates.

V5 also ships as a new npm package: @rntp/player. The V4 package (react-native-track-player) remains as-is on its last release.

This release supersedes the V5 alpha and beta versions on npm — anyone on those should upgrade to 5.0.0.

Highlights

• TurboModule + JSI — synchronous state getters (getProgress(), getQueue(), isPlaying()) with no bridge overhead
• Media3 on Android — new native core for queueing, caching, and playback control
• Native CarPlay — first-class iOS car dashboard support via setBrowseTree(), the same call that drives Android Auto
• Sleep Timer — native countdown with optional volume fade-out, works reliably in the background
• Progress Sync — server-side progress tracking with a configurable HTTP endpoint and native persistence
• Audio caching — built-in caching layer for offline playback and bandwidth savings
• Preloading — background buffering of upcoming tracks for gapless-like playback
• React hooks — usePlaybackState, useIsPlaying, useProgress, useActiveMediaItem

Breaking changes

V5 is not backwards-compatible with V4. Both the native layers and the JS API have been rewritten.

There is no automated V4 → V5 migration path. The new API surface is small — most apps can migrate by following the Introduction, Installation, and Quick Start guides.

Package and license changes

• New npm package: V5 ships as @rntp/player. V4 remains published as react-native-track-player.
• License: V5 is commercially licensed — free for personal and educational use, paid for everything else. See rntp.dev/pricing for plans.
• V4 remains available under Apache-2.0 on the v4 branch, but will not receive further updates.

Requirements

• React Native 0.74 or later
• New Architecture enabled (Fabric + TurboModules)

Install

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