React Native Track Player
Get V5 Access

Player Setup

Configure and initialize the player before any other API calls.

setupPlayer

await TrackPlayer.setupPlayer(config?: PlayerConfig);
PropTypeDefaultDescription
contentType 'music' | 'speech''music'Affects audio routing and ducking behavior on the device.
handleAudioBecomingNoisy booleantruePause automatically when headphones are unplugged.
cache CacheConfig—Configure local audio caching.
progressSync ProgressSyncConfig—Periodic background progress sync. Saves progress natively, posts to an HTTP endpoint, and emits PlaybackProgressUpdated events.
android AndroidPlayerConfig—Android-specific player options.

CacheConfig

PropTypeDefaultDescription
maxSize number524288000Maximum cache size in bytes. Default is 500 MB.

ProgressSyncConfig

PropTypeDefaultDescription
intervalSeconds number0Sync interval in seconds. 0 or omitted disables progress sync entirely.
http { url: string; headers?: Record<string, string> }—HTTP endpoint to POST progress to on each tick.

The HTTP POST body is JSON with the following shape:

{ "mediaId": "ep-123", "position": 142.5, "duration": 3600.0, "timestamp": 1710000000000 }

This is the same payload emitted by the PlaybackProgressUpdated event. A final tick is always sent on pause or stop.

AndroidPlayerConfig

PropTypeDefaultDescription
wakeMode 'none' | 'local' | 'network''none'Wake lock mode. Use 'network' for streaming audio.
skipSilenceEnabled booleanfalseSkip silent audio segments during playback.
notification AndroidNotificationConfig—Notification channel configuration.
cast string—Chromecast receiver app ID. Enables Cast support and powers OutputDeviceButton. Use DEFAULT_CAST_RECEIVER_APP_ID for Google's Default Media Receiver (no custom receiver registration required), or pass your own app ID for a custom receiver.

Example

await TrackPlayer.setupPlayer({
  contentType: 'music',
  handleAudioBecomingNoisy: true,
  cache: { maxSize: 200 * 1024 * 1024 }, // 200 MB
  progressSync: {
    intervalSeconds: 30,
    http: {
      url: 'https://api.example.com/progress',
      headers: { 'Authorization': 'Bearer xxx' },
    },
  },
  android: {
    wakeMode: 'network',
    notification: {
      channelId: 'com.myapp.audio',
      channelName: 'Audio Playback',
      smallIcon: 'ic_notification',
    },
  },
});

destroy

Tears down the player and releases all resources.

await TrackPlayer.destroy();

setCommands

Configure which commands appear on the lock screen and in the notification.

await TrackPlayer.setCommands(config: RemoteControlConfig);
PropTypeDefaultDescription
capabilities *PlayerCommand[]—Commands to enable on lock screen and notification.
handling 'native' | 'hybrid' | 'js''native'Controls who handles remote commands. 'native' lets the system act automatically (no background handler needed). 'js' routes all events to your background handler. 'hybrid' does both.
forwardInterval number15Seconds to skip forward. Applied natively when handling is 'native'; passed as event.interval when handling is 'js'.
backwardInterval number15Seconds to skip backward. Applied natively when handling is 'native'; passed as event.interval when handling is 'js'.

Available PlayerCommand values: Play, Pause, Stop, SkipToNext, SkipToPrevious, SeekTo, SkipForward, SkipBackward

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

await TrackPlayer.setCommands({
  capabilities: [
    PlayerCommand.Play,
    PlayerCommand.Pause,
    PlayerCommand.SkipToNext,
    PlayerCommand.SkipToPrevious,
    PlayerCommand.SeekTo,
  ],
  forwardInterval: 30,
  backwardInterval: 15,
});

updateProgressSyncHeaders

Update the HTTP headers used for progress sync POST requests at runtime — useful when auth tokens refresh.

TrackPlayer.updateProgressSyncHeaders({ 'Authorization': 'Bearer new-token' });

Caching

When cache is configured, audio is stored locally after the first download. Subsequent plays of the same URL are served from cache without a network request.

await TrackPlayer.setupPlayer({
  cache: { maxSize: 500 * 1024 * 1024 }, // 500 MB
});

Clear the cache manually:

await TrackPlayer.clearCache();
The useProgress hook exposes a cached field (in seconds) indicating how much of the current track is stored locally. Caching works regardless of whether the server provides a Content-Length header — the total size is determined when the download completes.

Preloading

Preloading downloads tracks to cache before they’re played, reducing gaps between tracks and enabling instant playback from browse screens.

Auto Preloading

Automatically preload the next tracks in the queue:

await TrackPlayer.setupPlayer({
  cache: {
    preloading: {
      window: 1,  // preload next 1 track (default: 0, disabled)
    },
  },
});

Auto preloading starts when the current track is fully cached, is a live stream, or is a local file. It also re-evaluates when the queue changes (items added, removed, replaced, or reordered). For on-demand streams, preloading waits until the current track finishes downloading to avoid competing for bandwidth.

Manual Preloading

Preload any track on demand — useful for browse screens, recommendations, or any UI where the user might play a track:

// Preload entire file
TrackPlayer.preload(mediaItem);

// Preload approximately 30 seconds
TrackPlayer.preload(mediaItem, { duration: 30 });

// Cancel an in-progress preload
TrackPlayer.cancelPreload(mediaItem);

Manual preloading works independently of the queue. The cache is keyed by URL, so any future play of the same URL will be a cache hit.

Preloading requires cache to be configured in setupPlayer.
ende