Expo Track Player

The expo-track-player library provides a comprehensive API for playing and managing audio playback, along with a set of React hooks for easily syncing player state with your UI.

TrackPlayer API

The main interface for controlling playback is the TrackPlayer object.

Setup

| Method | Description | | ----------------- | ------------------------------------------------------------ | | setup(options?) | Initializes the player. Must be called before any other API. | | stop() | Stops playback, clears the queue, and resets the player. |

Playback

| Method | Description | | ----------------- | ----------------------------------------- | | play() | Starts or resumes playback. | | pause() | Pauses playback. | | next() | Skips to the next track. | | previous() | Skips to the previous track. | | seekTo(seconds) | Seeks to a position in the current track. | | skipTo(index) | Skips to a queue item by index. |

Queue

| Method | Description | | ------------------------------- | ------------------------------------------------ | | addTracks(tracks) | Appends tracks to the queue. | | insertTracks(tracks, index) | Inserts tracks at the specified index. | | removeTrack(index) | Removes a track from the queue. | | moveTrack(fromIndex, toIndex) | Move a track from one index to another in queue. | | setQueue(tracks) | Replaces the current queue. | | clearQueue() | Removes every track from the queue. | | reshuffle(order?) | Generates a new playback order. |

Player Settings

| Method | Description | | --------------------------- | --------------------------------------- | | setVolume(volume) | Sets the playback volume (0.0 – 1.0). | | setPlaybackSpeed(rate) | Sets the playback speed (0.1 – 2.0). | | setRepeatMode(mode) | Sets the repeat mode. | | setShuffleMode(enabled) | Enables or disables shuffle. | | setRemoteControls(config) | Configures native media controls. |

Utilities

| Method | Description | | -------------------------- | ---------------------------------------------- | | updateMetadata(metadata) | Updates lock screen and notification metadata. | | setSleepTimer(seconds) | Starts a sleep timer. | | clearSleepTimer() | Cancels the active sleep timer. | | setBrowseTree(tree) | Sets the Android Auto / CarPlay browse tree. |

Events

Subscribe using:

TrackPlayer.addEventListener(event, listener);

| Event | Description | Payload | | --------------------- | ----------------------------------------------------------------------------------- | ------------------------- | | PlayerStateChanged | Emitted whenever the playback state changes. | PlayerStateChangedEvent | | TrackChanged | Emitted whenever the current track changes, regardless of the cause. | TrackChangedEvent | | PlaybackEnded | Emitted when playback naturally reaches the end of the queue. | PlaybackEndedEvent | | PlaybackError | Emitted when playback fails due to an error. | PlaybackErrorEvent | | QueueChanged | Emitted whenever the logical queue or playback order changes. | QueueChangedEvent | | MetadataChanged | Emitted after the current track's runtime metadata is updated. | MetadataChangedEvent | | SleepTimerTriggered | Emitted after the sleep timer pauses playback. | void | | RemotePlay | Emitted when playback is started from a native media controller. | void | | RemotePause | Emitted when playback is paused from a native media controller. | void | | RemoteNext | Emitted when the next-track command is received from a native media controller. | void | | RemotePrevious | Emitted when the previous-track command is received from a native media controller. | void | | RemoteSeek | Emitted when a native media controller requests seeking. | RemoteSeekEvent | | RemoteJumpForward | Emitted when a native media controller requests a forward jump. | RemoteJumpForwardEvent | | RemoteJumpBackward | Emitted when a native media controller requests a backward jump. | RemoteJumpBackwardEvent | | RemoteStop | Emitted when playback is stopped from a native media controller. | void |

React Hooks

| Hook | Description | Returns | | -------------------- | ---------------------------------------------------------------- | ---------------------------------- | | usePlayerState() | Returns the current player state. | PlayerState | | useProgress() | Returns the current playback progress and buffering information. | { position, buffered, duration } | | useNowPlaying() | Returns the currently active track and its queue index. | { index, track } | | useActualQueue() | Returns the logical queue in insertion order. | Track[] | | usePlaybackOrder() | Returns the current playback order used for navigation. | number[] | | useVolume() | Returns the current playback volume. | number | | usePlaybackSpeed() | Returns the current playback speed. | number | | useShuffleMode() | Returns whether shuffle mode is enabled. | boolean | | useRepeatMode() | Returns the current repeat mode. | RepeatMode | | useSleepTimer() | Returns the sleep timer remaining time, or -1 if inactive. | number |

Components

