Playlist and Queue

Queue manipulation beyond the basic queue([...]) call in the quickstart: inserting items mid-stream, a shuffle toggle, peek-ahead for preloading, or custom repeat behaviour.

The queue API is identical on video and music players. Examples use the music player but every method applies to both.

Queue basics

TypeScript

import { nmMPlayer } from '@nomercy-entertainment/nomercy-music-player';

const player = nmMPlayer('main').setup({
  playlist: [track1, track2, track3], // initial playlist
});

// Replace the entire queue:
player.queue([trackA, trackB, trackC]);

// Read the queue (returns a readonly snapshot):
const tracks = player.queue();
console.log(tracks.length); // 3

Append, prepend, and insert

TypeScript

// Add to the end:
player.queueAppend(track4);

// Add at the front (plays after the current item ends):
player.queuePrepend(track5);

// Insert at a specific index:
player.queueInsert(track6, 2); // inserts before index 2

Remove and move

TypeScript

// Remove by item id:
player.queueRemove('track-id-3');

// Move a track from one position to another:
player.queueMove(0, 4); // move index 0 to index 4

Jump to a track

TypeScript

// Set current item by id or by object reference:
player.item(track2);

// Jump to index:
player.seekToIndex(2);

// Read current item:
const nowPlaying = player.item();

Peek next and previous

Peek is read-only, it does not change playback:

TypeScript

const next = player.peekNext(); // next item in queue | undefined
const prev = player.peekPrevious(); // previous item | undefined

// Use peek for preloading artwork before a crossfade:
player.on('trackEndingSoon', async ({ remaining }) => {
  const upcoming = player.peekNext();
  if (upcoming) await prefetchArtwork(upcoming);
});

Shuffle

TypeScript

import { ShuffleState } from '@nomercy-entertainment/nomercy-music-player';

player.shuffleState(ShuffleState.ON);
player.shuffleState(ShuffleState.OFF);

// Read state:
const shuffled = player.shuffleState(); // ShuffleState.ON | ShuffleState.OFF

// Listen for changes:
player.on('shuffle', ({ state }) => {
  updateShuffleButton(state === ShuffleState.ON);
});

When shuffle is on, peekNext() returns the next shuffled item.

Repeat modes

TypeScript

import { RepeatState } from '@nomercy-entertainment/nomercy-music-player';

player.repeatState(RepeatState.OFF); // no repeat
player.repeatState(RepeatState.ONE); // repeat the current track
player.repeatState(RepeatState.ALL); // repeat the entire queue

// Read state:
const repeat = player.repeatState();

player.on('repeat', ({ state }) => {
  updateRepeatButton(state);
});

Auto-advance respects repeat state: with RepeatState.ONE set, the player restarts the current item when it ends instead of advancing the cursor.

Automatic advance

When the current item ends, the player advances to the next one in the queue automatically. This is built in — there is no plugin to register.

Disable it in setup() when an external orchestrator (Cast sync, a NoMercy Connect socket) drives next() itself, so an item is never advanced twice:

TypeScript

const player = nmplayer('player').setup({
  baseUrl: 'https://raw.githubusercontent.com/NoMercy-Entertainment/nomercy-media/master/Films',
  playlist: [
    { title: 'Sintel', url: '/Sintel.(2010)/Sintel.(2010).NoMercy.m3u8' },
  ],
  autoAdvance: false, // default is true
});

Sorting the queue

Use the built-in player.queueSort(compare), or sort the array yourself and set it:

TypeScript

const sorted = [...player.queue()].sort((a, b) => (a.title ?? '').localeCompare(b.title ?? ''));
player.queue(sorted);

For in-place shuffling, use Fisher-Yates before setting:

TypeScript

function shuffle<T>(array: T[]): T[] {
  const out = [...array];
  for (let i = out.length - 1; i > 0; i--) {
    const j = Math.floor(Math.random() * (i + 1));
    [out[i], out[j]] = [out[j], out[i]];
  }
  return out;
}

player.queue(shuffle([...player.queue()]));

This is a blunt replacement. The active track is preserved because the player matches by id.

Queue events

TypeScript

player.on('current', ({ item, index }) => {
  // fires when the active track changes
  nowPlayingDisplay.textContent = item?.title ?? '';
});

player.on('queue', (items) => {
  // fires when the queue array changes (append, remove, reorder, replace)
  // payload is the new queue as a plain array, not an object
  renderQueueList(items);
});