Patches

A patch is a JSON file that maps names to sound definitions. Ship them as static files, load them at runtime, or define them inline. Think of a patch as a sound palette for your app.

If you'd rather install patches from a registry, a GitHub repo, or a local path instead of hand-writing them, see the CLI.

Format

{
  "name": "minimal",
  "author": "web-kits",
  "version": "1.0.0",
  "description": "Clean UI sounds",
  "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
        }
      ]
    }
  }
}

Load from a URL

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

const patch = await loadPatch("/patches/minimal.json");
const voice = patch.play("tap");

Define inline

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

const patch = definePatch({
  name: "my-patch",
  sounds: {
    beep: {
      source: { type: "sine", frequency: 880 },
      envelope: { decay: 0.1 },
      gain: 0.3,
    },
  },
});

patch.play("beep");

Patch instance

Member	Type	Description
`play(name)`	`VoiceHandle`	Play a sound by name
`get(name)`	`SoundDefinition \| undefined`	Get the raw definition
`sounds`	`string[]`	All sound names
`ready`	`boolean`	Whether loaded
`toJSON()`	`SoundPatch`	Serialize back to JSON

JSON Schema

@web-kits/audio ships a JSON Schema for patches. Add it to your patch files to get autocomplete, inline validation, and error highlighting in VS Code, Cursor, and other editors.

Add a $schema property at the top of your patch JSON:

{
  "$schema": "https://unpkg.com/@web-kits/audio/schemas/patch.schema.json",
  "name": "my-patch",
  "sounds": {
    "tap": {
      "source": { "type": "sine", "frequency": 440 },
      "envelope": { "decay": 0.05 },
      "gain": 0.3
    }
  }
}

Local path

If you're working in a monorepo and want to reference the schema locally:

{
  "$schema": "../../../packages/audio/schemas/patch.schema.json"
}

SoundPatch type

The schema validates against the SoundPatch TypeScript type:

type SoundPatch = {
  $schema?: string;
  name: string;
  author?: string;
  version?: string;
  description?: string;
  tags?: string[];
  sounds: Record<string, SoundDefinition>;
};