React Native Track Player
Get V5 Access

Hooks

RNTP ships four React hooks. All hooks subscribe to player events and re-render automatically.

usePlaybackState

usePlaybackState():PlaybackState

Returns the current PlaybackState. See State & Progress for the full enum.

import { usePlaybackState, PlaybackState } from '@rntp/player';

function PlayerStatus() {
  const state = usePlaybackState();

  if (state === PlaybackState.Buffering) return <ActivityIndicator />;
  if (state === PlaybackState.Error) return <Text>Playback error</Text>;

  return <Text>{state}</Text>;
}

useIsPlaying

useIsPlaying():boolean

Returns whether the player is currently producing audio output. Updates via IsPlayingChanged events.

import { useIsPlaying } from '@rntp/player';
import TrackPlayer from '@rntp/player';

function PlayPauseButton() {
  const playing = useIsPlaying();

  return (
    <Pressable onPress={() => playing ? TrackPlayer.pause() : TrackPlayer.play()}>
      <Icon name={playing ? 'pause' : 'play'} />
    </Pressable>
  );
}

useProgress

useProgress(updateInterval?:number):Progress

Returns the current Progress shape, polling at the given interval (in seconds, default 1).

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

function ProgressBar() {
  const { position, duration } = useProgress(); // default 1s interval

  return (
    <Slider
      value={position}
      maximumValue={duration}
      onSlidingComplete={(value) => TrackPlayer.seekTo(value)}
    />
  );
}

Custom update interval

The argument is in seconds, not milliseconds.

const { position, duration } = useProgress(0.5); // update every 500ms

Returned shape

FieldTypeDefaultDescription
position * number—Current playback position in seconds.
duration * number—Total duration of the media item in seconds.
buffered * number—Buffered position in seconds.
cached * number—Cached-on-disk position in seconds. 0 when caching is not enabled.

useActiveMediaItem

useActiveMediaItem():MediaItem | null

Returns the currently active MediaItem or null. Subscribes internally to Event.MediaItemTransition and Event.MediaMetadataChanged, so the returned item always matches the lock screen / Now Playing view — including live ICY title updates when autoUpdateMetadataFromStream is enabled.

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

function NowPlaying() {
  const track = useActiveMediaItem();

  if (!track) return null;

  return (
    <View>
      <Image source={{ uri: typeof track.artworkUrl === 'string' ? track.artworkUrl : undefined }} />
      <Text>{track.title}</Text>
      <Text>{track.artist}</Text>
    </View>
  );
}
ende