Player methods
The engine is a full player — Player → Methods.
import WaveformSounds from '@arraypress/waveform-sounds';
const list = new WaveformSounds('#pack', { manifest: '/previews/sounds.json' });await list.ready;new WaveformSounds(container, options?) takes an element or a selector. It throws [WaveformSounds] Container not found: … for a selector that matches nothing.
The list is built after the constructor returns, on a later microtask (after the manifest fetch, if there is one) — so listeners attached straight after new WaveformSounds() see ready and the first filter. ready is a promise that resolves once it’s built. It never rejects: a failed build (the manifest 404s, say) resolves it too and is reported through onError and waveformsounds:error.
Calls made before it’s built are honoured: setFilter() and setSort() show in the controls once built, and play() waits for the list.
| Method | Description |
|---|---|
play(target?, opts?): void |
Play a sound — by index (in the original order), by id string, or by Sound object — or, with no target, resume the current one (else play the first visible). opts.at (0..1) starts it at that position; on the current sound it seeks there. |
pause(): void |
Pause the current sound. |
toggle(target?): void |
The current sound plays / pauses; any other sound starts. |
next(): void |
Play the next visible sound (in the current filter and sort), revealing it if it’s past the current page. No wrap at the end. |
previous(): void |
Play the previous visible sound. |
setLoop(on: boolean): void |
Loop the current sound (and every sound after it) on or off, and update the Loop toggle. When the list marks its loops, only loops repeat. |
setFilter(patch): void |
Merge patch into the current filter and re-apply it; back to the first page. Keys: query, type, key, bpmMin, bpmMax. The controls are updated to match. |
clearFilters(): void |
Reset every filter. The sort stays. |
setSort(by): void |
Change the order: 'default' | 'title' | 'bpm' | 'key' | 'duration' (anything else is 'default'). |
showMore(): void |
Reveal (and render) the next page of rows. |
destroy(opts?): void |
Tear down listeners, observers, timers and the engine. Markup the instance rendered is restored to what the container held before (its own classes and the measured --ws-surface too); adopted server markup is left as it is now — rows may be re-sorted, added, removed or marked current — so re-render it before building a new instance over it. destroy({ restore: true }) (2.1.0+) instead puts adopted markup back exactly as it arrived, ready for a new instance — what a framework re-mounting the same markup wants. |
list.setFilter({ type: 'Bass', bpmMin: 120, bpmMax: 130 });list.setSort('bpm');list.play('sound-3', { at: 0.5 });| Property | Type | Description |
|---|---|---|
container |
HTMLElement |
The element. |
options |
WaveformSoundsOptions |
The resolved options (defaults, constructor and data-* merged). |
ready |
Promise<void> |
Resolves once the list is built. Never rejects. |
sounds |
Sound[] |
Every sound, normalised, in the original order. A row’s data-ws-index is its position here — read a row’s sound as list.sounds[Number(row.dataset.wsIndex)] (since 2.2.0 a row carries nothing else). |
visible |
Sound[] |
The sounds passing the filter, in sort order (all of them, not only the rows rendered). A getter. |
current |
Sound | null |
The playing or paused sound. A getter. |
filter |
SoundsFilter |
The current filter: { query, type, key, bpmMin, bpmMax, loop }. |
sortBy |
SoundsSort |
The current order. |
playing |
boolean |
Whether a sound is playing. |
engine |
WaveformPlayer | null |
The engine player — the full player API. Built when the list is ready (when a player class is available), else on the first play. |
| Method / property | Description |
|---|---|
WaveformSounds.init(root = document): WaveformSounds[] |
Initialise every [data-waveform-sounds] under root (and root itself) that isn’t initialised yet; returns the new instances. Per-element errors are caught and logged. Run it after inserting markup. |
WaveformSounds.getInstance(el): WaveformSounds | null |
The instance on an element or selector. |
WaveformSounds.prune(): void |
Destroy the instances whose element has left the document — after a client-side navigation. Stops their audio. |
WaveformSounds.instances |
Map<Element, WaveformSounds> of every live instance. |
WaveformSounds.DEFAULT_OPTIONS |
Every option’s default — see Options. |
WaveformSounds.DEFAULT_STRINGS |
The English strings — see Strings & i18n. |
WaveformSounds.utils |
The pure data helpers — see utils. |
WaveformSounds.defineElement(name = 'waveform-sounds') |
Register the <waveform-sounds> element (2.1.0+) — for a <script> page that opted out of auto-init, which has no module import to reach defineWaveformSoundsElement(). Returns the constructor; a name already defined is left alone. |
document.addEventListener('waveformsounds:ready', () => { WaveformSounds.getInstance('#pack')?.setFilter({ type: 'Drums' });});Every event is a bubbling, composed CustomEvent dispatched from the container, so you can listen on the element or on document — from inside a shadow root too (composed since 2.1.0, like the core’s). Each detail carries the instance.
| Event | detail |
Fires |
|---|---|---|
waveformsounds:ready |
{ sounds: number, instance } |
The list is built. sounds is the count. |
waveformsounds:play |
{ sound, index, instance } |
A sound starts playing. |
waveformsounds:pause |
{ sound, index, instance } |
The playing sound pauses. |
waveformsounds:end |
{ sound, index, instance } |
A sound plays to its end. |
waveformsounds:filter |
{ visible: number, total: number, filter, sort, instance } |
After every filter, sort or page change, and once when the list is built. visible is the number of matching sounds. |
waveformsounds:error |
{ error, sound?, index?, instance } |
The list failed to build (no sound), or a sound failed to load or play. |
index is the sound’s position in sounds. The events are typed on HTMLElementEventMap — and, since 2.1.0, on DocumentEventMap and WindowEventMap too — so addEventListener('waveformsounds:play', (e) => e.detail.sound.title) type-checks on an element, document or window.
document.addEventListener('waveformsounds:filter', (e) => { const { visible, total, filter } = e.detail; if (filter.query) analytics.track('sound_search', { query: filter.query, visible, total });});2.1.0+. The instance is an EventTarget, like the core’s player: each of those moments is also dispatched on it as a plain Event named ready, play, pause, end, filter or error, right after the container’s waveformsounds:* event (whose detail carries the data). The matching on* callback still runs. Typed by WaveformSoundsInstanceEventMap.
const list = new WaveformSounds('#pack', { manifest: '/previews/sounds.json' });list.addEventListener('play', () => console.log('now playing', list.current?.title));The engine is a regular player, so its own waveformplayer:* events fire too — that’s what WaveformTracker listens to.
| Import | What it is |
|---|---|
@arraypress/waveform-sounds |
The runtime. Registers window.WaveformSounds and the <waveform-sounds> element, and initialises every [data-waveform-sounds] element when the DOM is ready. |
@arraypress/waveform-sounds/no-autoinit |
The same exports without the import-time side effects: no scan, no element registration. |
@arraypress/waveform-sounds/render |
The DOM-free server renderer. |
@arraypress/waveform-sounds/styles.css |
The stylesheet. |
The main entry’s named exports: WaveformSounds (also the default), DEFAULT_OPTIONS, DEFAULT_STRINGS, encodePeaks, decodePeaks, normalizeKey, normalizeSounds, parseManifest, facets, matches, sortSounds, formatDuration, renderSounds, renderSoundsElement, RENDER_OPTION_KEYS and pickRenderOptions (2.1.0+), and WaveformSoundsElement and defineWaveformSoundsElement (2.1.0+).
/no-autoinitFor frameworks and anything else that decides when lists are built. Importing it registers window.WaveformSounds but scans nothing and defines no element; construct instances yourself, call WaveformSounds.init() when you’re ready, or defineWaveformSoundsElement() to register the tag. The framework wrappers import it. (<html data-waveform-autoinit="false"> does the same for the main entry.)
import WaveformSounds, { defineWaveformSoundsElement } from '@arraypress/waveform-sounds/no-autoinit';
defineWaveformSoundsElement(); // <waveform-sounds>defineWaveformSoundsElement('pack-sounds'); // or under your own name/renderThe half that writes markup, and never touches window or document — safe in Node, an edge runtime or a static build.
import { renderSounds, renderSoundsElement } from '@arraypress/waveform-sounds/render';
// The inside of a [data-waveform-sounds] element:const inner = renderSounds(sounds, { pageSize: 100, columns: ['type', 'bpm', 'key'] });
// Or the whole element, wrapper included:const html = renderSoundsElement(sounds, { player: 'strip' }, 'my-extra-class');| Function | Returns |
|---|---|
renderSounds(sounds, options?) |
The component’s inner markup: the icon sprite, the toolbar, the rows the list starts with (the first page — with pageSize: 0, the first 50 — in the starting order), the footer, and every sound once as JSON in a <script type="application/json" data-ws-sounds>, which the runtime reads the sounds from. Rows carry only data-ws-index (2.2.0+; before, every row was written, each with its sound as data-*). sounds may be raw or normalised. See Server rendering. |
renderSoundsElement(sounds, options?, className?) |
The whole element: <div class="waveform-sounds waveform-sounds--<player> …" data-waveform-sounds data-player="…"> around renderSounds(). Since 2.1.0 it also writes a data-* attribute for every other render option you set (data-page-size="20", data-filters="", data-strings='…'), so the runtime adopting it keeps them; with only player set (or nothing) the element is unchanged. |
pickRenderOptions(options) |
2.1.0+. Just the render options that are set (not null / undefined) — for a wrapper handing its props to renderSounds. |
RENDER_OPTION_KEYS |
2.1.0+. The names of the options that shape the markup (the list below). |
The renderer reads the options that shape the markup — RENDER_OPTION_KEYS: player, search, filters, sorts, loopToggle, showCount, menuSearch, pageSize, columns, maxTypeChips, mergeEnharmonicKeys (2.2.0+), idPrefix, loop (whether the Loop toggle starts pressed) and strings. When the runtime finds that markup in the container it adopts it rather than rebuilding — so give the runtime the same options (as data-* on the container, or constructor options). See Server rendering.
import { renderSounds, pickRenderOptions } from '@arraypress/waveform-sounds/render';
const inner = renderSounds(props.sounds, pickRenderOptions(props));/render also exports RENDER_OPTION_KEYS, pickRenderOptions, DEFAULT_STRINGS, escapeHtml, normalizeSounds, parseManifest, encodePeaks, decodePeaks, normalizeKey, facets and formatDuration.
WaveformSounds.utils (and the same-named exports) are the pure data helpers the list runs on — the same functions on the server and in the browser.
| Function | Description |
|---|---|
encodePeaks(peaks: number[]): string |
Peaks 0..1 → the 8-bit hex string (two characters per bar). waveform-gen --manifest encodes byte-for-byte the same way. |
decodePeaks(value, scale = 1): number[] | null |
A hex string, the core’s compact wp1: string (2.1.0+), an array of 0..1, or an integer array with its scale → peaks 0..1. null for nothing usable. |
normalizeKey(key): string |
Any common key spelling → the short form ("F minor" → Fm, "C♯" → C#). Unparseable keys come back trimmed, as given. |
normalizeSounds(list, peakScale = 1): Sound[] |
Normalise a list: drop sounds without a url, fill in titles and ids, de-duplicate ids. |
parseManifest(manifest): Sound[] |
Read a manifest object (or a bare array), honouring peakScale. |
facets(sounds, opts?) |
What the controls would offer: { types: {name, count}[], keys: string[], keyAliases: Record<string, string[]>, bpm: {min, max} | null, hasDuration: boolean, loops: number, oneShots: number }. With enharmonic keys merged (the default; opts.mergeEnharmonicKeys: false to keep them apart, 2.2.0+), keys holds one spelling per key and keyAliases each entry’s other spellings. |
matches(sound, filter?, opts?): boolean |
Whether a sound passes a filter — the same search and filter rules as the list. opts.mergeEnharmonicKeys (default true, 2.2.0+): a key filter in either spelling matches. |
sortSounds(sounds, by = 'default'): Sound[] |
A sorted copy. Missing values sort last. |
formatDuration(seconds): string |
m:ss; tenths under a second (0.4s, 0.1.3+); '' when unknown. |
renderSounds(sounds, options?): string |
As above. |
const sounds = WaveformSounds.utils.parseManifest(await (await fetch('/previews/sounds.json')).json());const bassIn128 = sounds.filter((s) => WaveformSounds.utils.matches(s, { type: 'Bass', bpmMin: 128, bpmMax: 128 }));The package ships TypeScript declarations generated from its source (2.0; 0.x shipped a hand-written index.d.ts). The exports map points each entry at its declarations, and the option types live in types/types.d.ts. The framework components derive their props from them.
| Type | Shape |
|---|---|
WaveformSoundsOptions |
Every option. |
SoundInput |
A sound as given — see Sound fields. |
Sound |
A normalised sound: { id: string, url: string, title: string, type: string, bpm: number | null, key: string, duration: number | null, tags: string[], peaks: number[] | null, waveform: string | null, download: string | null, loop: boolean }. |
SoundsManifest |
{ version?: number, peakScale?: number, sounds: SoundInput[] }. |
SoundsFilter |
{ query: string, type: string, key: string, bpmMin: number | string, bpmMax: number | string, loop?: SoundsLoopFilter }. '' means “any”. |
SoundsLoopFilter |
'' | 'loop' | 'one-shot' |
SoundsSort |
'default' | 'title' | 'bpm' | 'key' | 'duration' |
SoundsLayout |
'inline' | 'strip' |
SoundsFilterControl |
'type' | 'key' | 'bpm' | 'loop' |
SoundsColumn |
'type' | 'bpm' | 'key' | 'duration' |
WaveformSoundsStrings |
Every string. |
WaveformSoundsEventMap |
The waveformsounds:* events and their detail. |
WaveformSoundsInstanceEventMap |
The plain events on the instance: ready, play, pause, end, filter, error. 2.1.0+. |
Call destroy() when removing a list in a single-page app — it stops the audio (the engine is destroyed), and drops every listener and observer. After a client-side navigation that replaced the page, WaveformSounds.prune() does the same for every list whose element is gone.
list.destroy();
// Re-mounting the same server-rendered markup (a framework island, say):list.destroy({ restore: true });new WaveformSounds(container);Player methods
The engine is a full player — Player → Methods.
Sounds manifest
Writing the JSON this reads — Generator → Sounds manifest.