Skip to content

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 v4audio-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:

  • useProgress changed meaning. RNTP's useProgress(interval) is polling; its drop-in is usePolledProgress(intervalMs). audio-browser also has a useProgress(), but it's event-based and takes no interval. It stays still until progressUpdateEventInterval is set. TypeScript rejects useProgress(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()):

ts
// 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
PlaybackActiveTrackChangedonActiveTrackChanged / useActiveTrack()
PlaybackStateonPlaybackChanged / usePlayback()
PlaybackProgressUpdatedonProgressUpdated / useProgress()
PlaybackQueueEndedonQueueEnded
PlaybackError / PlayerErroronPlaybackError / usePlaybackError()
PlaybackPlayWhenReadyChangedonPlayWhenReadyChanged / usePlayWhenReady()
Remote* (Play, Pause, Next, …)handleRemote* to override, onRemote* to observe — see Remote Controls
Metadata*ReceivedonTimedMetadata / 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*:

ts
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 default

Audio 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 ​

ts
// 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:

RNTPaudio-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:

ts
// 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 from media.resolve(track) (or resolveSync), which receives each track. Headers that every track shares go on the browser's request / media config (Shaping requests).
  • rating → favorites (see above).
  • title is required.
  • Track has no index signature, so it refuses fields of your own. Keep app data in a map keyed by id (or by src).
  • RNTP's type, contentType, pitchAlgorithm and date have no Track field.

title / artist / album / artwork / duration / description / genre are unchanged.

Now-playing metadata ​

ts
// 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 shows

For 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 v4audio-browser
minBuffer / maxBuffer / backBuffer / playBufferandroid.minBuffer / maxBuffer / backBuffer / playBuffer
minBuffer on iOSios.buffer
maxCacheSizeandroid.maxCacheSize
androidAudioContentTypeandroid.audioContentType
iosCategory / iosCategoryMode / iosCategoryOptionsios.category / ios.categoryMode / ios.categoryOptions
autoUpdateMetadatanowPlaying
notificationCapabilities / compactCapabilitiesnone; place Android buttons with android.remoteButtonLayout
icon / colornone
ratingTypethe 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 ​

ts
// RNTP — index.js + startup
TrackPlayer.registerPlaybackService(() => require('./service'))
await TrackPlayer.setupPlayer()
await TrackPlayer.updateOptions({
  capabilities: [Capability.Play, Capability.Pause, Capability.SkipToNext],
  progressUpdateEventInterval: 2
})
ts
// 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:

Quick reference ​

AreaRNTP v4audio-browser
Gettersawait TrackPlayer.getX()getX() (sync) or useX()
EventsEvent + addEventListener / useTrackPlayerEventsper-event onX / useX
Unsubscribesubscription.remove()the function addListener returns
Remote handlinga registered playback servicedefault behavior + handleRemote*
CapabilitiesCapability[]capabilities object of booleans
EnumsState.*, RepeatMode.*string literals ('playing', 'queue')
Playable URLtrack.urltrack.src
Live flagtrack.isLiveStreamtrack.live
Now playingupdateNowPlayingMetadata / clearNowPlayingMetadataupdateNowPlaying(update | null); null reverts to the track's metadata