audiobits 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,28 @@
+# audiobits
+
+## 0.1.0
+
+### Minor Changes
+
+- faf1c04: Preserve recipe parameter names and live modes in TypeScript authoring, and add
+  five procedural presets: tactileClick, gentleRejection, glassNotification,
+  whoosh and powerUp. Mark shared delay experimental and simplify the quick start
+  while retaining explicit production lifecycle guidance.
+- 7db5e9f: Prepare the first three-sound core candidate: schema-1 oscillator/white-noise
+  recipes, seeded variation, play/live controls, bounded voices, buses and shared
+  delay, explicit caller-owned native interop, and gesture-driven lifecycle APIs.
+  Chromium is the initial browser gate. No registry release or deployment is implied.
+
+### Patch Changes
+
+- faf1c04: Preserve managed linear ramps, live retargeting and release fades when the browser
+  lacks AudioParam.cancelAndHoldAtTime. Track bus gain, mute and delay gates explicitly.
+
+## 0.1.0-rc.0
+
+### Minor Changes
+
+- Prepare the first three-sound core candidate: schema-1 oscillator/white-noise
+  recipes, seeded variation, play/live controls, bounded voices, buses and shared
+  delay, explicit caller-owned native interop, and gesture-driven lifecycle APIs.
+  Chromium is the initial browser gate. No registry release or deployment is implied.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 joacod
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,4 +1,331 @@
-# Temporary Holding Version
+# AudioBits
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
-If no other versions are published within 30 days, this package and version will be deleted.
+AudioBits **0.1.0** is prepared for stable publication but has not yet been published to npm. It includes confirmation, impact, thruster, tactile click, gentle rejection,
+glass notification, whoosh and power-up; schema-1 recipes; play/live controls; seeded variation; bounded
+voices; bus gain, mute and routing; native output taps; and explicit lifecycle APIs.
+Prerelease verification target: current Chromium. Other browsers and operating
+systems are unverified and deliberately deferred. Maintainer listening acceptance for the
+unchanged sound definitions is recorded separately. Nothing has been published,
+and the npm identifier remains `audiobits`.
+
+## Try locally
+
+Install the reviewed archive into your own private consumer with
+`npm install /path/to/audiobits-0.1.0.tgz`. This is a local file install,
+not an instruction to install an existing registry package. Use a browser
+bundler and call `play()` directly from a gesture handler. Surface rejection
+with `void play().catch(showError)` and retry from a fresh gesture.
+
+```ts
+import { createAudio } from "audiobits";
+import { confirmation } from "audiobits/recipes";
+
+const audio = createAudio();
+const sound = audio.sound(confirmation);
+export async function play() {
+  await audio.start();
+  sound.play();
+}
+export function stop() {
+  audio.stopAll({ tails: "cut" });
+}
+export async function dispose() {
+  await audio.dispose();
+}
+```
+
+Bind `play()` to a button click (`void play().catch(showError)`).
+
+## Production lifecycle
+
+For an SPA, invalidate pending activation when hiding or unmounting; suspend on
+hide and dispose on navigation. Returning requires a fresh Play gesture.
+
+```ts
+import { createAudio } from "audiobits";
+import { confirmation } from "audiobits/recipes";
+const audio = createAudio();
+const sound = audio.sound(confirmation);
+let request = 0;
+export async function play() {
+  const token = ++request;
+  await audio.start();
+  if (token === request && !document.hidden) sound.play({ seed: 42 });
+}
+export function stop() {
+  request++;
+  audio.stopAll({ tails: "cut" });
+}
+function hide() {
+  if (document.hidden) {
+    stop();
+    void audio.suspend().catch(console.error);
+  }
+}
+document.addEventListener("visibilitychange", hide);
+export async function dispose() {
+  stop();
+  document.removeEventListener("visibilitychange", hide);
+  await audio.dispose();
+}
+```
+
+`createAudio()` and `audio.sound()` create no context. A failed start reports
+`AudioBitsError` with a retryable `start-failed` code. A blocked resume times out
+after two wall-clock seconds; the context stays owned for gesture retry. Play
+before activation fails with `not-ready`; no input is queued.
+
+The archive exports `audiobits/schema.json` and `audiobits/capabilities.json`.
+The latter identifies package version, shipped primitives, initial Chromium gate and verification browser matrix;
+the schema is structural, while `validateRecipe` enforces additional semantic
+limits. Agent guidance is included in [the AudioBits Skill](skill/SKILL.md).
+
+## Supported data
+
+`defineSound(recipe)` accepts typed authored data, preserves recipe structure, literal parameter names and modes, validates and returns a deeply frozen `Recipe` snapshot.
+Runtime validation remains authoritative for exact schema validity.
+For external JSON, `validateRecipe(unknown)` returns `{ ok: true, recipe }` or
+`{ ok: false, issues }`; every issue has `code`, `path`, and `message`.
+Paths use JSON bracket notation, such as `$["layers"][0]["id"]`.
+`AudioBitsError` carries `code` and `issues`; errors during validation use
+`invalid-recipe`. The input must be plain JSON data without accessors or cycles.
+Unknown fields and versions are rejected. Validation is browser-independent.
+
+Schema version 1 supports:
+
+- One-shot gates in `(0, 60]` seconds or sustained playback until Stop, with
+  1–16 uniquely identified layers. Sustained recipes forbid `duration`.
+- Sine, triangle, sawtooth, and square oscillators; numeric Hz or linear/
+  exponential frequency automation beginning at zero and ending by gate close
+  (at most 60 seconds of onset automation for sustained voices). White noise
+  uses bounded generated buffers; there is no audio-file fetch.
+- Layer gain from -60 to 0 dB and fixed ADSR envelopes. Attack/decay are 0–10 s,
+  sustain is 0–1, release is 0.005–10 s. Effective attack is at least 0.002 s;
+  effective attack plus decay must fit within the gate. A zero decay ramps
+  directly to sustain rather than introducing an instantaneous peak.
+- Lowpass/highpass/bandpass filters with frequency 20–20000 Hz and numeric
+  Q 0.1–20. At most eight filters and 128 frequency points across the recipe.
+- Source/filter frequencies accept numeric values, mappings, variation, or
+  automation. Layer gain accepts numeric values, mappings, or variation;
+  gain automation and variable envelope times are not supported.
+- Up to 16 named parameters with `min < max`, an in-range `default`, and `mode`
+  of `play` or `live`. Live parameters require `smoothing` in 0.005–1 seconds.
+  Names begin with an ASCII letter and contain letters, digits or underscores,
+  up to 64 characters. Declaration numbers are bounded to -60000–60000.
+
+Depth is limited to 16, visited values to 10000, and diagnostics to 100.
+Source/filter frequencies must be below the owning context's Nyquist frequency
+at playback, including all mapping/variation extrema. Other effects,
+expression strings, sequencing, and continuous random modulation are rejected. These are the capabilities shipped in 0.1.0.
+The generated schema is available as `recipeSchema` or `audiobits/schema.json`.
+
+## Runtime ownership
+
+`createAudio({ maxVoices, maxVoicesPerSound, masterGainDb })` defaults to
+32 active voices per engine, eight per sound, and -12 dB master gain. Limits
+must be integers from 1–128; master gain must be -60–0 dB. `setMuted(boolean)`
+uses a separate mute setting and a 5 ms gain ramp.
+
+`sound.play({ at, gainDb, pan, parameters, seed, bus })` creates fresh sources synchronously. `at` is
+absolute audio-context time, obtained by the host's own scheduling logic;
+available after startup as `audio.native.context.currentTime`. Omit it for
+immediate playback. Past timestamps are rejected. Playback gain is -60–0 dB
+(default 0), pan is -1–1 (default 0). Future voices reserve capacity.
+
+`voice.stop()` cancels before onset or releases from the current envelope value.
+Repeated stops cannot extend lifetime. `voice.ended` resolves after owned nodes
+are disconnected; `voice.state` is `active`, `stopping`, `retiring`, or `ended`.
+Stopping voices keep their capacity reservation until cleanup. Oldest-voice
+stealing uses a 5 ms output fade. There is at most one retiring voice beyond
+engine/per-sound limits; another steal finalizes the previous retiree first.
+`audio.counts` distinguishes reserved active/stopping voices from retirees.
+
+Gate duration excludes release. Filters receive a bounded 50 ms tail allowance;
+output fades to zero over the final 5 ms. Layer filters precede their envelopes.
+`stopAll()` releases managed voices according to their recipe envelopes.
+`stopAll({ tails: "cut" })` uses a 5 ms source/output fade. `sound.dispose()` immediately finalizes
+that sound's voices and noise buffers. `audio.suspend()` invalidates pending starts and finalizes all voices before suspending.
+Native suspension/interruption also finalizes voices when its state event arrives.
+`audio.dispose()` invalidates pending startup, finalizes voices immediately,
+disconnects master output, and closes the context once, even while suspended.
+Disposal is terminal and idempotent; no audio-clock progress is needed.
+
+`audio.state` reports `idle`, `starting`, `running`, `suspended`, `interrupted`,
+`closed`, or `disposed`. `subscribe(listener)` returns an unsubscribe function.
+Concurrent starts share one promise. A host controls visibility/navigation policy;
+the engine does not replay sounds or automatically resume them.
+
+Recipes contain no native nodes, callbacks, framework imports, or runtime
+dependencies. Only `audiobits/recipes` imports curated sound data.
+Default headroom checks do not guarantee safe peaks for arbitrary recipes,
+filter resonance, gains, or concurrency.
+
+## Dynamic controls and replay
+
+```ts
+import { createAudio } from "audiobits";
+import { impact, thruster } from "audiobits/recipes";
+
+const audio = createAudio();
+const hit = audio.sound(impact);
+const engine = audio.sound(thruster);
+
+// In a user gesture, await activation before creating voices.
+await audio.start();
+hit.play({ parameters: { intensity: 0.8 }, seed: 42 });
+const voice = engine.play({ parameters: { throttle: 0.2 }, seed: 42 });
+voice.set({ throttle: 1 }); // Update this voice without retriggering.
+console.log(voice.seed, voice.parameters);
+voice.stop();
+await voice.ended;
+await audio.dispose();
+```
+
+Omitted parameters use recipe defaults. Invalid names, non-finite values,
+out-of-range controls, and invalid seeds fail before graph allocation or voice
+stealing. Updates validate every supplied key before changing any parameter;
+play-only controls cannot be updated. `voice.parameters` is a frozen snapshot of
+requested values, not a readback of the current smoothed native parameters.
+`voice.set()` after Stop, retirement, completion, or disposal throws
+`ended-voice`; other control errors use `invalid-control`.
+
+Mappings use `{ control, range: [low, high], scale }`, where scale is `linear`
+or `exponential`. Exponential mapping endpoints must be positive. Mapping ranges
+may descend; random ranges `{ random: [low, high] }` must be ordered. All extrema
+must satisfy the target range. Automation points can reference only play-only
+controls. Direct live mappings support source frequency, layer gain, and filter
+frequency. Native targets ramp linearly over the parameter's smoothing time,
+from their current value on every retarget. For gain, that ramp is in linear
+amplitude after dB conversion; mapping scale describes the control-to-target
+conversion, not the ramp curve. Envelopes remain fixed and independent of live
+level controls, so release remains continuous.
+
+Seeds are unsigned 32-bit integers, including zero. Without one, playback chooses
+a seed and exposes it on `voice.seed`. xorshift32 uses shifts 13/17/5 and divides
+its unsigned state by 2^32; seed zero maps internally to `0x6d2b79f5`. Resolution
+traverses root effects, then layers in array order. Each layer resolves gain,
+layer filters, source frequency, and a noise seed, in that order; automation
+points follow time order. Each variation consumes one draw, and each noise layer
+consumes one draw for its own xorshift32 stream. Object property insertion order
+does not change this traversal. This algorithm reproduces choices and
+noise for the same normalized recipe, controls, seed and sample rate; it does not
+promise identical oscillator/filter samples across browsers or sample rates.
+
+## Noise ownership and bounds
+
+Each noise layer owns one mono, one-second buffer at context sample rate. The
+last 20 ms crossfades into the first 20 ms; looping resumes after that prefix,
+so the wrap follows an ordinary adjacent sample pair. The loop period is about
+0.98 seconds. Both finite and sustained noise loop this bounded resource.
+This treatment has signal evidence and maintainer listening acceptance;
+individual listening observations were not recorded. There is no shared noise cache or rendered-output cache.
+
+Noise supports integer sample rates from 8000 through 192000 Hz. Unsupported
+rates fail with `noise-rate` before voice allocation. A layer retains at most
+768000 sample bytes (192000 at 48 kHz); generation temporarily uses one extra
+buffer of that size. A recipe has at most 16 layers, and existing voice limits
+bound concurrent buffers. The thruster owns ten nodes and one buffer per voice;
+with its default eight-voice limit plus one retiree, sample storage is at most
+1728000 bytes at 48 kHz. The engine master owns two additional nodes for independent gain and mute. These are
+owned sample-storage bounds, not measurements of all browser memory.
+
+Control updates allocate no new audio nodes or buffers. Finishing a voice clears
+its buffer-source references and disconnects owned nodes, including cancellation
+before onset, stealing, sound disposal, and engine teardown. Browser-internal
+reclamation timing remains outside the library's control.
+
+## Buses and routing
+
+After `await audio.start()`, `audio.master` is the root bus. `audio.bus(name,
+parent = audio.master)` creates a named bus or reuses the live bus with that
+name; use `setParent()` to move an existing bus. Names contain 1–64 characters
+and cannot be blank. At most 32 buses, including master, may be live. Routes
+form a single-parent tree; invalid, disposed, foreign-engine, and cyclic
+parents fail before changing the previous connection. Reassigning the same
+parent does not create another route. `sound.play({ bus })` defaults to master
+and rejects foreign/disposed buses before voice allocation or stealing.
+
+`bus.setGainDb(value, rampSeconds = 0.005)` accepts -60–0 dB and 0–10 seconds.
+It holds the current native value before ramping. `bus.setMuted(boolean)` uses
+an independent 5 ms stage, preserving volume automation. `audio.setMuted()`
+controls master mute, including a setting made before startup.
+
+```ts
+import { createAudio } from "audiobits";
+import { confirmation } from "audiobits/recipes";
+const audio = createAudio();
+const sound = audio.sound(confirmation);
+// In a gesture handler, after activating this engine:
+await audio.start();
+const effects = audio.bus("effects");
+effects.setGainDb(-6, 0.1);
+const voice = sound.play({ bus: effects });
+voice.stop(); // Release this voice.
+audio.stopAll({ tails: "cut" }); // Fade managed voices over 5 ms.
+effects.dispose(); // Finalize routed voices and descendant buses.
+await audio.dispose();
+```
+
+Each bus owns two gain nodes. Suspension and disposal finalize voices
+without waiting for audio-clock progress.
+
+Non-master bus disposal is idempotent and stops routed voices recursively.
+A later lookup of that name creates a fresh bus. `master.dispose()` fails;
+dispose the engine to release master. Engine disposal removes all owned
+output and closes its context, even while suspended or starting.
+
+## Native analyser and caller ownership
+
+`audio.native` is available after startup and exposes the owned `context`,
+master `output`, and `connect(node)` tap helper. The helper rejects foreign
+contexts, duplicate taps, the output itself, and the context destination.
+It returns an idempotent detach function. Master already connects to the
+speaker destination. Leave an analyser's output unconnected to avoid a second
+audible path. The vanilla example reads peak levels with a host animation
+frame, cancels that frame, detaches the tap, and disconnects its analyser
+before engine teardown.
+
+```ts
+import { createAudio } from "audiobits";
+const audio = createAudio();
+// Execute in a gesture handler.
+await audio.start();
+const native = audio.native;
+const analyser = native.context.createAnalyser();
+const detach = native.connect(analyser);
+const samples = new Float32Array(analyser.fftSize);
+analyser.getFloatTimeDomainData(samples);
+// Host teardown:
+detach();
+analyser.disconnect();
+await audio.dispose();
+```
+
+Caller-created nodes, sources, connections, and animation listeners are
+caller-owned. Stop unmanaged sources explicitly: `stopAll()` cannot stop them.
+Direct native graph operations remain the caller's responsibility and cannot
+be serialized as recipes. Closing the engine context invalidates these native
+nodes; retained native handles do not transfer ownership back to the engine.
+
+The site and vanilla demo invalidate pending Play actions, cut managed tails,
+and suspend on hide. Returning does not resume; a fresh gesture starts audio.
+Late activation after suspension is cancelled and cannot replay an old request.
+The engine also clears owned voices/effects on native interruption; automatic
+native recovery is suspended until a fresh `start()` request. Physical OS
+interruption still requires manual evidence. Step 04 passed maintainer manual
+verification on 2026-10-06. Browser/device details and individual observations
+were not supplied; automated checks remain separate from that acceptance.
+
+Buses provide gain, mute, and routing. Shared effects are deferred until
+multiple real sound requirements justify an API.
+
+## Curated sounds
+
+The eight exports live in `audiobits/recipes`: `confirmation`, `impact`, `thruster`,
+`tactileClick`, `gentleRejection`, `glassNotification`, `whoosh`, and `powerUp`.
+Intensity controls impact, click and power-up; brightness controls glass; size
+controls whoosh; throttle is live on thruster. Other sounds have no parameters.
+New sound definitions use only schema-1 sources, filters and envelopes. Their
+signal and resource properties are tested; the current eight curated sounds have
+passed the maintainer listening gate in Chrome. Output devices and detailed
+listening coverage were not specified.

