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 playback state, updating when it changes.

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.

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 playback progress, polling at the given interval.

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

Active media item; refreshes on Event.MediaItemTransition and Event.MediaMetadataChanged (after native merges stream metadata).

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