Sounds
The Astro, React, Svelte and Vue components are the /sounds sub-path of each framework package and version with it — see Framework packages. Before 2.0 they were separate wrappers — see Framework wrappers (1.x).
[2.2.0] — 2026-11-22
Section titled “[2.2.0] — 2026-11-22”A lighter, quieter list: rows exist only while shown, icons are defined once, a screen reader hears one seek slider and whole sentences, and enharmonic keys are one key. The server-rendered markup changes (see below): nobody depends on 2.x markup yet, so this ships in a minor. Pass the same render options to the server and the runtime as before; markup rendered by 2.0 / 2.1 is still adopted.
Changed (markup)
Section titled “Changed (markup)”renderSoundsrenders only the rows the list starts with — the first page, or withpageSize: 0the first 50 — in its starting order (the first sort offered), and carries EVERY sound once as JSON (<script type="application/json" data-ws-sounds>). Rows past the page are no longer in the markup ashiddenrows, and a row no longer carries its sound asdata-url/data-title/data-type/data-bpm/data-key/data-duration/data-tags/data-peaks/data-waveform/data-download/data-loop/data-ws-id: onlydata-ws-index. 1000 sounds, paging off: 1.37 MB → 337 KB of markup (142 → 91 KB gzipped); 300 sounds, default paging: 429 → 147 KB.- Icons are one sprite per list: a hidden
<svg class="ws-sprite" data-ws-sprite="<idPrefix>">with a<symbol id="<idPrefix>-i-<name>">for each icon the list uses, first in the markup; every icon is<svg class="ws-icon …"><use href="#…"/></svg>(the classes are unchanged, so CSS that styles.ws-icon-playstill does). StillcurrentColor, still drawn under forced colours. - A row reads as a sentence: its cells are
aria-hidden, and a visually hidden<span class="ws-sr" id="<idPrefix>-d<index>">says “Bass loops, 130 BPM, key B minor, 0:07, Loop” (was “Bass loops 130 Bm 0:07”); the play button isaria-describedbyit. The loop mark isaria-hidden(its “Loop” is in the sentence). - No waveform is a slider in the markup:
.ws-waveisaria-hidden="true"with no role or tabindex; the runtime makes the current row’s the seek slider (and only that one). - The key menu’s options carry
data-alt(a merged key’s other spellings) where there are any. - The golden test now holds 2.2.0’s markup (
test/fixtures/render-2.2.0.json, regenerated deliberately byscripts/write-golden.mjs); the framework wrappers’ SSR / hydration fixtures need regenerating too.
- Enharmonic keys are merged, by default (
mergeEnharmonicKeys,data-merge-enharmonic-keys, a render option): A#m and Bbm, C# and Db are one key-menu entry, a filter on either spelling finds both, the search finds either, and?key=accepts either. The entry shows the spelling the pack uses most; a tie goes to the conventional spelling — the key signature with the fewest accidentals (Db, Eb, F#, Ab, Bb, B major; C#m, Ebm, F#m, G#m, Bbm minor; F# and Ebm for the six-and-six ties). Rows show their key as written.falsekeeps spellings apart.facets()returnskeyAliases;facets,matchesandreadUrlStatetake{mergeEnharmonicKeys}. - Rows are rendered as they are revealed. With paging, the page; with
paging off, 50 at a time as the list scrolls toward its end. Rows that
stop being shown (filtered, sorted past the page) leave the DOM, kept
with their drawing for when they return. Filtering, sorting, search, the
address, ↑/↓/Home/End,
next(), auto-advance and the “Playing…” status all work across rows not yet rendered (↓ or End renders up to the row it lands on). 1000 sounds, paging off, Chromium: 17,001 → 1,182 DOM elements; load’s longest task 287 → 0 ms (SSR: 289 → 0); clear filters 82 → 16 ms; sort by name 163 → 35 ms. 300 sounds: 5,325 → 1,182 elements, nothing slower beyond noise (a type filter with paging off 7 → 13 ms; clear 31 → 20, sort 50 → 17). - Strings
rowBpm,rowKey,rowDuration,keyMajor,keyMinor,noteSharp,noteFlat,listSeparator(the rows’ read-out).
- A screen reader met one slider per row (“Seek …” ×300, each focusable by a click); now only the current sound’s waveform is a slider. ←/→ and Home/End on it are unchanged.
- Row waveforms draw any peak count well: with more bars than peaks
(64 peaks across a wide row) each peak was repeated into flat steps; now
the bars are interpolated. 64, 128 and
wp1:peaks of any length draw the same shape. - A sound that failed to load stays marked when its row is rendered later.
- Re-sorting keeps focus on the focused row (moving it used to drop focus).
[2.1.0] — 2026-11-21
Section titled “[2.1.0] — 2026-11-21”Fixes from an audit of 2.0.0 in Chromium, Firefox and WebKit (and Chrome
115–133 / Firefox 115–128 binaries), the <waveform-sounds> element, and
the family’s event and server-rendering surface. Non-breaking: for packs
with whole-number BPMs, renderSounds output is byte-identical to 2.0.0
(a golden test holds it so).
- Switching sounds while one plays is reported. ↓ audition,
play(i),next()and auto-advance emitted nowaveformsounds:play/onPlayfor the new sound (and nopausefor the outgoing one), and the live region kept the first title: the browser swaps the source without apause, so the playing flag never flipped. Events now follow the sound. - A sound that fails is no longer left “playing”. A 404, an
undecodable file or a dropped connection set
is-errorbut leftplayingtrue and the row’s button reading “Pause”. Now the state settles, the live region announces it (new stringplayError), and the row’s mark clears once it loads. - A list that can’t be built says so. A manifest that 404s or isn’t
JSON left an empty container; one that isn’t a manifest rendered “No
sounds match.” with a Clear button. Now
loadErrorshows where the list would be (role="alert"; a site’s own fallback content in the container stays), and an empty pack showsnoSoundswith nothing to clear. - Pressed controls are readable before the script measures the page.
Chrome 119–130 (relative colour, but not from
currentColor) and Firefox 128–132 (currentColorresolved as black) painted a pressed chip, segment or Loop toggle in text colour on a text-colour fill on dark pages (1.0–1.2:1) until the runtime measured the surface. There, until it has, a pressed control is a tint with text-colour ink (9:1). Current engines are unchanged. - The surface is re-measured when a theme flips on any ancestor
(class, style or
data-themeon a section, a card, a framework’s root; not only<html>/<body>), and on a forced-colours switch. - The BPM panel fits on phones. At phone width it hung off the screen’s edge; in the narrow layout the menus now open from the controls row and never exceed it.
- Fractional BPMs. The slider steps by 1, so a pack whose fastest loop
is 128.5 BPM had a top handle stuck at 128 that filtered that loop out.
The slider’s ends are now the pack’s range rounded outward (floor /
ceil). The rendered BPM slider’s
min/max/ ends change for packs with fractional BPMs only (e.g. 128.5 → 129). - The address.
?bpm=with the ends reversed is put in order, limits outside the pack are ignored (a stale link no longer empties the list), and decimals are read — so it round-trips whatsetFilterwrites. - Focus never drops to
<body>: after “Clear filters” it goes to the search box, after the last “Show more” to the first row it revealed, and out of a row that a filter hides to the first row shown. parseDuration('1:-30')isnull(was 30).
Changed
Section titled “Changed”- The list is one Tab stop (roving tabindex, set at runtime; the markup is unchanged): the focused row’s play button — with its download link, and its seek slider when it is the current sound — and ↑/↓ between rows, as before.
- Resize and theme repaints draw only the rows on screen; the rest are redrawn when they scroll back in. 1000 rows: ~410 → 5ms per resize step in Chromium, ~1.9s → 25ms in WebKit, ~650 → 10ms in Firefox.
- The strip’s cue fetches nothing. The docked player’s first sound is
cued with
preload: 'none'(title, length and peaks come from the data), and the next sound played gets the engine’s ownpreloadback. 300 sounds, 8 filter changes, no play: 0 audio requests (was 6 files, ~2MB, in Firefox and WebKit). - Forced colours (Windows High Contrast): pressed states and the playing row’s button use Highlight / HighlightText (their icons were invisible), the BPM track is drawn, focus is an outline rather than a box-shadow, and the row waveforms draw in CanvasText / Highlight.
- Focus and targets: the search field shows a 2px focus ring on its frame (and the menu search field one of its own); “Any BPM” is a 24×24 target.
waveformsounds:*events arecomposed(they leave a shadow root, like the core’s).renderSoundsElementwrites adata-*attribute for every render option you set (data-page-size="20",data-filters="",data-strings='…'), so the runtime adopting it keeps them (apageSizeof 20 was re-paged to 50). Its inner markup isrenderSounds’ as before, and with onlyplayer(or nothing) set the element is unchanged too.engineis typed as the core’sWaveformPlayer(wasunknown);SoundInput.loopaccepts the strings and numbers the runtime reads ('true','1',1, …).- Re-sorting is linear (was quadratic), and one filter pass serves each layout.
<waveform-sounds>, a light-DOM custom element modelled on the core’s<waveform-player>: everydata-*option as an attribute with or without the prefix (<waveform-sounds manifest="/sounds.json" page-size="20">), server markup inside it adopted as it is today, events bubbling from it,.soundsfor the instance; a move keeps it, attribute changes rebuild it. Registered by the default entry (behind the samedata-waveform-autoinit="false"opt-out);/no-autoinitexportsdefineWaveformSoundsElement(name)andWaveformSoundsElement.WaveformSounds.defineElement(name?)— the definer as a static, so a<script>page that opted out of auto-init can register the tag (as the core’sWaveformPlayer.defineElement()).destroy({restore: true})puts adopted server markup back exactly as it arrived, for frameworks that re-mount the same markup.destroy()is unchanged.- The instance is an
EventTarget:list.addEventListener('play', …)forready,play,pause,end,filteranderror, after the container’swaveformsounds:*event (WaveformSoundsInstanceEventMap). - The
waveformsounds:*event map is merged intoDocumentEventMapandWindowEventMapas well, sodocument.addEventListener(...)is typed. RENDER_OPTION_KEYSandpickRenderOptions(options)(from/renderand the main entry): the options that shape the server markup, for wrappers handing props torenderSounds.- The seek slider reads out its time (
aria-valuetext, “0:12 of 0:30”, stringseekValue), and Home / End on it seek to the start / end. decodePeaks— so manifests anddata-peaks— accepts the core’s compactwp1:peaks; the server markup still writes hex.- Strings
playError,loadError,noSounds,seekValue.
[2.0.0] — 2026-11-21
Section titled “[2.0.0] — 2026-11-21”Version 2.0.0 lines the package up with @arraypress/waveform-player 2.0,
which it now requires. The list itself works as in 0.3.1: options, markup,
classes, events and the server-rendered HTML are unchanged (renderSounds
output is byte-identical).
- A sound’s known length reaches the player. A sound with a
durationpasses it to the engine (the 2.0 core’sdurationoption), so the player shows the right total, places a seek and fills the Media Session scrubber before the audio’s metadata arrives. - A docked player’s download link matches the row. With
playerOptions: {showDownload: true}in thestriplayout, the player’s download link is the sound’sdownload, else its audio.
Changed
Section titled “Changed”- Requires
@arraypress/waveform-player2.0 (peer^2.0.0). - Written in TypeScript. The type declarations are generated from the
source into
types/instead of being written by hand. The rootindex.d.ts,no-autoinit.d.tsandrender.d.tsare gone; theexportsmap points each entry at its declarations (types/index.d.ts,types/entry.d.ts,types/render-entry.d.ts), and the option types live intypes/types.d.ts. Declaration maps ship, so Go to definition opens the TypeScript source. - Browser support is Chrome/Edge 111+, Firefox 114+ and Safari 16.4+ (all from early 2023), as for the core. The bundles are built for ES2022.
- The script-tag builds run in strict mode.
waveform-sounds.jsand.min.jsnow start with"use strict"; the ES module builds always ran strict, as every ES module does. playerOptionscan’t take looping from the list. The engine’sloopandshowLoopare always off: the player’s loop would stopended(stallingautoAdvance), and its toggle would loop one-shots behind the Loop toggle’s back.duration,downloadUrlanddownloadNameinplayerOptionsare ignored: they describe one track, and each sound brings its own.lazyhas no effect on the engine (it loads nothing until a sound plays);showVolume,volumeand the rest pass through.- Search uses
@arraypress/text2.3.1 (bundled). Accents still fold away (Caféfindscafe), but the marks that are part of a letter in scripts such as Devanagari are kept:हिन्दी बेसwas searched as the fragmentsह,नद,बस, and is now the two words it spells.
- Reduced motion covers every transition. The segmented control, the
download button and the menu chevron still animated with
prefers-reduced-motion: reduce. - Pressed controls are readable before the script runs where relative colour isn’t supported (Safari 16.4–17, Firefox before 128): the “on” ink falls back to the page surface instead of painting the text colour on a text-colour fill.
Removed
Section titled “Removed”- The CommonJS builds (
waveform-sounds.cjs,waveform-sounds-no-autoinit.cjs,waveform-sounds-render.cjs), therequireexport conditions and themodulefield.mainis the ES module build.require('@arraypress/waveform-sounds')(and/render,/no-autoinit) still works: Node 22.12+ loads the ES module throughrequire(), andenginesnow says>=22.12. - Vendor prefixes the browser floor doesn’t need (
-webkit-appearancebesideappearance) and the deprecatedclipon.ws-sr(clip-path: inset(50%)instead).
[0.3.1] — 2026-10-08
Section titled “[0.3.1] — 2026-10-08”- The strip’s docked player no longer starts empty. It showed a play
button, no waveform and
0:00 / 0:00, and its button did nothing. The first sound the list shows is now cued in it — title, waveform, length — without playing (metadata only, the browser default for any<audio>), and its button plays it. Its row isn’t marked until it plays,currentstaysnull,next()starts with it, and a filter change re-cues the first sound still shown until something plays. - The docked player stays in place. It was
position: sticky, so it slid along the bottom of the screen over the rows as the page scrolled. It’s static now;--ws-strip-position: stickybrings the old behaviour back for a long list. - Rows and the player agree on lengths. Rows rounded to the nearest
second and the player’s clock rounds down, so a 7.6s sound read
0:08in its row and0:07in the player. Rows round down too now.
[0.3.0] — 2026-10-07
Section titled “[0.3.0] — 2026-10-07”Changed
Section titled “Changed”- BPM is a menu with a two-handle range instead of two number fields.
The button reads
Any BPM, or120–128 BPMonce set; its panel holds a range across the pack’s own tempos (two native range inputs on one track: arrow keys, screen readers and touch work as they do on any slider), the live readout and anAny BPMreset. The label follows the drag; the list re-filters once it settles. A handle left at an end is no limit on that side, so a range nobody narrowed never hides the sounds without a BPM.?bpm=in the address andsetFilter({bpmMin, bpmMax})work as before. New strings:anyBpm,bpmRange. - On a list that marks loops, Loop starts on. Only loops repeat (as in
0.2.0), so loops repeat out of the box and one-shots still play once. The
loopoption now defaults tonull(follow the data);true/falsestill force it. A list that marks nothing starts with it off, as before.
Removed
Section titled “Removed”.ws-bpm-rangeand its number inputs (data-ws-bpm-min/-maxare now the range handles).
[0.2.0] — 2026-10-07
Section titled “[0.2.0] — 2026-10-07”- Loops and one-shots. A sound can be marked
loop: true; anything else is a one-shot. Marking loops does three things:- a small loop icon beside the name (with “Loop” for screen readers);
- an All / Loops / One-shots filter, offered only when the list has
both kinds (
filtersentry'loop', on by default; in the address as?loop=loop/?loop=one-shotwithurlState); - the Loop toggle repeats only loops. A one-shot always plays once. A list that marks no loops behaves exactly as before.
isLoop()andLOOP_FILTERSin the data module;facets()reportsloopsandoneShots; four new strings (loopFilter,loops,oneShots,isLoop).
Changed
Section titled “Changed”- The title cell wraps its text in
.ws-title-text(so a loop’s icon can sit after an ellipsised name). Styling.ws-titlestill works.
[0.1.3] — 2026-10-07
Section titled “[0.1.3] — 2026-10-07”- Sounds under a second show their length.
formatDurationrounded to whole seconds, so a 0.38s one-shot read0:00— which looks like a missing length, and one-shots (kicks, hats, single notes) are routinely that short. Under a second it now shows tenths:0.4s. - The
stripplayer matches a dark page. Its background fell back to the systemCanvascolour, which is white on a dark page that doesn’t declarecolor-scheme: dark— a white box under a dark list. It now falls back to--ws-surface(the measured page surface), as the dropdowns already did. - No stray
·on a narrow screen. The mobile meta line put a separator before a cell whenever any cell came first, even an empty one, so a sound with no key read· 0:08. It now follows only a cell with content.
[0.1.2] — 2026-10-07
Section titled “[0.1.2] — 2026-10-07”- The
striplayout keeps its docked styling. The engine was mounted on the.ws-engineslot itself, andWaveformPlayerresets its container’sclassName, sows-engine--stripwas wiped on the first play: no sticky position, border, padding,--ws-strip-bgor--ws-radius. The engine now mounts into a child of the slot ([data-ws-engine-mount], made at runtime, so server-rendered markup from 0.1.0/0.1.1 works unchanged) anddestroy()removes it. render.d.tsdeclaresescapeHtml, which/renderhas always exported.
[0.1.1] — 2026-10-06
Section titled “[0.1.1] — 2026-10-06”- The playing row’s progress is smooth. It was painted a whole bar at a time (a bar switched colour once the playhead passed its middle), so a short clip advanced in visible steps — an 8-second loop across ~120 bars moved ~15 times a second however often it was redrawn. The bars are now drawn twice, the second pass clipped at the exact playhead pixel: the played part grows through the middle of a bar. Measured in Chrome: the edge moves every ~1px (≈37 times a second on a 12-second clip at 60fps).
- Bar geometry is a pure, tested function (
barRects), and each pass is a singlefill()of aPath2Dinstead of onefillRectper bar.
[0.1.0] — 2026-10-06
Section titled “[0.1.0] — 2026-10-06”- First release: a searchable, filterable list of sounds for showcasing the previews inside a sample pack, preset bank or sound library.
- One
WaveformPlayer(self mode) is the audio engine for the whole list, so playback gets the player’s seeking (including hosts that ignore byte ranges), error handling, Media Session card andsinglePlayhand-off. - Two layouts:
inline(a mini waveform per row; the playing row fills and is click-to-seek) andstrip(plain rows, the engine docked below). - Search (every word, any order; a number matches the BPM), type chips (a
menu past
maxTypeChips), key menu, BPM range, sort, Loop toggle, paging. - Keyboard: ↑/↓ move and, while a sound plays, audition the next; ←/→ seek;
/focuses the search; ↓ from the search enters the list. - Peaks as an 8-bit hex string (two characters per bar).
@arraypress/waveform-sounds/render: a DOM-free renderer for server rendering; the runtime adopts its markup instead of rebuilding it.@arraypress/waveform-sounds/no-autoinit.- Dropdowns for type (past
maxTypeChips), key and sort: a button and a popup listbox, with a search field pastmenuSearch(8) options; ↑/↓, Enter, Esc, type to narrow (WAI-ARIA combobox/listbox). - Every control is optional:
search,filters,sorts(which orders, in order; the first is the starting order),loopToggle,showCount,columns. - Optional per-sound
downloadlink (a download button on that row only). urlState: the filters and sort live in the address (shareable, survive a refresh), optionally prefixed for several lists on a page.- The engine is built when the list is ready (no audio loaded), so
waveform-tracker and other
waveformplayer:readyhooks see the first play. - Colour-agnostic by default: the “on” states are inverted (text colour as
fill, page surface as ink). The surface is detected (
--ws-surface) and re-read on theme flips; set it yourself for the first server paint.