Quick Start

Call setupPlayer once when your app starts — in your root component or entry point.

import TrackPlayer from '@rntp/player';

TrackPlayer.setupPlayer({
  contentType: 'music',
});

By default, the system handles remote control events natively — you do not need this for basic playback. Register a handler when you want to intercept events yourself, such as to update metadata or implement custom logic.

On iOS, use addEventListener in your app instead (registerBackgroundEventHandler is a no-op). On Android, register in index.js before setupPlayer() for events while the UI is backgrounded. See Events.

import TrackPlayer, { Event, type BackgroundEvent } from '@rntp/player';

TrackPlayer.registerBackgroundEventHandler(() => async (event: BackgroundEvent) => {
  if (event.type === Event.RemotePause) TrackPlayer.pause();
});

Set which commands appear on the lock screen, notification, and native media session (including Android Auto). This configures native handling by default — not your JS bundle. In-car surfaces do not run registerBackgroundEventHandler; see Remote controls in-car.

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

TrackPlayer.setCommands({
  capabilities: [
    PlayerCommand.PlayPause,
    PlayerCommand.Next,
    PlayerCommand.Previous,
  ],
});

TrackPlayer.setMediaItems([
  {
    mediaId: 'track-1',
    url: 'https://example.com/audio.mp3',
    title: 'My Track',
    artist: 'Artist Name',
    artworkUrl: 'https://example.com/artwork.jpg',
  },
]);

TrackPlayer.play();

import { useIsPlaying, useProgress } from '@rntp/player';

function PlayerControls() {
  const playing = useIsPlaying();
  const { position, duration } = useProgress();

  return (
    <>
      <Slider value={position} maximumValue={duration} />
      <Button onPress={() => playing ? TrackPlayer.pause() : TrackPlayer.play()}>
        {playing ? 'Pause' : 'Play'}
      </Button>
    </>
  );
}