Migrating from react-native-track-player
Most playback and queue calls from react-native-track-player (RNTP) v4 keep their names and meaning in react-native-audio-browser. This page lists what changes.
RNTP v5 moved to a commercial license. react-native-audio-browser is MIT.
What ports over unchanged
These are the same calls with the same meaning. import them from react-native-audio-browser instead of react-native-track-player:
add, remove, move, skip, skipToNext, skipToPrevious, setQueue, getQueue, getTrack, removeUpcomingTracks, load, reset, retry, play, pause, stop, seekTo, seekBy, setRate, getRate, setVolume, getVolume, setRepeatMode, getRepeatMode, setPlayWhenReady, getPlayWhenReady, getActiveTrack, getActiveTrackIndex.
setupPlayer and updateOptions keep their names, but their options changed shape. See Player options.
The differences below are what to watch for.
Getters are synchronous — and there are hooks
RNTP getters return Promises; audio-browser getters return the value synchronously, and most have a reactive hook. Drop the await (awaiting a non-Promise returns the value, so this isn't urgent), and prefer the hook in React.
| RNTP v4 | audio-browser |
|---|---|
await getPosition() | getProgress().position |
await getDuration() | getProgress().duration |
await getBufferedPosition() | getProgress().buffered |
await getProgress() | getProgress() (sync) / usePolledProgress() |
await getState() | getPlayback().state |
await getPlaybackState() | getPlayback() / usePlayback() |
await getActiveTrack() | getActiveTrack() / useActiveTrack() |
await getQueue() | getQueue() / useQueue() |
await getRepeatMode() | getRepeatMode() / useRepeatMode() |
Two hook gotchas:
useProgresschanged meaning. RNTP'suseProgress(interval)is polling; its drop-in isusePolledProgress(intervalMs). audio-browser also has auseProgress(), but it's event-based and takes no interval. It stays still untilprogressUpdateEventIntervalis set. TypeScript rejectsuseProgress(2000); plain JS ignores the argument.useIsPlaying()→usePlayingState(), but the field is renamed: RNTP's{ playing, bufferingDuringPlay }becomes{ playing, buffering }.
Events: per-event on* / use*, no Event enum
RNTP centralizes events behind the Event enum with addEventListener / useTrackPlayerEvents. audio-browser exposes one emitter (and usually a hook) per event, and addListener returns an unsubscribe function (not a subscription with .remove()):
// RNTP
import TrackPlayer, { Event } from 'react-native-track-player'
const sub = TrackPlayer.addEventListener(
Event.PlaybackActiveTrackChanged,
(e) => {}
)
sub.remove()
// audio-browser
import { onActiveTrackChanged } from 'react-native-audio-browser'
const unsubscribe = onActiveTrackChanged.addListener((e) => {})
unsubscribe()RNTP Event.* | audio-browser |
|---|---|
PlaybackActiveTrackChanged | onActiveTrackChanged / useActiveTrack() |
PlaybackState | onPlaybackChanged / usePlayback() |
PlaybackProgressUpdated | onProgressUpdated / useProgress() |
PlaybackQueueEnded | onQueueEnded |
PlaybackError / PlayerError | onPlaybackError / usePlaybackError() |
PlaybackPlayWhenReadyChanged | onPlayWhenReadyChanged / usePlayWhenReady() |
Remote* (Play, Pause, Next, …) | handleRemote* to override, onRemote* to observe — see Remote Controls |
Metadata*Received | onTimedMetadata / onChapterMetadata / onTrackMetadata — see Metadata |
Delete the playback service
RNTP requires registerPlaybackService(() => require('./service')) and a service file that wires Event.RemotePlay → TrackPlayer.play(), etc. audio-browser has no playback service — the library wires the native side itself, and remote controls drive the player by default. Delete the service file and the registration call.
To customize a remote control, set a handleRemote* override (pass undefined to restore the default); to just observe, use onRemote*:
import { handleRemoteNext, skipToNext } from 'react-native-audio-browser'
// Override "next" (call the default action yourself if you still want it):
handleRemoteNext(() => skipToNext())
handleRemoteNext(undefined) // restore the defaultAudio interruptions (RNTP's Event.RemoteDuck) are handled natively, so the duck handler in your service can go too. On Android, android.audioContentType: 'speech' pauses on an interruption instead of ducking.
capabilities: an object, not an array
// RNTP
import { Capability } from 'react-native-track-player'
await TrackPlayer.updateOptions({
capabilities: [Capability.Play, Capability.Pause, Capability.SkipToNext]
})
// audio-browser — most are ON by default; specify only what differs
updateOptions({ capabilities: { skipToPrevious: false } })Pass capabilities to either setupPlayer (initial) or updateOptions (later) — both accept it. See Configuration → Capabilities for the defaults. Capability.Like / RatingType map to the favorite capability.
Enums become string literals
audio-browser has no enum objects — use the string values directly:
| RNTP | audio-browser |
|---|---|
State.Playing, State.Paused, … | 'playing', 'paused', … (same strings) |
RepeatMode.Off / Track / Queue | 'off' / 'track' / 'queue' |
Capability.Play (in an array) | { play: true } (in the capabilities object) |
State's string values are identical, so state === 'playing' checks port directly — you just drop the enum import.
Track: url → src
The playable URL field is renamed. In audio-browser, the playable source is src; a track's browse address (for the browse tree) is a separate field, path:
// RNTP
{ url: 'https://cdn.example.com/song.mp3', title, artist, artwork }
// audio-browser
{ src: 'https://cdn.example.com/song.mp3', title, artist, artwork }Other field changes:
isLiveStream→live.- Per-track
headers/userAgent→ return them frommedia.resolve(track)(orresolveSync), which receives each track. Headers that every track shares go on the browser'srequest/mediaconfig (Shaping requests). rating→ favorites (see above).titleis required.Trackhas no index signature, so it refuses fields of your own. Keep app data in a map keyed byid(or bysrc).- RNTP's
type,contentType,pitchAlgorithmanddatehave noTrackfield.
title / artist / album / artwork / duration / description / genre are unchanged.
Now-playing metadata
// RNTP
TrackPlayer.updateNowPlayingMetadata({ title, artist })
TrackPlayer.clearNowPlayingMetadata()
// audio-browser
import { updateNowPlaying } from 'react-native-audio-browser'
updateNowPlaying({ title, artist })
updateNowPlaying(null) // drop the override; the track's own metadata showsFor live streams, prefer the Now Playing formatter over imperative updates — it re-derives the lock-screen lines on every metadata / state change.
Player options
setupPlayer and updateOptions keep capabilities, forwardJumpInterval, backwardJumpInterval and progressUpdateEventInterval. Other RNTP options moved or have no equivalent:
| RNTP v4 | audio-browser |
|---|---|
minBuffer / maxBuffer / backBuffer / playBuffer | android.minBuffer / maxBuffer / backBuffer / playBuffer |
minBuffer on iOS | ios.buffer |
maxCacheSize | android.maxCacheSize |
androidAudioContentType | android.audioContentType |
iosCategory / iosCategoryMode / iosCategoryOptions | ios.category / ios.categoryMode / ios.categoryOptions |
autoUpdateMetadata | nowPlaying |
notificationCapabilities / compactCapabilities | none; place Android buttons with android.remoteButtonLayout |
icon / color | none |
ratingType | the favorite capability |
The units changed with the names. The four Android buffers and ios.buffer take milliseconds where RNTP took seconds, and maxCacheSize takes megabytes where RNTP took kilobytes, so a value copied across unchanged is off by a factor of 1000.
The android and ios keys are typed, so a leftover RNTP option is a type error. See Configuration for every option.
Setup, before and after
// RNTP — index.js + startup
TrackPlayer.registerPlaybackService(() => require('./service'))
await TrackPlayer.setupPlayer()
await TrackPlayer.updateOptions({
capabilities: [Capability.Play, Capability.Pause, Capability.SkipToNext],
progressUpdateEventInterval: 2
})// audio-browser — one declarative call, no service
import { setupPlayer } from 'react-native-audio-browser'
await setupPlayer({
progressUpdateEventInterval: 2
// capabilities are on by default; nothing to register
})See Configuration for the full options surface and what's setup-only vs runtime-updatable.
What you gain
audio-browser adds capabilities RNTP doesn't have — worth adopting once you've ported:
- A browse tree that powers native CarPlay and Android Auto menus (and voice search) — see the Automotive overview.
- A now-playing formatter for live-stream metadata and transient status lines.
- Content gating, a sleep timer, an equalizer, and favorites.
Quick reference
| Area | RNTP v4 | audio-browser |
|---|---|---|
| Getters | await TrackPlayer.getX() | getX() (sync) or useX() |
| Events | Event + addEventListener / useTrackPlayerEvents | per-event onX / useX |
| Unsubscribe | subscription.remove() | the function addListener returns |
| Remote handling | a registered playback service | default behavior + handleRemote* |
| Capabilities | Capability[] | capabilities object of booleans |
| Enums | State.*, RepeatMode.* | string literals ('playing', 'queue') |
| Playable URL | track.url | track.src |
| Live flag | track.isLiveStream | track.live |
| Now playing | updateNowPlayingMetadata / clearNowPlayingMetadata | updateNowPlaying(update | null); null reverts to the track's metadata |