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').

taskRemovedBehavior (continue | stop, default continue) controls whether playback survives when the app is swiped from recents.

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, notification, and native media session (including Android Auto when the host connects to your playback service).

Remote control and media-session command configuration (lock screen, notification, Android Auto, and similar surfaces). This configures **native** behavior. With `handling: 'native'` (default), actions run without JavaScript; on Android, config is persisted for the playback service. `handling: 'js'` / `'hybrid'` emit events to `addEventListener` / `registerBackgroundEventHandler` on the phone only — Android Auto and CarPlay do not run the React Native JS runtime for transport controls; use native handling or native extensions for in-car custom behavior.

In-car behavior: Remote controls in-car.

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.