Waveform Sounds for Astro

Typed Astro component for @arraypress/waveform-sounds. A searchable, filterable list of sound previews — server-rendered, then brought to life — with a mini waveform per row and one shared audio engine.

Documentation · npm

Install

npm install @arraypress/waveform-sounds-astro @arraypress/waveform-sounds @arraypress/waveform-player

Import the two stylesheets once, in your layout. The component does not inject CSS (none of the family's wrappers do):

---
import '@arraypress/waveform-player/styles.css';
import '@arraypress/waveform-sounds/styles.css';
---

The JavaScript is handled for you: the component ships a bundled client script that loads the sounds runtime, and the player too unless the page already has one (see below).

Usage

From an array — rendered on the server

---
import WaveformSounds from '@arraypress/waveform-sounds-astro';
---
<WaveformSounds
  sounds={[
    { url: '/previews/kick-01.mp3', title: 'Kick 01', type: 'Drums', bpm: 128, key: 'F minor', duration: 2.4 },
    { url: '/previews/bass-04.mp3', title: 'Bass Loop 04', type: 'Bass', bpm: 128, key: 'Fmin', peaks: 'a1b2c3…' },
  ]}
  pageSize={100}
  columns={['type', 'bpm', 'key']}
/>

The whole list — toolbar, filter chips, every row — is in the HTML. The browser runtime adopts that markup instead of rebuilding it, so the list is readable and crawlable before any script runs. Give rows peaks (what waveform-gen --manifest writes) and the row waveforms draw without decoding any audio. A sound with download: '/files/kick-01.wav' gets a download button on its row (a plain <a download> — gating is up to your site).

From a manifest — fetched in the browser

<WaveformSounds manifest="/sounds.json" player="strip" />

With only manifest (and no sounds), the component renders an empty container with data-manifest, and the runtime fetches and renders the list. sounds={[]} counts as "given" — it renders an empty list, as the core does.

Generate a manifest from a folder of previews (--base-url is the folder's public URL; without it every URL is relative to the site root, /kick.mp3):

npx @arraypress/waveform-gen ./public/previews/*.mp3 --manifest ./public/sounds.json --base-url /previews/

To server-render a manifest instead, read it at build time and pass its sounds array.

Props

Every prop is optional. An omitted prop emits nothing, so the core's default applies. Types come straight from the core's WaveformSoundsOptions.

| Prop | Type | Default | Notes | |---|---|---|---| | sounds | SoundInput[] | — | Rendered on the server. | | manifest | string | — | URL, fetched in the browser when there are no sounds. | | player | 'inline' \| 'strip' | 'inline' | Mini waveform per row, or one docked player. | | search | boolean | true | Search box. | | filters | ('type' \| 'key' \| 'bpm')[] | all three | [] = no filter controls. Drop one from filters, columns and sorts to remove it everywhere. | | sorts | SoundsSort[] | all five | Orders the Sort menu offers; the first is the start order. [] = no menu. | | showCount | boolean | true | The "12 of 300 sounds" line. | | menuSearch | number | 8 | Type / key / sort dropdowns with more options than this get a search field. | | urlState | boolean \| string | false | Keep filters + sort in the address (?q=…&type=…), shareable and refresh-proof. A string prefixes the parameter names, for several lists on a page. | | idPrefix | string | the id, else a hash of the sounds | Prefix for the dropdowns' element ids. Two lists of the same sounds on one page need an id or idPrefix each. | | loopToggle | boolean | true | Loop button. | | pageSize | number | 50 | Rows before "Show more"; 0 = all. | | maxTypeChips | number | 10 | More types than this become a menu. | | columns | ('type' \| 'bpm' \| 'key' \| 'duration')[] | all four | Order is kept. | | waveformStyle | 'mirror' \| 'bars' | 'mirror' | Row waveform. | | waveformColor | string | CSS --ws-wave-color | Default derives from currentColor. | | progressColor | string | CSS --ws-progress-color | Default derives from currentColor. | | barWidth | number | 2 | Row bar width, CSS px. | | barGap | number | 1 | Gap between row bars, CSS px. | | loop | boolean | false | Start with Loop on. | | autoAdvance | boolean | false | Play the next visible sound at the end. | | arrowAudition | boolean | true | ↑/↓ play the next row while playing. | | strings | Partial<WaveformSoundsStrings> | English | UI words; emitted as JSON. | | playerOptions | object | — | Options for the engine WaveformPlayer; emitted as JSON (functions are dropped). | | id | string | — | Container id. | | class | string | — | Added to waveform-sounds waveform-sounds--<player>. |

Not available as props: the on* callbacks (see Events) and playerClass (the page's window.WaveformPlayer is used — see below).

Theming

No accent is needed: like the rest of the family the list is colour-agnostic. Everything derives from currentColor, so it fits light and dark pages as is, and the "on" states (selected chip, playing row) invert. Opt into a brand colour with --ws-accent / --ws-on-accent if you want one.

Set --ws-surface to your page background. The runtime detects it, but a server-rendered list paints before any script runs, so the first paint (dropdown and button fills) uses the CSS value:

.waveform-sounds { --ws-surface: var(--color-bg); }

Other properties: --ws-wave-color, --ws-progress-color, --ws-border, --ws-radius, --ws-control-radius, … (see the core's README).

Events

Callbacks can't cross server rendering. Listen for the core's bubbling DOM events instead — on the element, or on document:

<WaveformSounds id="pack" manifest="/sounds.json" />

<script>
  document.addEventListener('waveformsounds:play', (e) => {
    console.log('playing', e.detail.sound.title);
  });
</script>

| Event | detail | |---|---| | waveformsounds:ready | { sounds, instance } | | waveformsounds:play / :pause / :end | { sound, index, instance } | | waveformsounds:filter | { visible, total, filter, sort, instance } | | waveformsounds:error | { error, sound?, index?, instance } |

For the imperative API, window.WaveformSounds.getInstance('#pack') returns the instance (play(), setFilter(), setSort(), …). It is created by the client script, so call it from an event handler or after waveformsounds:ready.

Content Security Policy

The client script is a processed Astro <script>: one bundled module, emitted as an external file (/_astro/…) and identical on every page — no is:inline, no define:vars. Everything per-instance travels in data-* attributes. A strict hash-based CSP needs no extra hashes for this component.

View Transitions (<ClientRouter />)

Works with and without Astro's router. The script initialises on load, again on every astro:page-load, and on astro:after-swap destroys the instances whose element left the page (stopping their audio). A list inside a transition:persist element is carried over and keeps playing.

Using it next to other players (WaveformBar, <WaveformPlayer>, …)

The list plays through a WaveformPlayer, and singlePlay (one sound at a time across the page) only works between players of the same class. So the client script never replaces a player the page already has: it waits for the page's own scripts to run (DOMContentLoaded) and uses window.WaveformPlayer if it's there — a persistent WaveformBar's, or one loaded by a <script> tag. Only when there is none does it load the bundled @arraypress/waveform-player (a separate chunk, by dynamic import).

A player your code loads LATER than that (from its own dynamic import) can't be detected; load it from a static <script>/import instead.

License

MIT © ArrayPress