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 (empty values never overwrite queued ones), otherwise it inserts right after the current index. play() does not fire onQueueChange. When the browser refuses playback (autoplay policy), togglePlay() and seekToMarker() catch the rejection and restore the paused state (1.12.0+).

Queue

WaveformBar.addToQueue({ url: 'next.mp3', title: 'Next Up' }); // append; starts if queue was empty; emits queuechange (1.12.0+)
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, shuffle & volume

WaveformBar.cycleRepeat();    // off → all → one → off
WaveformBar.setRepeat('all'); // 'off' | 'all' | 'one' (invalid ignored)
WaveformBar.toggleShuffle();  // emits shufflechange + onShuffleChange
WaveformBar.setShuffle(true); // turning it on starts a fresh shuffle pass

WaveformBar.setVolume(0.5);   // 0..1, persists (if persist), 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

destroy() also sets every synced inline player to paused and (1.12.0+) resets in-memory session state — mute, favorites, cart, resume position, active markers, the collapsed flag — so a following init() with different config starts clean. Persisted storage is left alone.

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:shufflechange	{ shuffle }	Has onShuffleChange callback.
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);
});