Sound Engine

SoundProvider + SynthBackend. Sound tokens are serializable synth recipes (dry, short, hardware) rendered by a zero-dep WebAudio synth. Lazy AudioContext, persisted mute, per-play jitter, blur guard, reduced-motion coupling. On a phone, the tokens that mark a choice, a completion, a warning or an error also buzz.

Feel Dry, short clicks and chirps from a device — never notes from an instrument.

muted

Recipes are data, synthesised on a WebAudio graph — no audio files ship. Tune them by ear on the audition bench.

Or let the agent fetch it: get_component("sound") on the Echo MCP server.

Installation

npm install echo-ui-core

This one ships in the echo-ui-core package rather than being copied into your project — npx echo-ui-cli init installs it for you. Import it from echo-ui-core/sound.

At a glance

Weight: 2.1 KB (minified and gzipped; React not counted)
Sound: Nine tokens: tap, press, release, select, transition, notify, caution, error, celebrate.
Every play varies pitch by up to 3% and volume by up to 10%.
Silent until the person turns sound on (it starts muted; defaultMuted={false} starts with it), until the first pointer press, when muted, in a hidden or unfocused tab, and — by default — under reduced motion.
Haptics, on a phone that can vibrate: select a tick; notify and celebrate a success; caution a warning; error an error. A tap or a press never buzzes. They don't wait for sound to be on, stay still in a hidden tab, and haptics={false} turns them off.

Usage

tsx

import { SoundProvider } from "echo-ui-core/sound";

<SoundProvider>
  <App />
</SoundProvider>

Examples

Wrap the app

Provide sound once near the root. It starts muted until the person turns sound on; the AudioContext is created lazily on first pointerdown, and closed when the provider unmounts.

tsx

<SoundProvider>
  <App />
</SoundProvider>

Play a token

useSound().play resolves a token name to its recipe and jitters it.

tsx

const { play } = useSound();
<button onPointerDown={() => play("press")} onPointerUp={() => play("release")} />

A haptic on its own

play buzzes for the tokens that carry a haptic, even while sound is off; buzz plays one with no sound. Android browsers vibrate; iPhones can't, from a web page.

tsx

const { play, buzz } = useSound();
play("select"); // a tick in the hand, and the sound when it's on
buzz("success");

Mute toggle

Sound starts muted, so offer this somewhere people can find it. Their choice is persisted to localStorage and wins over defaultMuted.

tsx

const { muted, setMuted } = useSound();
<button onClick={() => setMuted(!muted)}>{muted ? "unmute" : "mute"}</button>

Motion & sound

Sound: Nine tokens: tap, press, release, select, transition, notify, caution, error, celebrate.
Sound: Every play varies pitch by up to 3% and volume by up to 10%.
Sound: Silent until the person turns sound on (it starts muted; defaultMuted={false} starts with it), until the first pointer press, when muted, in a hidden or unfocused tab, and — by default — under reduced motion.
Sound: Haptics, on a phone that can vibrate: select a tick; notify and celebrate a success; caution a warning; error an error. A tap or a press never buzzes. They don't wait for sound to be on, stay still in a hidden tab, and haptics={false} turns them off.

Props

Sound Engine props
Prop	Type	Default
`backend`A SoundBackend to render recipes with. Defaults to the zero-dependency WebAudio SynthBackend; swap it to route sound elsewhere or silence it in tests.	`SoundBackend`
`masterGain`Conservative master gain, scales every recipe.	`number`	`0.5`
`muteOnReducedMotion`Silence sound when the OS requests reduced motion.	`boolean`	`true`
`defaultMuted`Muted until the person turns sound on, for anyone who hasn't chosen yet; a stored choice always wins. Pass false where sound is the point from the first press.	`boolean`	`true`
`haptics`Buzz a phone for the sounds that carry a haptic (a choice changing, a completion, a warning, an error), whether or not sound is on. A device that can't vibrate ignores it; iPhones can't, from a web page.	`boolean`	`true`

Anti-patterns

Never create an AudioContext at module scope — autoplay policy blocks it and it breaks SSR.
Do not add reverb or long tails; recipes stay dry and short (a device, not an instrument).
Do not ship audio-file assets as the default sound path — synth recipes are the default backend.

Changelog

v0.3.0 · 2026-10-12 · ChangedEvery item needs echo-ui-core 0.3.0 (all components). The drawn device, readability past AA and the design tests live in core, and the components that use them are built against it, so each item now declares echo-ui-core >=0.3.0 <0.4.0. Update core with the items: npm install echo-ui-core@^0.3.0 (or your package manager's), then npx echo-ui-cli update. An item whose files didn't change is the same code under a new version; the 0.2.0 files stay published.
v0.2.0 · 2026-10-04 · ChangedComments only, no behaviour change. Comments in the component source used to cite documents, milestones and ticket numbers from Echo's own planning, none of which exist in your project. The citations are gone and the sentences around them stay. Where a comment was only a citation, it now says what it meant. Three development warnings (HardwareButton's engraved/caption checks and StatusDot's missing-label check) also dropped the ticket code at the end of the message. echo-ui diff will show changes in most items; none of them are to code.
v0.2.0 · 2026-10-04 · ChangedAn item's version is now a function of declared data, not of how the changelog is formatted. The version an item ships under is published once and never rewritten, and it used to be inferred from prose: a regex for a bolded "Breaking" run across the whole unreleased section, and attribution by "does a bullet mention this name in backticks". One breaking entry therefore moved every item that changed that cycle, and an entry explaining that "Menu and Sheet are unchanged here" filed itself as a change to Menu and Sheet — which it really had.
v0.2.0 · 2026-10-04 · ChangedThe agent brief says Echo has not shipped. llms.txt and the MCP server's instructions led with npx echo-ui-cli init, and that name on npm is a reserved stub with no executable — so a model following the brief wrote an install step that fails with npx's own error. The brief now opens with the caveat, and the docs carry it on every surface that shows a command. One switch (CLI_RELEASED) silences all of them at launch, and a test refuses to let one move without the others. Affects all components only in what the brief says about installing them; no item's props, CSS or rendered semantics change.
v0.2.0 · 2026-10-04 · ChangedEcho's home is echo-ui.com. The registry, the docs and the packages all move to it from echo.nawwara.studio. Nothing was published under the old host, so no echo.json anywhere points at it and there is nothing to migrate — this is the last release where that is true.
v0.2.0 · 2026-10-04 · ChangedWeights, line heights, letter-spacing, z-index, border widths and icon sizes come from the theme scales in all components, with the old value as a fallback, so components keep working with echo-ui-core@0.0.1. Strays moved to the nearest step: most by under a pixel; HardwareButton icons are 14/16/20px (were 15/17/19).
v0.2.0 · 2026-10-04 · FixedContent now reflows into a 320px screen (400% zoom) and survives a doubled browser text size (WCAG 1.4.10, 1.4.4), across all components. Select's 180px floor, NumberField's readout, Segmented and Steps as flex items, EmptyState's grid columns, and Avatar's fixed-pixel disc all gave way; Panel counts its padding inside a width you set (box-sizing: border-box), so a <Panel style={{ width: 220 }}> is now 220px wide overall rather than 260px.

Preview