Events

Two APIs, one rule: a listener lives as long as the place you register it.

registerPlaybackSession

The home for your playback logic. Register it from index.js; the function runs at startup, and listeners you add inside it stay alive as long as JS is running. That includes while the app is backgrounded, and after the user swipes it away while music keeps playing. On Android, a listener that returns a promise is awaited in the background, so async work like saving progress gets a guaranteed window to finish. It works the same on iOS, Android, and web.

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

// index.js — before AppRegistry.registerComponent
TrackPlayer.registerPlaybackSession(() => {
  TrackPlayer.addEventListener(Event.PlaybackProgressUpdated, ({ mediaId, position }) => {
    saveProgress(mediaId, position);
  });
  TrackPlayer.addEventListener(Event.PlaybackError, ({ code }) => {
    if (code === 'network') TrackPlayer.retry();
  });
});

addEventListener

Subscribe to a single event. In components, use it for display state; the listener is removed when the component unmounts.

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 listen for the Remote* events. Put these listeners in your playback session; remote presses usually happen while the app is in the background.

RemotePlay / RemotePause / RemoteNext / RemotePrevious / RemoteStop

All four fire with no payload.

RemoteSeek

RemoteSkipForward

RemoteSkipBackward

Background event handler (advanced)

Use registerPlaybackSession instead. Session listeners that return a promise are awaited in the background with a guaranteed execution window (the library holds a wakelock until they settle), so this handler offers nothing extra. It is kept for backwards compatibility.

If you register it, it takes over: while the app is backgrounded on Android, events go to this handler only, and your session listeners see them again when the app returns to the foreground. It is Android-only (no-op on iOS) and 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;
  }
});