React Native Track Player
Get V5 Access

Playback

Basic controls

await TrackPlayer.play();
await TrackPlayer.pause();
await TrackPlayer.stop();

stop() halts playback and releases the media resource, while pause() retains position.

Seeking

// Seek to an absolute position in seconds
await TrackPlayer.seekTo(30);

// Seek relative to current position
await TrackPlayer.seekBy(10);   // forward 10s
await TrackPlayer.seekBy(-10);  // back 10s

Skipping

await TrackPlayer.skipToNext();
await TrackPlayer.skipToPrevious();
await TrackPlayer.skipToIndex(2); // zero-based index

Speed and volume

await TrackPlayer.setPlaybackSpeed(1.5); // 1.0 = normal
await TrackPlayer.setVolume(0.8);        // 0.0 – 1.0

Repeat mode

import { RepeatMode } from '@rntp/player';

await TrackPlayer.setRepeatMode(RepeatMode.Track);  // repeat current track
await TrackPlayer.setRepeatMode(RepeatMode.Queue);  // repeat queue
await TrackPlayer.setRepeatMode(RepeatMode.Off);    // no repeat

Shuffle

await TrackPlayer.setShuffleEnabled(true);
await TrackPlayer.setShuffleEnabled(false);

Sleep timer

Set a countdown timer that pauses playback after a duration. The timer uses wall clock time — it keeps counting even if playback is paused.

// Pause after 30 minutes
TrackPlayer.sleepAfterTime(30 * 60);

// Pause after 30 minutes with a 30-second volume fade-out
TrackPlayer.sleepAfterTime(30 * 60, { fadeOutSeconds: 30 });

You can also pause after a specific track finishes:

// Pause after the current track ends
TrackPlayer.sleepAfterMediaItemAtIndex();

// Pause after the track at index 5 ends
TrackPlayer.sleepAfterMediaItemAtIndex(5);

Only one sleep timer can be active at a time — setting a new one cancels the previous.

Cancel an active timer with:

TrackPlayer.cancelSleepTimer();

If a volume fade is in progress, cancelling restores the original volume immediately.

Note: fadeOutSeconds is only available with sleepAfterTime. The media-item-based timer has no fade-out since the remaining time is unknown. If fadeOutSeconds exceeds the timer duration, it is clamped to fit.

Error recovery

If a track fails to load, the player enters an error state. Call retry() to re-attempt:

await TrackPlayer.retry();

Background playback

Background playback is enabled automatically when you configure the UIBackgroundModes capability in iOS and set up a background event handler.

The player continues running when:

  • The app is backgrounded
  • The screen is turned off
  • The user switches apps

No additional configuration is needed beyond the Installation setup.

Remote controls

Remote controls (lock screen, notification, headphone buttons, Bluetooth) are handled via the background event handler registered with registerBackgroundEventHandler.

See Quick Start for the full example.

Customize which controls are visible with setCommands. See Player Setup.

ende