API Reference

The player exposes a global WebPlayer object that provides full programmatic control over playback, volume, playlist, and events.

The WebPlayer object

Once the loader script has initialized, a global WebPlayer object is available on window. All methods below are accessed through this object:

// Wait for the player to be ready
WebPlayer.events.on('player:ready', () => {
  console.log('WebPlayer is ready');
  console.log('Tracks found:', WebPlayer.playlist.length);
});

Playback methods

Method	Description
`play(index?)`	Start playback. Optionally pass a track index to play a specific track.
`pause()`	Pause the current track.
`togglePlayPause()`	Toggle between play and pause states.
`next()`	Skip to the next track in the playlist.
`previous()`	Go back to the previous track in the playlist.
`seek(seconds)`	Seek to a specific time in seconds within the current track.
`stop()`	Stop playback and reset the current track position.

Volume methods

Method	Description
`setVolume(level)`	Set the volume level. Accepts a number between 0 (muted) and 1 (full).
`getVolume()`	Returns the current volume level as a number between 0 and 1.
`setMuted(muted)`	Set the muted state. Pass true to mute, false to unmute.
`getMuted()`	Returns true if the player is currently muted.
`toggleMute()`	Toggle the muted state.

Info methods

Method	Description
`getCurrentTrack()`	Returns the current track object with properties like title, url, duration, and artist.
`getCurrentTime()`	Returns the current playback position in seconds.
`getDuration()`	Returns the total duration of the current track in seconds.
`isReady()`	Returns true if the player has initialized and is ready to accept commands.

Playlist access

Method	Description
`playlist.getTracks()`	Returns an array of all track objects in the current playlist.
`playlist.getCurrentIndex()`	Returns the index of the currently active track.
`playlist.length`	The total number of tracks in the playlist.

Usage example

// Play the third track
WebPlayer.play(2);

// After 10 seconds, skip to the next track
setTimeout(() => {
  WebPlayer.next();
}, 10000);

// Get info about the current track
const track = WebPlayer.getCurrentTrack();
console.log(track.title, track.url);

// Set volume to 50%
WebPlayer.setVolume(0.5);

// Access the full playlist
const tracks = WebPlayer.playlist.getTracks();
tracks.forEach((t, i) => console.log(i, t.title));

Events

Listen for events using WebPlayer.events.on(eventName, callback). Remove listeners with WebPlayer.events.off(eventName, callback).

Event	Description and Payload
`track:change`	Fired when the active track changes. `{ track, index }`
`playback:play`	Fired when playback starts.
`playback:pause`	Fired when playback is paused.
`playback:stop`	Fired when playback is stopped.
`playback:timeupdate`	Fired continuously during playback. `{ currentTime, duration }`
`playback:volumechange`	Fired when the volume changes. `{ volume, muted }`
`playback:buffering`	Fired when the player is buffering. `{ percent }`
`playback:error`	Fired on playback error. `{ message, track }`
`scanner:complete`	Fired when the DOM scanner finishes. `{ trackCount }`
`entities:detecting`	Fired when entity detection begins. Requires term detection (not yet available for external embeds).
`entities:complete`	Fired when entity detection finishes. Requires term detection (not yet available for external embeds). `{ count }`
`player:ready`	Fired when the player has fully initialized.
`player:destroy`	Fired when the player is destroyed.

Event listener example

// Track changes
WebPlayer.events.on('track:change', ({ track, index }) => {
  console.log('Now playing:', track.title, 'at index', index);
});

// Progress updates
WebPlayer.events.on('playback:timeupdate', ({ currentTime, duration, progress }) => {
  document.querySelector('.progress-bar').style.width = (progress * 100) + '%';
});

// Volume changes
WebPlayer.events.on('playback:volumechange', ({ volume, muted }) => {
  console.log('Volume:', volume, 'Muted:', muted);
});

// Error handling
WebPlayer.events.on('playback:error', ({ track, error }) => {
  console.error('Failed to play:', track.title, error);
});

// Remove a listener
function onReady() {
  console.log('Player ready');
}
WebPlayer.events.on('player:ready', onReady);
WebPlayer.events.off('player:ready', onReady);