Skip to content

Overview

Playback state methods expose and control coarse play, volume, repeat, and shuffle tokens. These are the high-level selectors that UI components subscribe to via player.on('play', ...) events and read via these snapshot getters.

playState()

Current play-state token. Read-only snapshot. Subscribe to play / pause / stop events to track changes reactively.

Returns: PlayStateToken, one of 'idle' | 'loading' | 'playing' | 'paused' | 'stopped' | 'error'

volumeState()

Current volume-state token. Read-only snapshot. Subscribe to mute events.

Returns: VolumeStateToken, one of 'unmuted' | 'muted'

repeatState(state?)

Read or write the repeat mode.

Read: repeatState() returns the current RepeatStateToken.

Write: repeatState(state) sets the repeat mode and emits repeat with the new token. The transport mixin honours this token inside next():

  • 'off', no repeat; next() emits queue:exhausted at the end
  • 'one', reload the current item on next(); cursor does not move
  • 'all', wrap to the first item when next() reaches the last item

Returns: RepeatStateToken | void, one of 'off' | 'one' | 'all'

Events emitted: repeat with { state: RepeatStateToken }

TypeScript
// cycle through modes
const modes: RepeatStateToken[] = ['off', 'one', 'all'];
repeatButton.addEventListener('click', () => {
  const current = player.repeatState() ?? 'off';
  const next = modes[(modes.indexOf(current) + 1) % modes.length]!;
  player.repeatState(next);
});

shuffleState(state?)

Read or write the shuffle mode.

Read: shuffleState() returns 'on' or 'off'.

Write:

  • shuffleState('on'), randomises the queue order immediately via queueShuffle(), then emits shuffle.
  • shuffleState('off'), updates the token and emits shuffle. The queue order is NOT restored; the current (shuffled) order is kept. Re-supply the queue to restore the original order.

Accepts a ShuffleStateToken or a plain boolean (true becomes 'on', false becomes 'off').

Events emitted: shuffle with { state: 'on' | 'off' }; queue:shuffle (via queueShuffle()) when enabling

TypeScript
player.shuffleState(true); // enable
player.shuffleState(false); // disable (queue stays shuffled)

player.on('shuffle', ({ state }) => {
  shuffleButton.classList.toggle('active', state === 'on');
});

Mutation guards and hot mutations

playState and volumeState are read-only getters with no before-mutation guard. repeatState and shuffleState write mutations go through _emitBeforeMutation when mutationGuards is not false. time, volume, and playbackRate are classified as hot mutations and skip the guard by default, because they fire too often. Pass mutationGuards: 'all' to setup() to guard them during debugging.

See also