package/dist/capabilities.json

@@ -0,0 +1,40 @@
+{
+  "packageVersion": "0.1.0",
+  "schemaVersion": 1,
+  "status": "stable",
+  "recipe": {
+    "kinds": ["one-shot", "sustained"],
+    "sources": ["oscillator", "noise"],
+    "waveforms": ["sine", "triangle", "sawtooth", "square"],
+    "noiseColors": ["white"],
+    "filters": ["lowpass", "highpass", "bandpass"],
+    "parameterModes": ["play", "live"],
+    "mappingScales": ["linear", "exponential"],
+    "automationCurves": ["linear", "exponential"],
+    "values": ["number", "mapping", "seeded-variation", "frequency-automation"]
+  },
+  "curatedRecipes": [
+    "confirmation",
+    "impact",
+    "thruster",
+    "tactileClick",
+    "gentleRejection",
+    "glassNotification",
+    "whoosh",
+    "powerUp"
+  ],
+  "runtime": [
+    "gesture-start",
+    "bounded-voices",
+    "live-controls",
+    "seeded-replay",
+    "buses",
+    "native-output-tap",
+    "suspend",
+    "dispose"
+  ],
+  "experimentalRuntime": [],
+  "browserGate": "Chromium",
+  "browserMatrix": ["Chromium"],
+  "schemaNote": "Structural schema only; validateRecipe also enforces semantic and resource limits. Playback checks context sample rate."
+}

