Events

addEventListener

import TrackPlayer, { Event } from '@rntp/player';
import { useEffect } from 'react';

useEffect(() => {
  const sub = TrackPlayer.addEventListener(Event.PlaybackError, (event) => {
    console.error('Playback error', event.code, event.message);
  });
  return () => sub.remove();
}, []);

Event catalogue

Event payloads

PlaybackStateChanged

Fires when the playback state transitions.

TrackPlayer.addEventListener(Event.PlaybackStateChanged, ({ state }) => {
  console.log('New state:', state);
});

IsPlayingChanged

Fires when playing status toggles.

TrackPlayer.addEventListener(Event.IsPlayingChanged, ({ playing }) => {
  console.log('Playing:', playing);
});

MediaItemTransition

Fires when the active queue item changes.

TrackPlayer.addEventListener(Event.MediaItemTransition, ({ item, index }) => {
  console.log('Now playing:', item?.title, 'at index', index);
});

MediaMetadataChanged

Fires when the effective metadata of the currently active media item changes — the view that backs getActiveMediaItem() and the system Now Playing info (lock screen, Bluetooth, CarPlay / Android Auto). This is the event most apps want: it accounts for track transitions, explicit updateMetadata calls, and the auto-update path that merges incoming stream metadata into the queued item.

Effective metadata for the active item (getActiveMediaItem, Now Playing). Use MetadataReceivedEvent for raw per-frame stream metadata instead. v5.1.0+

TrackPlayer.addEventListener(Event.MediaMetadataChanged, ({ title, artist }) => {
  console.log('Now playing:', title, artist);
});

MetadataReceived

Fires for every metadata frame received off the wire (ICY blocks on Shoutcast/Icecast streams, ID3 frames in MP3/AAC streams, Vorbis comments, …). The payload reflects stream-derived fields only and is not merged with the queued media item — for the merged effective view, subscribe to MediaMetadataChanged.

Useful for analytics / scrobbling and for sanitization pipelines that want to filter stream metadata before writing it back (combine with autoUpdateMetadataFromStream: false and call updateMetadata yourself).

Fired for every metadata frame the audio stream pushes — ICY blocks (Shoutcast/Icecast radio), ID3 tags, Vorbis comments, QuickTime metadata. The payload reflects *stream-derived* fields only; user-supplied fields on the queued MediaItem (e.g. a static `genre` or `albumTitle`) are not merged in here. For the effective merged view that `getActiveMediaItem` returns (and that the lock screen / system Now Playing info reflects), subscribe to MediaMetadataChangedEvent instead. Typical consumers: analytics / scrobbling, sanitization pipelines that filter the raw stream before calling updateMetadata themselves (use with `PlayerConfig.autoUpdateMetadataFromStream: false`).

TrackPlayer.addEventListener(Event.MetadataReceived, ({ title, artist }) => {
  console.log('Stream pushed:', title, artist);
});

PlaybackError

Fires when a playback error occurs.

TrackPlayer.addEventListener(Event.PlaybackError, ({ code, message }) => {
  console.error(`[${code}] ${message}`);
  if (code === 'network') TrackPlayer.retry();
});

PlaybackProgressUpdated

Fires periodically during playback when progressSync is configured. Contains the same payload sent to the HTTP endpoint and saved natively.

TrackPlayer.addEventListener(Event.PlaybackProgressUpdated, ({ mediaId, position, duration, timestamp }) => {
  console.log(`${mediaId}: ${position}/${duration}s at ${timestamp}`);
});

SleepTimerTriggered

Fires when a sleep timer pauses playback.

TrackPlayer.addEventListener(Event.SleepTimerTriggered, ({ type }) => {
  console.log(`Sleep timer fired (${type})`);
});

QueueChanged

Fires when the queue is modified. No payload.

TrackPlayer.addEventListener(Event.QueueChanged, () => {
  const queue = TrackPlayer.getQueue();
});

Remote control events

These fire in response to hardware buttons, lock screen controls, and notification actions on the phone (and similar surfaces that route through the same native session).

With default handling: 'native', the native player handles the press immediately — no JavaScript runs. Remote events are not emitted in that mode.

To intercept presses yourself, set handling to 'js' or 'hybrid' in setCommands, then use addEventListener on iOS (and on Android while the UI is foreground). On Android with the UI backgrounded, handle them in registerBackgroundEventHandler instead.

RemotePlay / RemotePause / RemoteNext / RemotePrevious / RemoteStop

All four fire with no payload.

RemoteSeek

RemoteSkipForward

RemoteSkipBackward

Background event handler

By default (handling: 'native'), play, pause, skip, and seek work without JavaScript — you do not need a background handler for basic playback.

Register one when you want to run JS yourself — for example to update metadata, implement custom skip logic on the phone, handle progressSync ticks, or use handling: 'js' / 'hybrid' for commands that emit to JS. On Android, this runs while the app UI is backgrounded (not when the whole process is force-stopped); on iOS the function is a no-op — use addEventListener for all events (including while audio plays in the background with UIBackgroundModes audio).

This handler does not cover Android Auto or CarPlay — see the callout under Remote control events above.

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

// index.js — before AppRegistry.registerComponent
TrackPlayer.registerBackgroundEventHandler(() => async (event: BackgroundEvent) => {
  switch (event.type) {
    case Event.RemotePause:
      TrackPlayer.pause();
      break;
    case Event.PlaybackProgressUpdated:
      await TrackPlayer.updateMetadata(0, { title: `At ${event.position}s` });
      break;
  }
});