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. Sodata-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 istrue,"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. |
Layout and toolbar
Section titled “Layout and toolbar”| 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. |
Row waveform
Section titled “Row waveform”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.
Behaviour
Section titled “Behaviour”| 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. |
Engine
Section titled “Engine”| 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') },});What playerOptions can’t change
Section titled “What playerOptions can’t change”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.
Strings
Section titled “Strings”| 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. |
Callbacks
Section titled “Callbacks”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 }.
Defaults at a glance
Section titled “Defaults at a glance”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,}