Skip to main content

Migrating from react-native-track-player v4.x

This guide maps the react-native-track-player (RNTP) v4.x API to react-native-queue-player and walks through the changes.

Key differences​

  • Instance access. Instead of static TrackPlayer.* methods, call the singleton accessor getTrackPlayer() (and getEqualizer(), getVisualizer(), getCastManager() for those features).
  • Remote controls are automatic. Lock-screen / Now Playing / headset / Bluetooth commands are handled natively once you call configure(). There is no capabilities list to declare and no remote-event service to write. registerPlaybackService in this library is for automotive and voice browse/search, not remote transport.
  • Native config via the Expo plugin. Native setup is driven by the bundled Expo config plugin (plus a couple of manual steps).

API mapping​

react-native-track-player v4react-native-queue-player
TrackPlayer.setupPlayer() + TrackPlayer.updateOptions({...})getTrackPlayer().configure({...}) — no capabilities / notification options to set
TrackPlayer.add(tracks)player.addToQueue(tracks)
TrackPlayer.setQueue(tracks)player.setQueue(tracks)
TrackPlayer.remove(indexes)player.removeFromQueue(indices)
TrackPlayer.move(from, to)player.moveInQueue(from, to)
TrackPlayer.skip(index)player.skipToIndex(index)
TrackPlayer.skipToNext() / skipToPrevious()player.skipToNext() / skipToPrevious()
TrackPlayer.play() / pause() / stop()player.play() / pause() / stop()
TrackPlayer.seekTo(seconds)player.seekTo(seconds)
TrackPlayer.setRate(rate)player.setPlaybackSpeed(rate)
TrackPlayer.setVolume(v)player.setVolume(v)
TrackPlayer.setRepeatMode(RepeatMode.Queue)player.setRepeatMode('queue') ('off' / 'queue' / 'track')
TrackPlayer.getQueue()player.getQueue()
TrackPlayer.getActiveTrackIndex()player.getCurrentTrackIndex()
TrackPlayer.getActiveTrack()useActiveTrack() (React) or player.getQueue()[player.getCurrentTrackIndex()]
TrackPlayer.getProgress()useProgress() (React)
TrackPlayer.getPlaybackState()player.getState()
useProgress() / usePlaybackState() / useActiveTrack()same names — see hooks
useTrackPlayerEvents([...], handler)per-event listeners (player.onStateChange, onTrackChange, onProgress, onError, onQueueEnd, …) returning disposers, or the hooks
registerPlaybackService(() => require('./service')) with Event.RemotePlay/RemotePause/… handlersnot needed — remote controls are automatic
Capability.* in updateOptionsnot needed — handled automatically
Track { url, title, artist, artwork, duration }TrackItem { url, title, artist, artworkUrl, duration } (note artwork → artworkUrl)

Step by step​

1. Swap dependencies​

npm uninstall react-native-track-player
npm install react-native-queue-player react-native-nitro-modules

Add the Expo config plugin — it sets the iOS background-audio mode for you — then npx expo prebuild. (Bare React Native: see Setup & manual configuration.)

2. Replace setup​

// Before
import TrackPlayer, { Capability } from 'react-native-track-player';
await TrackPlayer.setupPlayer();
await TrackPlayer.updateOptions({
  capabilities: [Capability.Play, Capability.Pause, Capability.SkipToNext],
});

// After
import { getTrackPlayer } from 'react-native-queue-player';
await getTrackPlayer().configure({ audioContentType: 'music' });

The capabilities/notification options have no equivalent — drop them.

3. Replace queue and transport calls​

Apply the mapping table. Most calls are renames (add → addToQueue, skip → skipToIndex, setRate → setPlaybackSpeed); the signatures are otherwise the same.

4. Replace events with hooks or listeners​

// Before
useTrackPlayerEvents([Event.PlaybackState], (e) => setState(e.state));

// After (hook)
const { state } = usePlaybackState();

// After (imperative)
const off = getTrackPlayer().onStateChange((state) => setState(state));
// off() to unsubscribe

5. Remove the remote-event playback service​

If your RNTP service only handled remote events (Event.RemotePlay, RemotePause, RemoteNext, …), delete it — those are automatic now. If you also do automotive/voice, keep registerPlaybackService but implement the browse/search handlers instead (see Android Auto, CarPlay, Voice).

Gotchas​

  • artwork → artworkUrl on the track object.
  • setRate → setPlaybackSpeed.
  • Enums become string unions: RepeatMode.Off/Track/Queue → 'off' | 'track' | 'queue'; the State enum → PlayerState strings ('playing', 'paused', 'buffering', …).
  • getProgress() / getActiveTrack() are best consumed via the useProgress / useActiveTrack hooks.
  • Shuffle is one-shot — shuffleQueue() reorders the queue and returns the result; there is no persistent "shuffle on/off" toggle.
  • Crossfade duration is bounded to 1000–12000 ms in 500 ms steps (see PlaybackMode).
  • TrackItem.id is optional — where RNTP wants a unique track id, here it's optional metadata that's simply echoed back to you (in remote-command callbacks and voice-query results). You don't need to supply one, and duplicate or missing ids are fine.