React Native Track Player
Get V5 Access

Playback

All playback methods are synchronous — they return immediately, no await needed. Native state updates surface through events.

Basic controls

TrackPlayer.play():void
TrackPlayer.pause():void
TrackPlayer.stop():void
TrackPlayer.play();
TrackPlayer.pause();
TrackPlayer.stop();

stop() halts playback and resets position. pause() retains position.

Seeking

TrackPlayer.seekTo(position:number):void
TrackPlayer.seekBy(offset:number):void
TrackPlayer.seekTo(30);       // jump to 30 seconds
TrackPlayer.seekBy(10);       // forward 10s
TrackPlayer.seekBy(-10);      // back 10s

Skipping

TrackPlayer.skipToNext():void
TrackPlayer.skipToPrevious():void
TrackPlayer.skipToIndex(index:number):void
TrackPlayer.skipToNext();
TrackPlayer.skipToPrevious(); // restarts the current item if past ~3s
TrackPlayer.skipToIndex(2);   // zero-based

Speed and volume

TrackPlayer.setPlaybackSpeed(speed:number):void
TrackPlayer.setVolume(volume:number):void
TrackPlayer.setPlaybackSpeed(1.5); // 1.0 = normal
TrackPlayer.setVolume(0.8);        // 0.0 – 1.0

Repeat mode

TrackPlayer.setRepeatMode(mode:RepeatMode):void

Available values: RepeatMode.Off, RepeatMode.One, RepeatMode.All.

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

TrackPlayer.setRepeatMode(RepeatMode.One);  // repeat current track
TrackPlayer.setRepeatMode(RepeatMode.All);  // repeat queue
TrackPlayer.setRepeatMode(RepeatMode.Off);  // no repeat

Shuffle

TrackPlayer.setShuffleEnabled(enabled:boolean):void
TrackPlayer.setShuffleEnabled(true);
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.

TrackPlayer.sleepAfterTime(seconds:number,options?:{ fadeOutSeconds?: number }):void
// 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:

TrackPlayer.sleepAfterMediaItemAtIndex(index?:number):void
TrackPlayer.sleepAfterMediaItemAtIndex();   // after the current track ends
TrackPlayer.sleepAfterMediaItemAtIndex(5);  // after the track at index 5 ends

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

TrackPlayer.cancelSleepTimer():void
TrackPlayer.cancelSleepTimer();

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

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:

TrackPlayer.retry():void
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