Skip to content

Options

Set options as constructor options or as data-* attributes on the container. Precedence is the family’s: container data-* > constructor option > default. An option left unset (or null / undefined) never overrides a default.

new WaveformSounds('#pack', { manifest: '/previews/sounds.json', pageSize: 100, autoAdvance: true });
<div data-waveform-sounds data-manifest="/previews/sounds.json" data-page-size="100" data-auto-advance></div>

How the attributes are read:

  • Names are kebab-case: pageSize → data-page-size.
  • Booleans — present-and-empty or "true" is on, "false" is off; anything else is ignored. So data-search="false" hides the search box.
  • Numbers — an empty attribute counts as not set.
  • Lists (filters, sorts, columns) are comma-separated: data-columns="type, key". An empty attribute is an empty list — data-sorts="" is no Sort menu, not the default one.
  • JSON (strings, playerOptions) — invalid JSON logs [WaveformSounds] Ignoring invalid JSON in data-<name> and is ignored rather than breaking the list.
  • data-url-state — "true" or empty is true, "false" is off, anything else is the parameter prefix.

Unknown entries in filters, sorts and columns are dropped, menuSearch / maxTypeChips / pageSize are rounded down to whole numbers (anything that isn’t a number of 0 or more falls back to the default), and any player other than 'strip' is 'inline'.

Option data-* Type Default Description
sounds — SoundInput[] | null null The sounds — see Sound fields. An array (even an empty one) wins over manifest. In markup, the equivalent is server-rendered rows.
manifest data-manifest string | null null URL of a sounds manifest (JSON), fetched when there are no sounds and no server-rendered rows. A non-2xx response is reported through onError and waveformsounds:error.
Option data-* Type Default Description
player data-player 'inline' | 'strip' 'inline' 'inline': a mini waveform per row; the playing row fills and seeks. 'strip': plain rows and one full player docked below. See Layouts.
search data-search boolean true Show the search box.
filters data-filters ('type' | 'key' | 'bpm' | 'loop')[] ['type', 'key', 'bpm', 'loop'] Which filter controls to offer. Each appears only when the data has something to filter: 2+ types, 2+ keys, a spread of BPMs, both loops and one-shots ('loop', 0.2.0+). [] = no filters.
sorts data-sorts ('default' | 'title' | 'bpm' | 'key' | 'duration')[] all five, in that order The orders the Sort menu offers, in order; the first is the starting order. Orders the data can’t use are dropped. [] (or a single usable order) hides the menu.
showCount data-show-count boolean true Show the 12 of 300 sounds count.
menuSearch data-menu-search number 8 A dropdown (type / key / sort) gets a search field when it has more than this many options.
maxTypeChips data-max-type-chips number 10 Up to this many types show as chips; more become a Type menu.
loopToggle data-loop-toggle boolean true Show the Loop toggle. When any sound is marked loop: true, it repeats only loops.
pageSize data-page-size number 50 Rows shown before Show more. 0 shows all — rendered 50 at a time as the list scrolls (2.2.0+).
columns data-columns ('type' | 'bpm' | 'key' | 'duration')[] ['type', 'bpm', 'key', 'duration'] The columns after the title, in this order. [] = title only.
mergeEnharmonicKeys data-merge-enharmonic-keys boolean true Enharmonic keys are one key: A#m and Bbm (C# and Db, …) are one key-menu entry, a filter on either finds both, and the search and ?key= take either spelling. The entry shows the spelling the pack uses most; a tie goes to the conventional key signature (Db, Eb, F#, Ab, Bb, B major; C#m, Ebm, F#m, G#m, Bbm minor). Rows show their key as written. false keeps every spelling apart. A render option. 2.2.0+. See Enharmonic keys.
idPrefix data-id-prefix string the container’s id, else a hash of the sounds Prefix for the dropdowns’ element ids. Two lists of the same sounds on one page each need one (or an id). The framework wrappers always pass a unique one.
urlState data-url-state boolean | string false Keep the filters and sort in the address. true uses q, type, key, bpm, loop, sort; a string prefixes them ('pack' → pack-q, …). See Filters in the address.

These style the row canvases in the inline layout. (The engine player’s own look is set through playerOptions.)

