Features
Layouts
Section titled “Layouts”player picks one of two layouts:
inline(default) — every row has a mini waveform. The playing row fills with progress, and pressing its waveform seeks. The engine player is hidden.strip— plain rows with no waveform; the engine is shown as a full player docked under the list for the current sound, and it starts with the first sound cued — its title, waveform and length, ready to play (0.3.1+; before that it was an empty frame). It stays in place under the list; set--ws-strip-position: stickyto keep it at the bottom of the viewport while a long list scrolls. A sound’swaveform(full-resolution peaks) is drawn there when it has one; otherwise its rowpeaksare.
<div data-waveform-sounds data-manifest="/previews/sounds.json" data-player="strip"></div>Search and filters
Section titled “Search and filters”Above the rows, in order: the search box, a row of controls (type menu, key menu, BPM menu, Loops / One-shots, sort menu, Loop toggle), then the type chips and the count.
- Search matches every word, in any order, against the title, type, key and tags — forgiving one typo in a word of four letters or more, so
drunfinds drum loops. A number in the query also matches the BPM exactly:bass 128finds 128 BPM bass loops. - Type — one chip per type, with its count, plus All. Past
maxTypeChipstypes (default 10) the chips become a Type menu instead: a pack has a handful of types, a whole library can have fifty. - Key — a menu of every key in the data, in musical order (C, C#, D … B, each major before its minor). Enharmonic spellings are one key (2.2.0+): a pack that writes both A#m and Bbm gets one entry, and picking it finds both. See Enharmonic keys.
- BPM — a menu (
Any BPM, or120–128 BPMonce set) opening a two-handle range across the pack’s own tempos. Drag either handle (or focus one and use the arrow keys, one BPM a step); the label follows the drag and the list re-filters once it settles. A handle left at an end is no limit on that side. Sounds without a BPM drop out while a limit is set. 0.3.0+; before that, two number fields. - Sort — the orders in
sorts, the first being the starting order:default(as given),title(natural order, soLoop 2sorts beforeLoop 10),bpm,keyandduration. Sounds missing the value sort last. - Loop — repeats the current sound. On a list that marks its loops it starts on and repeats only loops (a one-shot plays once); on one that doesn’t, it starts off and repeats whatever plays. The
loopoption overrides the starting state. - The count —
300 sounds, or12 of 300 soundswhile a filter is on. It’s anaria-liveregion.
Every control appears only when the data gives it something to do: no type filter for a single type, no key menu for a single key, no BPM range without a spread of tempos, no Loops / One-shots filter unless the list has both, no sort order the data can’t use (no BPM sort without BPMs), and no Sort menu with only one usable order. And every control can go: search, filters, sorts, loopToggle, showCount and columns remove them one by one. To take BPM out everywhere, leave it out of all three lists:
new WaveformSounds('#pack', { manifest: '/previews/sounds.json', filters: ['type', 'key'], columns: ['type', 'key', 'duration'], sorts: ['default', 'title', 'key'],});<div data-waveform-sounds data-manifest="/previews/sounds.json" data-filters="type,key" data-columns="type,key,duration" data-sorts="default,title,key"></div>An empty list attribute means none: data-filters="" shows no filter controls and data-sorts="" no Sort menu — which is different from leaving the attribute out (the default set).
The type, key and sort menus are a button and a popup listbox (the WAI-ARIA combobox / listbox pattern). One with more than menuSearch options (default 8) gets a search field; type to narrow, ↑ / ↓ to move, Enter to pick, Esc to close.
When nothing matches, the list says so (No sounds match.) with a Clear filters button. Clearing keeps the sort.
Hundreds of sounds
Section titled “Hundreds of sounds”A pack can have 300 previews — a library, thousands — so nothing in the list is per-sound heavy:
- One engine. A single
WaveformPlayerplays every sound; selecting a row calls itsloadTrack(). No row ever holds an<audio>element. - Rows exist only while they’re shown (2.2.0+). With paging, the page is in the DOM; with
pageSize: 0, rows are rendered 50 at a time as the list scrolls toward its end. A row that stops being shown (filtered out, sorted past the page) leaves the DOM and is kept, drawing and all, for when it returns. Filtering, sorting, search, the address, ↑ / ↓ / Home / End,next(), auto-advance and the “Playing…” announcement all work across rows not rendered yet — ↓ or End renders up to the row it lands on. - Rows are pictures. A row’s waveform is a canvas drawn from its low-resolution
peaks(128 bars fromwaveform-gen3.1.0+, 64 before), and only once the row is within 200px of the viewport. Any number of peaks draws well: with more bars than peaks, the bars between are interpolated (2.2.0+; before, each peak was repeated into flat steps), so 64, 128 andwp1:peaks of any length give the same shape. Rows are redrawn when the list is resized and when the page’s theme flips. - Icons are defined once (2.2.0+): one hidden SVG sprite per list, and each icon a
<use>of it — not a copy of every path in every row. - Small data. Peaks travel as an 8-bit hex string, two characters per bar — about 256 characters a sound at 128 bars, a few tens of KB for a pack where a JSON number array would be several times that.
- No decoding. A sound with
peaksnever makes the engine download and decode its whole file just to draw it. - Paging.
pageSize(default 50) rows show first, then a Show 50 more button;pageSize: 0shows them all (rendered as they scroll into reach, above). Filtering and sorting work across every sound, not only the page shown, andnext()/ auto-advance reveal the next page when they reach it. - One manifest request, written at build time by
waveform-gen --manifest, instead of a JSON per sound.
What rendering only the shown rows bought, measured in Chromium (2.1.0 → 2.2.0):
| 1000 sounds, paging off | 300 sounds, default paging | |
|---|---|---|
| DOM elements | 17,001 → 1,182 | 5,325 → 1,182 |
| Load’s longest task | 287 → 0 ms (server-rendered: 289 → 0) | — |
| Clear filters | 82 → 16 ms | 31 → 20 ms |
| Sort by name | 163 → 35 ms | 50 → 17 ms |
| Server markup | 1.37 MB → 337 KB (142 → 91 KB gzipped) | 429 → 147 KB |
Keyboard
Section titled “Keyboard”| Key | Where | Does |
|---|---|---|
| Tab | Into the list | The list is one Tab stop (2.1.0+; a roving tabindex, set at runtime): Tab lands on the focused row’s play button (else the first row’s), then that row’s download link and — on the current sound — its seek slider, then leaves the list. Move between rows with ↑ / ↓. |
| ↑ / ↓ | A row | Move to the previous / next row; while a sound plays, play that row too (the sample-browser audition — turn it off with arrowAudition: false). ↑ on the first row goes back to the search box. |
| Home / End | A row | First / last visible row (auditioning the same way) — rendering it first if it isn’t yet (2.2.0+). |
| Home / End | The current row’s seek slider | Seek to the start / end (2.1.0+). |
| ← / → | The playing row | Seek back / forward 10% (stopping just short of the end, so a held → can’t end the sound). |
| Space / Enter | A row | Play / pause it. |
/ |
Anywhere in the list, outside a text field | Focus the search box. |
| ↓ | The search box | Into the list (the first visible row). |
| Esc | The search box | Clear the search. |
| ↑ / ↓, Home / End, Enter, Esc | An open menu | Move, pick, close. Typing in its search field narrows it. |
Keys with Alt, Ctrl or Cmd held pass through. After a mouse or touch play, focus moves (quietly, with no scroll jump and no focus ring) to that row’s play button, so the arrow keys drive the list instead of scrolling the page.
Each row is a list item with a play button (aria-pressed, labelled Play <title> / Pause <title>), and reads as a sentence (2.2.0+): its visible cells are aria-hidden, and a visually hidden .ws-sr says “Bass loops, 130 BPM, key B minor, 0:07, Loop” — the columns the row shows, the values it has — which the play button is aria-describedby. (2.1 read the bare cells: “Bass loops 130 Bm 0:07”.)
There is one seek slider (2.2.0+): only the current sound’s waveform is a role="slider" (0–100, read out as a time — “0:12 of 0:30”, string seekValue); every other row’s waveform is aria-hidden, so a screen reader no longer meets “Seek …” once per row. ← / → and Home / End on it are unchanged. The download link is labelled Download <title>; and a polite live region announces Playing <title> (and Could not play <title> when a sound fails, 2.1.0+). Every one of those words — the row sentence’s too — is a string you can translate.
Filters in the address
Section titled “Filters in the address”urlState: true keeps the filters and the sort in the URL, so a filtered list can be shared and survives a refresh:
?q=bass&type=Bass+loops&key=Fm&bpm=120-130&loop=one-shot&sort=bpm| Parameter | Holds |
|---|---|
q |
The search text. |
type |
The selected type. |
key |
The selected key (any spelling is normalised: key=F+minor works; with merged keys, either spelling selects the entry — key=A%23m finds the Bbm sounds too). |
bpm |
The range: 120-130, 120- (at least) or -130 (at most). |
sort |
The sort order — left out while it’s the starting one. |
A string prefixes the names, for a page with more than one list: urlState: 'pack' reads and writes pack-q, pack-type, pack-key, pack-bpm and pack-sort. As an attribute, data-url-state="true" (or a bare data-url-state) is true, "false" is off, and anything else is the prefix.
The address is rewritten with history.replaceState a quarter of a second after a change, so filtering adds no back-button entries; every other parameter and the hash are kept. Values the list can’t use — a type it doesn’t have, a key no sound is in, a sort it doesn’t offer — are ignored, never applied, so a stale link shows the whole list rather than an empty one.
Enharmonic keys
Section titled “Enharmonic keys”2.2.0+. A pack that names some files A#m and others Bbm — or C# and Db — means one key. By default (mergeEnharmonicKeys: true) they are one key:
- One key-menu entry, and a filter on it finds every spelling. The search finds either spelling too, and
?key=accepts either. - The entry shows the spelling the pack uses most. A tie goes to the conventional one — the key signature with the fewest accidentals: Db, Eb, F#, Ab, Bb and B major; C#m, Ebm, F#m, G#m and Bbm minor (F# and Ebm for the six-sharps-or-six-flats ties).
- Rows show their key as written — merging changes the menu and the filter, never your data.
mergeEnharmonicKeys: false (data-merge-enharmonic-keys="false") keeps every spelling a key of its own. It shapes the key menu’s markup, so the server renderer takes it too (its options carry the other spellings as data-alt).
Loops and one-shots
Section titled “Loops and one-shots”0.2.0+. A sound is a one-shot unless it says otherwise. Mark the loops:
{ url: '/previews/drums-01.mp3', title: 'Drums 01', bpm: 128, loop: true }That does three things:
- A loop icon beside the name (and “Loop” at the end of the row’s read-out). One-shots carry nothing.
- An All / Loops / One-shots filter, once the list has both kinds — someone hunting for a kick doesn’t have to scroll past forty drum loops. It’s the
'loop'entry infilters(on by default; leave it out to hide the control), and?loop=loop/?loop=one-shotwithurlState. - The Loop toggle starts on, and repeats only loops (0.3.0+; on 0.2.x it started off). A one-shot always plays once, toggle or not; turn it off to hear loops once.
A list that marks no loops behaves exactly as before: no filter, and the Loop toggle repeats whatever plays. waveform-gen --manifest (2.2.0+) sets loop: true for files whose folder or name has the word “loop” in it.
Downloads
Section titled “Downloads”Optional, per sound — a free sample, the .mid of a MIDI preview:
{ url: '/previews/kick-01.mp3', title: 'Kick 01', download: '/free/kick-01.wav' }Rows with a download get a download button at the end; rows without carry nothing. It is a plain <a download> — gating it (an email, a login) is the site’s job.
Which sounds get played (analytics)
Section titled “Which sounds get played (analytics)”The list plays through a regular WaveformPlayer, so @arraypress/waveform-tracker tracks it with no extra code — each event carries that sound’s url and title:
import WaveformTracker from '@arraypress/waveform-tracker';
WaveformTracker.init({ endpoint: '/api/listens', events: { play: 3, listen: 15 } });The engine is built as soon as the list is ready — before any play, with no audio loaded — so the tracker (and anything else that hooks players on waveformplayer:ready) is attached before the first sound plays. For list-level events (searches, filters, which sounds were shown) listen for waveformsounds:filter.
Playing alongside other players
Section titled “Playing alongside other players”The engine has singlePlay on, so starting a sound pauses any other WaveformPlayer on the page, and the list also pauses itself whenever any other player starts — including a WaveformBar’s, which doesn’t use singlePlay. The hand-off works between players of the same class, so load the player once: if a page ends up with two copies (an IIFE <script> and a bundled import), the second replaces the global and the two halves can no longer pause each other. The Astro wrapper takes care of this for you; with the others, import @arraypress/waveform-player once, or pass the class you already have as playerClass.
The engine also brings the player’s own machinery: seeking on hosts that ignore byte ranges (see Hosting the audio), error handling, and the Media Session card on the lock screen. A sound that fails to load is struck through (.is-error) and reported through onError / waveformsounds:error.
Server rendering
Section titled “Server rendering”@arraypress/waveform-sounds/render writes the list’s markup as an HTML string — the toolbar, the chips and the rows the list starts with — without touching window or document. Put it inside a [data-waveform-sounds] element and the runtime adopts it instead of rebuilding it, so the list is there, readable and crawlable, before any script runs:
import { renderSounds } from '@arraypress/waveform-sounds/render';
const html = `<div data-waveform-sounds class="waveform-sounds waveform-sounds--inline" data-player="inline">${renderSounds(sounds, options)}</div>`;What’s in it (2.2.0+):
- The first page of rows — or, with
pageSize: 0, the first 50 — in the starting order (the first ofsorts). The runtime renders the rest as they’re revealed. - Every sound, once, as JSON: one
<script type="application/json" data-ws-sounds>at the end. That’s where the runtime reads the sounds from. A row carries onlydata-ws-index(its sound’s position in that array) — no longerdata-url,data-title,data-peaksand the rest — so read a sound from the instance (list.sounds[Number(row.dataset.wsIndex)], or thesoundin an event), not from a row’s attributes. - One icon sprite, first: a hidden
<svg class="ws-sprite" data-ws-sprite="<idPrefix>">with a<symbol>per icon the list uses; each icon is<svg class="ws-icon …"><use href="#<idPrefix>-i-<name>"/></svg>. The classes are as before, so CSS on.ws-icon-playstill applies.
1000 sounds with paging off went from 1.37 MB of markup to 337 KB. Markup rendered by 2.0 / 2.1 (every row, each sound in its data-*) is still adopted.
renderSoundsElement(sounds, options, className) writes that wrapper too. Two things to keep in step:
- The runtime reads its options from the element, not from the markup. Pass the same options to the renderer and to the runtime — as
data-*attributes on the container or as constructor options. ApageSizethe runtime doesn’t know about, say, re-pages the rows to the default 50.renderSoundsElementtakes care of it: since 2.1.0 it writes adata-*attribute for every render option you set (data-page-size="20",data-filters="",data-strings='…'), so the runtime adopting it keeps them. With onlyplayerset (or nothing), the element is as before. (2.0 wrotedata-playeronly.) A wrapper handing its props to the renderer can pick the markup-shaping ones withpickRenderOptions(). idPrefix. The dropdowns’ element ids default to the container’sid, else a hash of the sounds — the same on the server and in the browser. Two lists of the same sounds on one page need anidoridPrefixeach.
Or let the <waveform-sounds> element adopt it: put the renderSounds() output inside the tag.
The framework wrappers — Astro, React, Svelte, Vue — do all of this for you whenever you give them sounds.
urlState is runtime-only: the server renders the unfiltered list and the runtime applies the address once it loads. Set --ws-surface for a server-rendered list, so its first paint is right before the runtime measures the page.
Mobile
Section titled “Mobile”- Narrow lists (560px wide or less — a container query, so a list in a sidebar counts too) lay each row out as three lines beside the play button: the full title, then
Bass · 128 · Fm · 0:08, then the waveform. A title is never squeezed by the columns. - Touch targets are 44px on coarse pointers, and the text inputs are 16px so iOS doesn’t zoom into them.
- Scrolling isn’t seeking. A finger that lands on a waveform still scrolls the page; touch seeks on the tap, while mouse and pen seek on press, like every scrubber.
- With
prefers-reduced-motion, the row and button transitions are off.