Queue

MediaItem

Every item in the queue is a MediaItem:

Field	Type	Description
`url`	`string \\| number \\| { uri, headers }`	Audio source
`mediaId`	`string`	Unique identifier (falls back to URL)
`title`	`string`	Track title
`artist`	`string`	Artist name
`albumTitle`	`string`	Album title
`artworkUrl`	`string`	Artwork image URL
`duration`	`number`	Duration hint in seconds (optional)
`isLive`	`boolean`	Marks a live stream — disables caching and preloading

Setting the queue

Replace the entire queue and start from a given index:

await TrackPlayer.setMediaItems(items, startIndex?: number);

Set a single item (replaces queue with one track):

await TrackPlayer.setMediaItem(item);

Adding tracks

// Append to end of queue
await TrackPlayer.addMediaItem(item);
await TrackPlayer.addMediaItems(items);

// Insert at a specific index
await TrackPlayer.insertMediaItem(index, item);
await TrackPlayer.insertMediaItems(index, items);

Removing tracks

// Remove by index
await TrackPlayer.removeMediaItem(index);

// Remove a range (inclusive)
await TrackPlayer.removeMediaItems(fromIndex, toIndex);

// Clear the entire queue
await TrackPlayer.clear();

Reordering

await TrackPlayer.moveMediaItem(fromIndex, toIndex);

Replacing a track

await TrackPlayer.replaceMediaItem(index, newItem);

Updating metadata

Useful for live streams where metadata arrives mid-playback (e.g. ICY stream tags):

await TrackPlayer.updateMetadata(index, {
  title: 'Now Playing: Song Title',
  artist: 'Artist Name',
});

Reading queue state

const queue = TrackPlayer.getQueue();
const current = TrackPlayer.getActiveMediaItem();
const index = TrackPlayer.getActiveMediaItemIndex();

All three are synchronous — no await needed.