Skip to main content

Queue player

MediaPlaylistItem Interface​

The MediaPlaylistItem interface defines the structure of media items in the playback queue.

interface MediaPlaylistItem {
  /// URL of the audio content
  contentURL: string;
  /// Unique content ID for the item (optional)
  mediaId?: string;
  /// Metadata displayed on the lock screen widget during playback
  mediaMetadata?: Record<AndroidMediaMetadataKeys, string> | Record<iOSMediaMetaDataKeys, string>;
  /// Additional custom metadata for application-specific use
  customMetadata?: string;
}

Adding Items to Queue​

Add a Single Item​

Add a single item into the QueuePlayer

const item = {
  contentURL: 'https://example.com/audio/new-track.mp3',
  mediaMetadata: {
    TITLE: 'New Track',
    ARTIST: 'Artist Name',
    ALBUM: 'Album Name',
    DURATION: '300000', // Duration is required and must be specified in milliseconds (ms).
    ARTWORK_URL: 'image-Url' // displays artwork in lock screen and Now Playing info.
  }
};
await player.addItemToQueue(item)

Add Multiple Items​

Add multiple items into the QueuePlayer

await player.addMultipleItemsToQueue(items)

Note:

  • Items are appended to the end of the queue by default.
  • The onPlayerQueueChanged callback is triggered whenever items are successfully added to the queue.

Retrieving Queue Items​

To retrieve the current queue items from the player.

const allItems = await player.getAllItems()

Removing Items from Queue​

Remove a Specific Item​

Remove an item by its index (based on the array returned by player.getAllItems()):

await player.removeFromQueueWithIndex(queueIndex)

Remove Multiple Items​

Remove a range of items (based on the array returned by player.getAllItems()) from the queue:

await player.removeMultipleItems(
  queueStartPosition, queueStartPosition + 5)

Important Notes:

  • If the currently playing item is removed, playback automatically advances to the next item in the queue.
  • If you remove the currently playing item along with its previous and next items, playback continues with the next available item (if any).
  • The onPlayerQueueChanged callback is triggered whenever items are successfully added to or removed from the queue.

Queue Navigation Controls​

Check for Next Item​

Display the "play next" control only when a next item is available. If this returns false, the current item is the last one in the queue.

let isAvailableNextItem = await player.hasNextItem();

Play Next Item​

let isAvailableNextItem = await player.hasNextItem();
if (isAvailableNextItem) {
  // Play the next item in the queue. The MediaPlaylistItemTransitionListener will be triggered on successful transition.
  await player.playNext();
}

Note: Always verify player.hasNextItem() before calling player.playNext().

Check for Previous Item​

Display the "play previous" control only when a previous item is available. If this returns false, the current item is the first one in the queue.

let isAvailablePreviousItem = await player.hasPreviousItem()

Play Previous Item​

let isAvailablePreviousItem = await player.hasPreviousItem()
if (isAvailablePreviousItem) {
  // Play the previous item in the queue. The MediaPlaylistItemTransitionListener will be triggered on successful transition.
  await player.playPrevious()
}

Note: Always verify player.hasPreviousItem() before calling player.playPrevious().

Get Currently Playing Item​

Retrieve the current playing item to display in your application UI:

let currentItem = await getCurrentlyPlayingItem();

Player Event Listeners​

Implement all required listeners (e.g., onStateChanged, etc.), and ensure the following queue-specific listeners are included:

MediaPlaylistItemTransitionListener​

Triggered when the player transitions to the next / previous item in the queue. This listener converts the internal media format to a MediaPlaylistItem object.

const playerListener = {
  MediaPlaylistItemTransitionListener() {
    console.log('Player has transitioned to a different content item');
  },
}

onPlayerQueueChanged​

Triggered when the player queue is modified (items added or removed). This callback does not provide details about the specific changes made.

const playerListener = {
  onPlayerQueueChanged() {
    console.log('Queue has been updated');
  },
}