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 up to five seconds to finish. Return the promise, as below, rather than discarding it with void: work that isn’t returned can be frozen until the app is next opened. Listeners are typed as PlayerEventListener, so returning a promise is fine under no-misused-promises. 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. reason says why: auto when the previous item finished and playback moved on, seek for a skip or jump, repeat each time a repeat-one item loops, and playlistChanged when the queue was replaced or the current item removed.

TrackPlayer.addEventListener(Event.MediaItemTransition, ({ item, index, reason }) => {
  if (reason === 'auto') console.log('Moved on to', 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 handlers

Presses from the lock screen, the notification, Bluetooth and headset keys, Android Auto and CarPlay all arrive as remote commands. By default the native player handles each one and no JavaScript runs. To run your own logic for a command, register a handler for it:

// inside registerPlaybackSession, before the first await
TrackPlayer.registerRemoteHandlers({
  next: () => TrackPlayer.skipToNext(),
  previous: (command) => command.performDefault(),
  play: async (command) => {
    if (await canPlay()) command.performDefault();
  },
});

A handler owns its command. The native action only runs if the handler calls performDefault(), so a handler that returns without calling it consumes the press. Commands without a handler keep their native behaviour. performDefault() runs the original native operation once, with the arguments captured at the press, within five seconds of it.

The keys are play, pause, stop, next, previous, seek (with command.position), skipForward and skipBackward (with command.interval). Buttons still come from setCommands: a handler doesn’t make a button appear, it decides what the button does.

Register handlers synchronously inside registerPlaybackSession so they also exist when the app starts in the background, for example from Android Auto with android.autoStartJs. On Android they only take over once setupPlayer() has run in the same runtime, so a background start needs setupPlayer() in the playback session as well. If you register handlers in a component instead, call remove() when it unmounts.

Calling registerRemoteHandlers again replaces the whole set, and the returned remove() clears it. Registrations are never saved: each JS runtime registers its own, and a press that arrives before the player has finished connecting runs natively.

A few limits:

• At most 32 presses can be waiting on or held by handlers at once, each for five seconds. Presses beyond that run natively without calling the handler.
• A handler that throws or rejects consumes the press.
• For asynchronous work, make the handler async and await it before calling performDefault(), as in the play example above. On Android, a backgrounded app’s timers only run while the handler’s promise is pending, so work scheduled to run after the handler returns can miss the five-second window.
• Picking an item from the queue, calls your app makes to TrackPlayer, and controls on a Cast receiver are not intercepted. Browse selection in the car loads its queue natively; in Android Auto the Play that follows goes to your play handler, while CarPlay plays the selection directly.
• On Android, handlers run inside the background task even while the app is in the foreground.

Moving from handling: 'js'

handling: 'js' and 'hybrid' with the Remote* events below still work in 5.x, but they are deprecated and go away in 6.0. A listener becomes a handler:

// before
TrackPlayer.setCommands({ capabilities, handling: 'js' });
TrackPlayer.addEventListener(Event.RemoteNext, () => TrackPlayer.skipToNext());

// after
TrackPlayer.setCommands({ capabilities });
TrackPlayer.registerRemoteHandlers({ next: () => TrackPlayer.skipToNext() });

A few differences from the old setup. Handlers survive destroy() and setupPlayer(), while Android’s setupPlayer still resets legacy handling to native. System Previous/Next on Android keep running natively under legacy handling, as in 5.10, whereas a next or previous handler receives them. And on Android a play handler also owns restarting from the end of the queue: call command.performDefault() rather than TrackPlayer.play() if Play should start over after the last track.

Remote control events (deprecated)

These fire only when setCommands sets handling to 'js' or 'hybrid' for that command and no handler is registered for it. Use handlers in new code.

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 presses taken by remote handlers never reach it.

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