Player Setup

Configure and initialize the player before any other API calls.

setupPlayer

CacheConfig

ProgressSyncConfig

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

notification is an object with channelId, channelName, and smallIcon (Android resource name, e.g. 'ic_stat_music_note').

Example

TrackPlayer.setupPlayer({
  contentType: 'music',
  handleAudioBecomingNoisy: true,
  cache: { maxSizeBytes: 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. After calling this, you must call setupPlayer() again to use the player.

TrackPlayer.destroy();

setCommands

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

handling controls who handles remote commands. 'native' (default) lets the system act automatically with no background handler needed. 'js' routes all events to your background handler. 'hybrid' does both, with per-command overrides via perCommandHandling.

Available PlayerCommand values: PlayerCommand.Seek, PlayerCommand.PlayPause, PlayerCommand.Next, PlayerCommand.Previous, PlayerCommand.Stop, PlayerCommand.SkipForward, PlayerCommand.SkipBackward.

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

TrackPlayer.setCommands({
  capabilities: [
    PlayerCommand.PlayPause,
    PlayerCommand.Next,
    PlayerCommand.Previous,
    PlayerCommand.Seek,
  ],
  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.

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

TrackPlayer.clearCache();

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:

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

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.