package/dist/generated-BQ3sfms_.d.ts

@@ -0,0 +1,74 @@
+//#region src/recipe/generated.d.ts
+type Mapping = {
+  readonly control: string;
+  readonly range: readonly [number, number];
+  readonly scale: "linear" | "exponential";
+};
+type Variation = {
+  readonly random: readonly [number, number];
+};
+type PointValue = number | Mapping | Variation;
+type Value = PointValue | {
+  readonly points: ReadonlyArray<readonly [number, PointValue]>;
+  readonly curve: "linear" | "exponential";
+};
+type Frequency = Value;
+type Parameter = {
+  readonly min: number;
+  readonly max: number;
+  readonly default: number;
+  readonly mode: "play";
+} | {
+  readonly min: number;
+  readonly max: number;
+  readonly default: number;
+  readonly mode: "live";
+  readonly smoothing: number;
+};
+type Parameters = Readonly<Record<string, Parameter>>;
+type Envelope = {
+  readonly attack: number;
+  readonly decay: number;
+  readonly sustain: number;
+  readonly release: number;
+};
+type Filter = {
+  readonly type: "filter";
+  readonly filter: "lowpass" | "highpass" | "bandpass";
+  readonly frequency: Frequency;
+  readonly q: number;
+};
+type Source = {
+  readonly type: "oscillator";
+  readonly waveform: "sine" | "triangle" | "sawtooth" | "square";
+  readonly frequency: Frequency;
+} | {
+  readonly type: "noise";
+  readonly color: "white";
+};
+type Layer = {
+  readonly id: string;
+  readonly source: Source;
+  readonly gainDb: PointValue;
+  readonly envelope: Envelope;
+  readonly effects?: ReadonlyArray<Filter>;
+};
+type OneShotRecipe = {
+  readonly schemaVersion: 1;
+  readonly kind: "one-shot";
+  readonly duration: number;
+  readonly parameters?: Parameters;
+  readonly layers: ReadonlyArray<Layer>;
+  readonly effects?: ReadonlyArray<Filter>;
+};
+type SustainedRecipe = {
+  readonly schemaVersion: 1;
+  readonly kind: "sustained";
+  readonly parameters?: Parameters;
+  readonly layers: ReadonlyArray<Layer>;
+  readonly effects?: ReadonlyArray<Filter>;
+};
+type Recipe = OneShotRecipe | SustainedRecipe;
+declare const recipeSchema: Readonly<Record<string, unknown>>;
+//#endregion
+export { Mapping as a, Parameters as c, Source as d, SustainedRecipe as f, recipeSchema as h, Layer as i, PointValue as l, Variation as m, Filter as n, OneShotRecipe as o, Value as p, Frequency as r, Parameter as s, Envelope as t, Recipe as u };

