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 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, { Event, type BackgroundEvent } from '@rntp/player';

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

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

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