@web-kits/audio

Declarative audio synthesis for the web. Describe a sound as plain data, play it with one call. By Raphael Salaja. Source: audio.raphaelsalaja.com, 2026-04-22

The Pitch

"The web has been quiet for a while." Sound is the forgotten dimension of web interaction - CSS has tokens, motion has springs, layout has grid, but audio has always required hand-rolled Web Audio API graphs. @web-kits/audio treats sound like a declarative UI primitive: a sound is a plain object, a patch is a JSON palette, a play is a zero-allocation function call.

Mental model: shadcn for audio. JSON-schema-validated patches, a registry + CLI, React hooks, prefers-reduced-motion respected by default.

Core API

import { defineSound } from "@web-kits/audio";

const pop = defineSound({
  source: { type: "sine", frequency: { start: 400, end: 150 } },
  envelope: { decay: 0.05 },
  gain: 0.35,
});

pop(); // play it

defineSound compiles the definition once and returns a zero-allocation play function. Browsers block audio until a user gesture - call ensureReady() inside a click/pointer handler before the first play.

React Integration

import { SoundProvider, useSound } from "@web-kits/audio/react";

<SoundProvider enabled={enabled} volume={volume} onEnabledChange={setEnabled} onVolumeChange={setVolume}>
  {children}
</SoundProvider>

• SoundProvider owns global enabled/volume state; auto-disables on prefers-reduced-motion: reduce.
• useSound(def) returns a stable play function; result is a VoiceHandle (stoppable) or undefined when sound is disabled.
• usePatch loads a patch by URL or inline definition.

Patches - Sound Tokens

A patch is a JSON file that maps names to sound definitions. Think design tokens, but for sound. Ship them as static files, load at runtime, or define inline. Each patch declares name, author, version, description, tags, and a sounds map.

{
  "$schema": "https://unpkg.com/@web-kits/audio/schemas/patch.schema.json",
  "name": "minimal",
  "sounds": {
    "tap": {
      "source": { "type": "sine", "frequency": { "start": 600, "end": 400 } },
      "envelope": { "decay": 0.04 },
      "gain": 0.3
    },
    "success": {
      "layers": [
        { "source": { "type": "triangle", "frequency": 523 }, "envelope": { "attack": 0.01, "decay": 0.15 }, "gain": 0.25 },
        { "source": { "type": "triangle", "frequency": 659 }, "envelope": { "attack": 0.01, "decay": 0.15 }, "gain": 0.25, "delay": 0.08 }
      ]
    }
  }
}

Ships a JSON Schema (packages/audio/schemas/patch.schema.json) so VS Code / Cursor get autocomplete and inline validation on patch files. SoundPatch is also exported as a TypeScript type.

Primitives

Distribution

• CLI - install patches from a registry, a GitHub repo, or a local path (shadcn-style).
• Registry - hosted patches discoverable by name.
• Bundle-your-own - ship patches as static JSON alongside your app.

Launch Thread Details

The reviewed launch thread adds two operational pieces that matter for Kevin's stack:

• The CLI can browse community sound packs, install a pack with one command, and scaffold a new pack. That makes patches closer to a source-code registry than a loose asset folder.
• Raphael also described an agent-facing sound-design skill: describe the desired sound, optionally provide an audio reference, and receive a typed patch ready to drop into the app. Treat that as a candidate workflow for Media Generation Skills or a future web-kits-audio skill after Kevin uses it repeatedly.

The downloaded local thumbnail is visually low-information, essentially a blank video thumb, so the durable evidence is the tweet, video URL, docs, npm package, and GitHub repository rather than the image itself. Source: local X media artifact, reviewed 2026-06-30

Version Snapshot

This is not a production dependency pin for any Kevin project yet. It is a versioned tool snapshot so future agents can tell whether the audio stack changed before recommending it.

Why This Matters

• Auditory micro-interactions. Taps, toggles, success/error, drag-release, AI-response-complete - all currently either missing from the web or hand-rolled per app.
• Declarative matches the rest of the stack. Motion, layout, and color all became data-first (Framer Motion, Tailwind, OKLCH). Audio was the straggler.
• Accessibility by default. prefers-reduced-motion integration means sound effects don't ship to users who've opted out of motion - a surprisingly-common default.
• Patches are design-engineering artifacts. A sound palette is shippable, versioned, and shareable the same way a color palette is. The CLI + registry makes this concrete.

Fit With Existing Wiki Tools

• Userinterface.wiki - Raphael's living manual for interface craft. The "Generating Sounds with AI" and "Sounds on The Web" articles there predate this library and explain the thesis: sound is the forgotten sense in web design.
• Media Generation Skills - personal skill to generate custom MP3 SFX via ElevenLabs API; wire outputs into @web-kits/audio patches or static assets.
• Design Engineering Resources - fits under Tools alongside DialKit (UI value tuning), Sonner (toast feedback), Calligraph (text transitions). Complements soundcn (curated sound files) as the engine to soundcn's assets.
• Interface Micro-Polish / Frontend and Design Skills - sound is the next axis after typography, radius, shadows, and motion.
• Motion 3D Playbook - same declarative philosophy as GSAP timelines and R3F scenes, but for the ear.

Install

npm i @web-kits/audio
# or pnpm / yarn / bun

Docs: audio.raphaelsalaja.com

---

Timeline

• 2026-06-30 | Deep-reviewed the X bookmark artifacts, docs, npm package, and GitHub repository. Added the tweet/video artifact, CLI/agent-skill notes, and version snapshot (@web-kits/audio@0.1.0, MIT, Git tag @web-kits/audio@0.1.0). Source: X/@raphaelsalaja, 2026-04-04
• 2026-06-12 | Cross-linked Media Generation Skills skill for AI-generated MP3 assets upstream of declarative playback. Source: User, 2026-06-12
• 2026-04-22 | Kevin surfaced the launch post ("the web has been quiet for a while - declarative audio for the web, describe a sound as plain data, play it with one call"). Created this page. Source: User, 2026-04-22