Catalog and editable source

The catalog lets you hear sounds, adjust their controls, and inspect their source. The GitHub source registry distributes that source into your application. audiobits supplies the runtime; the installed files supply the sound and, for an experience, its interaction.

Recipes and experiencesCopy Anchor Link

A recipe is serializable, versioned sound data: sources, envelopes, filters, variation, and parameter mappings. It contains no UI or application state. Use a recipe for a button sound, notification, impact, or a sustained sound controlled by your own host. See the recipe reference.

An experience combines a recipe with a reusable interaction controller and a complete browser example. Try Energy Charge for application-supplied progress or Reactive Thruster for pointer-driven live throttle. You can use just the recipe, adapt the controller to your UI, or study the complete host.

Install sourceCopy Anchor Link

npx shadcn@latest list joacod/audiobits
npx shadcn@latest view joacod/audiobits/confirmation

npx shadcn@latest add joacod/audiobits/confirmation

npx shadcn@latest add joacod/audiobits/energy-charge
npx shadcn@latest add joacod/audiobits/reactive-thruster

Use the top-level view command above for inspection. In the currently verified CLI, add --dry-run, --diff, and --view can prompt for components.json in an unconfigured project. Decline unrelated framework setup or use the disposable preview setup.

Files you ownCopy Anchor Link

The items use explicit project-relative file targets. Normal installation needs no React, Tailwind, Next.js, or components.json. The source is TypeScript using public AudioBits exports and bundler module resolution, not precompiled JavaScript.

This tree shows the registry targets for Confirmation, Energy Charge, and Reactive Thruster. Only the selected item's files are installed. Reactive Thruster also includes Impact, which its complete host imports.

Integrate into your applicationCopy Anchor Link

For Confirmation, import the installed definition from a host file in src/:

import { createAudio } from "audiobits";
import { confirmation } from "./sounds/recipes/confirmation/recipe";

const audio = createAudio();
const sound = audio.sound(confirmation);

Use this definition in place of the local tone in the quick start. Call audio.start() directly from a user gesture, await activation, then call sound.play(). Surface activation errors and allow a fresh gesture to retry. Provide Stop, invalidate pending starts on cancellation, suspend on hide, and dispose owned resources on navigation or unmount. The lifecycle guide explains those host responsibilities.

For an experience, keep the installed relative paths intact. Reactive Thruster's complete host imports Impact at ../../recipes/impact/recipe. The included host.ts owns an engine and browser lifecycle; call its dispose() when removing an SPA view. If your application already owns audio, adapt progress.ts or pointer.ts to that shared engine instead. Those controllers dispose their own sounds and listeners; the host remains responsible for engine suspension and final disposal.

The nested index.html is an optional standalone demo requiring a TypeScript-aware browser toolchain. Installation does not replace your root entrypoint or create build configuration. Use your existing toolchain, or the optional standalone demo setup.

Workbench editorCopy Anchor Link

Each catalog workbench (/catalog/[slug]) accepts at most 32 KiB of JSON and shows the first ten validation issues. Apply explicitly; invalid input preserves the last valid playable sound. Applying a valid definition stops current playback and disposes the old sound. Play again to hear the new definition.

Keep the sound's playback kind and its primary parameter's range, default, and mode. Additional parameters use their declared defaults. Restore and Reset return to the catalog recipe, seed 42, and primary control defaults. Raw comparisons apply only to catalog definitions. Edited recipes still have a copyable AudioBits example containing the entire accepted JSON.

Customize and verifyCopy Anchor Link

Edit the installed recipe.ts to change pitch, gain, envelopes, filters, or parameter mappings. Keep application state, input mapping, and visuals in your controller or host. Parameters explains live controls and seeded replay; buses explains shared routing and mute.

Validate adapted data with validateRecipe from your installed runtime, then run your application's typecheck and build. Check defaults and control extrema, gesture activation, errors, Stop, hiding, and teardown in the browser. Static validation does not prove audio playback or audible quality. AudioBits automated browser evidence targets Chromium.

For help adapting or creating source, use the official agent Skill.