| Component | Platform | Description | | ------------------------ | -------------- | ----------------------------------------------------------------------------------------- | | <OutputDeviceButton /> | Cross-platform | Native output routing button (AVRoutePickerView on iOS, MediaRouteButton on Android). | | <AirPlayButton /> | iOS | AirPlay route picker button (AVRoutePickerView). | | <ChromecastButton /> | Android | Google Cast route picker button (MediaRouteButton). |

Types

Track

interface Track {
  id: string;
  uri: string | number;

  headers?: Record<string, string>;

  title?: string;
  artist?: string;
  album?: string;

  artwork?: string | number;
  duration?: number;

  isLive?: boolean;
  mimeType?: string;

  extras?: Record<string, unknown>;
}

SetupOptions

interface SetupOptions {
  contentType?: "music" | "speech";
  pauseOnDisconnect?: boolean;
  audioMixing?: "exclusive" | "mix";
  restoreSession?: boolean;
  androidCastId?: string;
}

RemoteControlConfig

interface RemoteControlConfig {
  capabilities: RemoteCommand[];
  forwardJumpInterval?: number;
  backwardJumpInterval?: number;
  isLiveStream?: boolean;
}

AudioMetadata

interface AudioMetadata {
  title?: string;
  artist?: string;
  album?: string;
  artwork?: string | number;
}

BrowseNode

interface BrowseNode {
  id: string;
  title: string;
  subtitle?: string;
  artwork?: string | number;
  track?: Track;
  extras?: Record<string, unknown>;
  children?: BrowseNode[];
}

Progress

interface Progress {
  position: number;
  buffered: number;
  duration: number;
}

NowPlaying

interface NowPlaying {
  index: number;
  track: Track | null;
}

Enums

PlayerState

export const PlayerState = {
  Idle: "idle",
  Loading: "loading",
  Buffering: "buffering",
  Ready: "ready",
  Playing: "playing",
  Paused: "paused",
  Stopped: "stopped",
  Error: "error",
} as const;

export type PlayerState = (typeof PlayerState)[keyof typeof PlayerState];

RepeatMode

export const RepeatMode = {
  Off: "off",
  Track: "track",
  Queue: "queue",
} as const;

export type RepeatMode = (typeof RepeatMode)[keyof typeof RepeatMode];

Event

export const Event = {
  PlayerStateChanged: "player-state-changed",
  TrackChanged: "track-changed",
  PlaybackEnded: "playback-ended",
  PlaybackError: "playback-error",
  QueueChanged: "queue-changed",
  MetadataChanged: "metadata-changed",
  SleepTimerTriggered: "sleep-timer-triggered",

  RemotePlay: "remote-play",
  RemotePause: "remote-pause",
  RemoteNext: "remote-next",
  RemotePrevious: "remote-previous",
  RemoteSeek: "remote-seek",
  RemoteJumpForward: "remote-jump-forward",
  RemoteJumpBackward: "remote-jump-backward",
  RemoteStop: "remote-stop",
} as const;

export type Event = (typeof Event)[keyof typeof Event];

RemoteCommand

export const RemoteCommand = {
  PlayPause: "play-pause",
  Next: "next",
  Previous: "previous",
  Stop: "stop",
  Seek: "seek",
  JumpForward: "jump-forward",
  JumpBackward: "jump-backward",
} as const;

export type RemoteCommand = (typeof RemoteCommand)[keyof typeof RemoteCommand];

ErrorCode

type ErrorCode = "network" | "decoding" | "timeout" | "unknown";

TrackChangedReason

type TrackChangedReason =
  "completed" | "skipped-next" | "skipped-previous" | "skipped-to" | "removed" | "moved";

QueueChangedReason

type QueueChangedReason = "add" | "insert" | "remove" | "replace" | "clear" | "move" | "reshuffle";

PlayerStateChangedEvent

interface PlayerStateChangedEvent {
  previousState: PlayerState;
  currentState: PlayerState;
}

TrackChangedEvent

interface TrackChangedEvent {
  previousIndex: number;
  previousTrack: Track | null;
  currentIndex: number;
  currentTrack: Track;
  reason: TrackChangedReason;
}

PlaybackEndedEvent

interface PlaybackEndedEvent {
  lastIndex: number;
  lastTrack: Track;
}

PlaybackErrorEvent

interface PlaybackErrorEvent {
  code: ErrorCode;
  message: string;
  trackIndex?: number;
  track?: Track;
}

QueueChangedEvent

interface QueueChangedEvent {
  queue: Track[];
  playbackOrder: number[];
  reason: QueueChangedReason;
}

MetadataChangedEvent

interface MetadataChangedEvent {
  metadata: AudioMetadata;
}