JavaScript API

JavaScript API

Every method returns the singleton (unless noted), so calls chain. Highlights:

Playback & navigation

WaveformBar.play('audio/track.mp3');              // play now (url string or track object)
WaveformBar.play({ url: 'x.mp3', title: 'X' });   // already-current → toggles play/pause
WaveformBar.togglePlay();
WaveformBar.pause();
WaveformBar.next();        // wraps to 0 when repeat === 'all'
WaveformBar.previous();    // > 3s into the track → restart; else go back
WaveformBar.skipTo(2);     // jump to queue index (toggles play if already current)

play() dedupes by URL: if the track is already queued it merges new data into that entry, otherwise it inserts right after the current index. play() does not fire onQueueChange.

Queue

WaveformBar.addToQueue({ url: 'next.mp3', title: 'Next Up' }); // append; starts if queue was empty
WaveformBar.removeFromQueue(3);  // cannot remove the current track
WaveformBar.clearQueue();        // clears all except the current track
WaveformBar.getQueue();          // shallow copy
WaveformBar.getCurrentTrack();   // object | null
WaveformBar.getCurrentIndex();   // number, -1 if none
WaveformBar.isCurrentTrack(url); // current (playing or paused)?
WaveformBar.isCurrentlyPlaying(url);

Repeat & volume

WaveformBar.cycleRepeat();    // off → all → one → off
WaveformBar.setRepeat('all'); // 'off' | 'all' | 'one' (invalid ignored)

WaveformBar.setVolume(0.5);   // 0..1, persists, emits volumechange + onVolumeChange
WaveformBar.getVolume();
WaveformBar.toggleMute();     // remembers prior volume

Favorites & cart

WaveformBar.toggleFavorite();      // current track; syncs page classes + fires actions.favorite
WaveformBar.addToCart();           // current track; flashes the button; fires actions.cart
WaveformBar.isFavorited(id?);      // defaults to current track id/url
WaveformBar.isInCart(id?);

There is no removeFromCart — the cart is an in-memory Set and is never persisted (your server is the source of truth; seed via data-wb-in-cart).

DJ markers

WaveformBar.seekToMarker(2);                 // by index — seeks and plays
WaveformBar.seekToMarkerByLabel('Drop');     // first label/title match, case-insensitive

UI & lifecycle

WaveformBar.show();   WaveformBar.hide();
WaveformBar.toggleQueuePanel();  WaveformBar.openQueuePanel();  WaveformBar.closeQueuePanel();
WaveformBar.toggleVolumePopup(); WaveformBar.openVolumePopup(); WaveformBar.closeVolumePopup();
WaveformBar.collapse(); WaveformBar.expand(); WaveformBar.toggleCollapse();
WaveformBar.getPlayer();  // the underlying WaveformPlayer instance
WaveformBar.destroy();    // tear everything down, strip .wb-current/.wb-playing from the page

Events

DOM events bubble from the bar element (#waveform-bar), prefixed waveformbar:. Listen on document.

Event	Detail	Notes
waveformbar:play	{ track }	Has onPlay callback.
waveformbar:pause	{ track }	Has onPause callback.
waveformbar:trackchange	{ track, index }	Has onTrackChange callback.
waveformbar:queuechange	{ queue, currentIndex }	Has onQueueChange callback.
waveformbar:volumechange	{ volume }	Has onVolumeChange callback.
waveformbar:favorite	{ track, favorited }	Has onFavorite callback.
waveformbar:cart	{ track }	Has onCart callback.
waveformbar:repeatchange	{ mode }	mode is 'off'/'all'/'one'. DOM-only.
waveformbar:markerchange	{ marker, index, track }	DJ-mode boundary crossed. DOM-only.
waveformbar:error	{ track }	Track failed to load/decode; auto-skips when continuous. DOM-only.
waveformbar:share	{ url, time, track }	Share button copied a link. DOM-only.
waveformbar:collapse	{ collapsed }	Emitted by collapse()/expand(). DOM-only.

document.addEventListener('waveformbar:trackchange', (e) => {
  console.log('now playing', e.detail.track.title, 'at', e.detail.index);
});
document.addEventListener('waveformbar:error', (e) => {
  console.warn('failed', e.detail.track.url);
});