Option data-* Type Default Description
waveformStyle data-waveform-style 'mirror' | 'bars' 'mirror' Row waveform style. Anything else is 'mirror'.
waveformColor data-waveform-color string | null null → CSS --ws-wave-color Unplayed bar colour — a value a canvas accepts (#888, rgba(…); not var()).
progressColor data-progress-color string | null null → CSS --ws-progress-color Played-part colour — a value a canvas accepts.
barWidth data-bar-width number 2 Bar width in CSS px (at least 1).
barGap data-bar-gap number 1 Gap between bars in CSS px (at least 0).

With the colours left unset, the canvas uses the --ws-wave-color and --ws-progress-color custom properties, resolved to real colours by the runtime (a canvas can’t read CSS) and re-read when the page’s theme flips.

Option data-* Type Default Description
loop data-loop boolean | null null Start with Loop on or off. null: on when any sound is marked loop: true (then only loops repeat), off otherwise (0.3.0+; false before). Change it later with setLoop().
autoAdvance data-auto-advance boolean false Play the next visible sound when one ends (in the current filter and sort; no wrap at the end).
arrowAudition data-arrow-audition boolean true While a sound plays, ↑ / ↓ (and Home / End) move to a row and play it — the sample-browser audition. Off, they only move focus.
Option data-* Type Default Description
playerOptions data-player-options (JSON) object | null null Options for the engine WaveformPlayer — colours, height, waveformStyle, preload, … — and its callbacks, which are called after the list’s own, with the same arguments. See what the list forces below.
playerClass — typeof WaveformPlayer | null null → window.WaveformPlayer The WaveformPlayer class to build the engine from, for ESM setups without the global.

The engine’s defaults, before playerOptions is applied:

Engine option inline strip
height 32 (hidden) 48
waveformStyle 'bars' 'mirror'
preload 'metadata' 'metadata'
singlePlay true true
new WaveformSounds('#pack', {
manifest: '/previews/sounds.json',
player: 'strip',
playerOptions: { height: 64, waveformStyle: 'bars', onPlay: () => console.log('engine playing') },
});

The list depends on a few engine settings, so these are applied after playerOptions (2.0):

Engine option In 2.0 Why
audioMode always 'self' The list owns its audio.
loop, showLoop always off The list owns looping (its Loop toggle repeats only sounds marked as loops). The player’s own loop would stop ended, stalling autoAdvance and the row state, and its button would loop one-shots behind the list’s back.
duration, downloadUrl, downloadName dropped They describe one track. Each sound brings its own: a sound’s duration reaches the engine (so the total time and the Media Session scrubber are right before the audio’s metadata), and in the strip layout, with playerOptions: { showDownload: true }, the engine’s download link is the sound’s download, else its audio.
onPlay, onPause, onEnd, onTimeUpdate, onLoad, onError chained The list’s handler always runs; yours runs after it.

Everything else passes through — including the 2.0 showVolume, volume, showDownload and their labels. lazy is accepted but has no effect: the engine loads nothing until a sound plays.

Option data-* Type Default Description
strings data-strings (JSON) Partial<WaveformSoundsStrings> | null null → English Every visible or announced word. Partial: merged over the English defaults. See Strings & i18n.

Each callback fires alongside the matching bubbling waveformsounds:* event. Constructor-only — there are no data-* forms.

Option Signature Fires
onReady (instance) => void The list is built (after the manifest fetch, if any).
onPlay (sound, instance) => void A sound starts playing.
onPause (sound, instance) => void The playing sound pauses. Fires once at a natural end, not twice.
onEnd (sound, instance) => void A sound plays to its end (before an auto-advance).
onFilter (visible, instance) => void After every filter, sort or page change — and once when the list is built — with the matching sounds, in sort order.
onError (error, instance) => void The list failed to build (e.g. the manifest request failed), or a sound failed to load or play.

sound is the normalised Sound — { id, url, title, type, bpm, key, duration, tags, peaks, waveform, download, loop }.

WaveformSounds.DEFAULT_OPTIONS (also a named export) holds every default:

{
player: 'inline',
search: true,
filters: ['type', 'key', 'bpm', 'loop'],
sorts: ['default', 'title', 'bpm', 'key', 'duration'],
loopToggle: true,
showCount: true,
menuSearch: 8,
pageSize: 50,
columns: ['type', 'bpm', 'key', 'duration'],
maxTypeChips: 10,
mergeEnharmonicKeys: true,
sounds: null,
manifest: null,
waveformStyle: 'mirror',
waveformColor: null,
progressColor: null,
barWidth: 2,
barGap: 1,
loop: null,
autoAdvance: false,
arrowAudition: true,
idPrefix: null,
urlState: false,
playerOptions: null,
playerClass: null,
strings: null,
onReady: null, onPlay: null, onPause: null, onEnd: null, onFilter: null, onError: null,
}