package/dist/index.d.ts

@@ -0,0 +1,96 @@
+import { a as Mapping, c as Parameters, d as Source, h as recipeSchema, i as Layer, l as PointValue, m as Variation, n as Filter, p as Value, r as Frequency, s as Parameter, t as Envelope, u as Recipe } from "./generated-BQ3sfms_.js";
+//#region src/recipe/validate.d.ts
+interface RecipeIssue {
+  readonly code: string;
+  readonly path: string;
+  readonly message: string;
+}
+type ValidationResult = {
+  readonly ok: true;
+  readonly recipe: Recipe;
+} | {
+  readonly ok: false;
+  readonly issues: readonly RecipeIssue[];
+};
+export declare function validateRecipe(input: unknown): ValidationResult;
+export declare class AudioBitsError extends Error {
+  readonly code: string;
+  readonly issues: readonly RecipeIssue[];
+  constructor(code: string, message: string, issues?: readonly RecipeIssue[]);
+}
+export declare function defineSound<const R extends Recipe>(input: R): R;
+//#endregion
+//#region src/runtime/bus.d.ts
+interface Bus {
+  readonly name: string;
+  readonly parent: Bus | null;
+  setParent(parent: Bus): void;
+  setGainDb(value: number, rampSeconds?: number): void;
+  setMuted(value: boolean): void;
+  dispose(): void;
+}
+//#endregion
+//#region src/compiler/values.d.ts
+type Controls = Readonly<Record<string, number>>;
+//#endregion
+//#region src/runtime/engine.d.ts
+type AudioState = "idle" | "starting" | "running" | "suspended" | "interrupted" | "closed" | "disposed";
+interface AudioOptions {
+  readonly maxVoices?: number;
+  readonly maxVoicesPerSound?: number;
+  readonly masterGainDb?: number;
+}
+type RecipeParameters<R extends Recipe> = "parameters" extends keyof R ? NonNullable<R["parameters"]> : never;
+type NamedControls<K extends PropertyKey> = [K] extends [never] ? Readonly<Record<string, never>> : string extends K ? Controls : Readonly<Partial<Record<K, number>>>;
+type RecipeControls<R extends Recipe = Recipe> = [RecipeParameters<R>] extends [never] ? Readonly<Record<string, never>> : NamedControls<keyof RecipeParameters<R>>;
+type LiveControls<R extends Recipe = Recipe> = [RecipeParameters<R>] extends [never] ? Readonly<Record<string, never>> : string extends keyof RecipeParameters<R> ? Controls : NamedControls<{ [K in keyof RecipeParameters<R>]: RecipeParameters<R>[K] extends {
+  readonly mode: "live";
+} ? K : never; }[keyof RecipeParameters<R>]>;
+interface PlayOptions<R extends Recipe = Recipe> {
+  readonly at?: number;
+  readonly gainDb?: number;
+  readonly pan?: number;
+  readonly parameters?: RecipeControls<R>;
+  readonly seed?: number;
+  readonly bus?: Bus;
+}
+interface Voice<R extends Recipe = Recipe> {
+  readonly ended: Promise<void>;
+  readonly seed: number;
+  readonly parameters: RecipeControls<R>;
+  set(parameters: LiveControls<R>): void;
+  readonly state: "active" | "stopping" | "retiring" | "ended";
+  stop(): void;
+}
+interface Sound<R extends Recipe = Recipe> {
+  readonly recipe: R;
+  play(options?: PlayOptions<R>): Voice<R>;
+  dispose(): void;
+}
+interface AudioEngine {
+  readonly state: AudioState;
+  readonly counts: {
+    readonly active: number;
+    readonly retiring: number;
+  };
+  start(): Promise<void>;
+  suspend(): Promise<void>;
+  sound<const R extends Recipe>(input: R): Sound<R>;
+  sound(input: unknown): Sound;
+  readonly master: Bus;
+  bus(name: string, parent?: Bus): Bus;
+  readonly native: {
+    readonly context: AudioContext;
+    readonly output: AudioNode;
+    connect(node: AudioNode): () => void;
+  };
+  stopAll(options?: {
+    readonly tails?: "allow" | "cut";
+  }): void;
+  setMuted(muted: boolean): void;
+  subscribe(listener: (state: AudioState) => void): () => void;
+  dispose(): Promise<void>;
+}
+export declare function createAudio(options?: AudioOptions): AudioEngine;
+//#endregion
+export { type AudioEngine, type AudioOptions, type AudioState, type Bus, type Envelope, type Filter, type Frequency, type Layer, type LiveControls, type Mapping, type Parameter, type Parameters, type PlayOptions, type PointValue, type Recipe, type RecipeControls, type RecipeIssue, type Sound, type Source, type ValidationResult, type Value, type Variation, type Voice, recipeSchema };