@web-kits/audio

Declarative audio synthesis for the web. Describe sounds as plain objects, play them with one function call.

Install

npm install @web-kits/audio

Usage

Define and play a sound

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

const pop = defineSound({
  source: { type: "sine", frequency: { start: 1200, end: 300 } },
  envelope: { attack: 0.001, decay: 0.06, sustain: 0, release: 0.03 },
  gain: 0.3,
});

await ensureReady();
pop();

Shorthand helpers

import { sine, noise } from "@web-kits/audio";

const beep = sine(440, 0.1);
const click = noise("white", 0.02);

beep();
click();

Sound patches (React)

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

function App() {
  const patch = usePatch("/patches/core.json");

  return (
    <button onClick={() => patch.play("click")} disabled={!patch.ready}>
      Click me
    </button>
  );
}

Sound patches (vanilla)

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

const patch = await loadPatch("/patches/core.json");
patch.play("click");

CLI

# Browse and install patches from the registry
npx @web-kits/audio add

# Install patches from a GitHub repo
npx @web-kits/audio add user/repo

# Create a new sound patch
npx @web-kits/audio init

# List installed patches
npx @web-kits/audio list

# Remove installed patches
npx @web-kits/audio remove

Patch authoring

Create a patch JSON file with npx @web-kits/audio init, then add sound definitions to the sounds object:

{
  "$schema": "node_modules/@web-kits/audio/schemas/patch.schema.json",
  "name": "my-patch",
  "sounds": {
    "click": {
      "source": { "type": "noise", "color": "white" },
      "filter": { "type": "bandpass", "frequency": 2000 },
      "envelope": { "decay": 0.05 }
    }
  }
}

Push it to a GitHub repo. Others can install it with:

npx @web-kits/audio add your-username/your-repo

API

| Export | Description | |--------|-------------| | defineSound(def) | Create a reusable play function from a sound definition | | ensureReady() | Initialize the audio context (call before first play) | | sine(freq, decay) | Shorthand for sine oscillator | | triangle(freq, decay) | Shorthand for triangle oscillator | | square(freq, decay) | Shorthand for square oscillator | | sawtooth(freq, decay) | Shorthand for sawtooth oscillator | | noise(color, decay) | Shorthand for noise generator | | loadPatch(url) | Load a sound patch from a URL | | definePatch(json) | Create a patch from a JSON object | | usePatch(url) | React hook for loading and playing patches |

Documentation

Full docs at audio.raphaelsalaja.com.

License

MIT