Quick Start

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

import TrackPlayer from '@rntp/player';

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

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

If registered, it must be called before setupPlayer.

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

TrackPlayer.registerBackgroundEventHandler(() => async (event: BackgroundEvent) => {
  switch (event.type) {
    case EventType.RemotePlay:     await TrackPlayer.play(); break;
    case EventType.RemotePause:    await TrackPlayer.pause(); break;
    case EventType.RemoteNext:     await TrackPlayer.skipToNext(); break;
    case EventType.RemotePrevious: await TrackPlayer.skipToPrevious(); break;
  }
});

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

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

await TrackPlayer.setCommands({
  capabilities: [
    PlayerCommand.Play,
    PlayerCommand.Pause,
    PlayerCommand.SkipToNext,
    PlayerCommand.SkipToPrevious,
  ],
});

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

await 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>
    </>
  );
}