Playback

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

Basic controls

TrackPlayer.play():void

Start playback.

TrackPlayer.pause():void

Pause playback.

TrackPlayer.stop():void

Stop playback and reset position. Queue is preserved.

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

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

Seeking

TrackPlayer.seekTo(position:number):void

Seek to a position in seconds.

TrackPlayer.seekBy(offset:number):void

Seek by a relative offset in seconds (negative = rewind).

TrackPlayer.seekTo(30);       // jump to 30 seconds
TrackPlayer.seekBy(10);       // forward 10s
TrackPlayer.seekBy(-10);      // back 10s

Skipping

TrackPlayer.skipToNext():void

Skip to the next item in the queue.

TrackPlayer.skipToPrevious():void

Skip to the previous item in the queue. If playback is past ~3 seconds, restarts the current item instead.

TrackPlayer.skipToIndex(index:number):void

Skip to a specific index in the queue.

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

Speed and volume

TrackPlayer.setPlaybackSpeed(speed:number):void

Set the playback speed (1.0 = normal).

TrackPlayer.setVolume(volume:number):void

Set the player volume (0.0 to 1.0).

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

Repeat mode

TrackPlayer.setRepeatMode(mode:RepeatMode):void

Set the repeat mode.

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

Enable or disable shuffle.

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

Sets a countdown sleep timer. Playback pauses after `seconds` of wall clock time. The timer keeps counting even if playback is paused. Cancels any existing sleep timer (last one wins).

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

Pauses playback after the media item at `index` finishes playing. - Cancels any existing sleep timer (last one wins). - Index is absolute — queue mutations after setting may shift which item it points to. - No fade-out support (no known time horizon).

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

Cancels the active sleep timer. If a volume fade is in progress, restores the original volume immediately.

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

Re-prepares the current media item after a playback error. No-op if the player is not in an error state. Does not auto-play — call play after if needed.

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

By default (handling: 'native' in setCommands), the native player handles lock screen, notification, headphone, and Bluetooth actions with no JavaScript.

Register registerBackgroundEventHandler (Android, UI backgrounded) or use addEventListener (iOS, and Android foreground) only when you set handling to 'js' or 'hybrid' and need custom behavior on the phone.

Android Auto and CarPlay always use the native session; JS remote handlers do not run there. See Remote controls in-car.

See Quick Start for an optional background handler example.