@litlab/audx 0.0.2 → 0.6.0

package/README.md

@@ -1,86 +1,129 @@
-# audx
+# @litlab/audx
 
-CLI tool for distributing and managing UI sounds from the [audx](https://audx.dev) registry.
+Declarative audio synthesis for the web. Describe sounds as plain objects, play them with one function call.
 
 ## Install
 
 ```bash
-npm install -g @litlab/audx
+npm install @litlab/audx
 ```
 
-Or use directly with `npx`:
+## Usage
 
-```bash
-npx @litlab/audx <command>
+### Define and play a sound
+
+```ts
+import { defineSound, ensureReady } from "@litlab/audx";
+
+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();
 ```
 
-## Quick Start
+### Shorthand helpers
 
-```bash
-# Initialize audx in your project
-audx init
+```ts
+import { sine, noise } from "@litlab/audx";
+
+const beep = sine(440, 0.1);
+const click = noise("white", 0.02);
+
+beep();
+click();
+```
+
+### Sound themes (React)
+
+```tsx
+import { useTheme } from "@litlab/audx/react";
+
+function App() {
+  const theme = useTheme("/themes/core.json");
 
-# Browse available sounds
-audx list
+  return (
+    <button onClick={() => theme.play("click")} disabled={!theme.ready}>
+      Click me
+    </button>
+  );
+}
+```
+
+### Sound themes (vanilla)
 
-# Add a sound
-audx add click-001
+```ts
+import { loadTheme } from "@litlab/audx";
 
-# Set up themes
-audx theme init
-audx theme map click click-001
-audx theme generate
+const theme = await loadTheme("/themes/core.json");
+theme.play("click");
 ```
 
-## Commands
+## CLI
 
-| Command | Description |
-|---|---|
-| `audx init` | Initialize audx config in your project |
-| `audx add <sounds...>` | Add sounds from the registry |
-| `audx remove <sounds...>` | Remove installed sounds |
-| `audx list` | List available sounds (`--tag`, `--search`) |
-| `audx diff` | Check for updates to installed sounds |
-| `audx update [sound]` | Update installed sounds from registry |
-| `audx generate "<prompt>"` | Generate a sound from a text prompt (`--name`, `--duration`) |
-| `audx theme init` | Create theme configuration |
-| `audx theme set <name>` | Switch active theme |
-| `audx theme map <semantic> <sound>` | Map a semantic name to a sound |
-| `audx theme create <name>` | Create a new theme |
-| `audx theme list` | List all themes |
-| `audx theme generate` | Generate `sound-theme.ts` |
+```bash
+# Browse and install themes from the registry
+npx @litlab/audx add
+
+# Install themes from a GitHub repo
+npx @litlab/audx add user/repo
 
-## How It Works
+# Create a new sound theme
+npx @litlab/audx init
 
-audx manages UI sounds as TypeScript modules with base64-encoded audio data — no external files to serve. Sounds are fetched from the audx registry and written directly into your project.
+# List installed themes
+npx @litlab/audx list
 
-The theme system lets you reference sounds by semantic purpose (`play("success")`) instead of file names, and swap entire sound palettes by switching themes.
+# Remove installed themes
+npx @litlab/audx remove
+```
 
-## Configuration
+## Theme authoring
 
-Running `audx init` creates `audx.config.json`:
+Create a theme JSON file with `npx @litlab/audx init`, then add sound definitions to the `sounds` object:
 
 ```json
 {
-  "soundDir": "src/sounds",
-  "libDir": "src/lib",
-  "registryUrl": "https://audx.dev",
-  "packageManager": "pnpm",
-  "aliases": {
-    "lib": "@/lib",
-    "hooks": "@/hooks",
-    "sounds": "@/sounds"
-  },
-  "installedSounds": {}
+  "$schema": "node_modules/@litlab/audx/schemas/theme.schema.json",
+  "name": "my-theme",
+  "sounds": {
+    "click": {
+      "source": { "type": "noise", "color": "white" },
+      "filter": { "type": "bandpass", "frequency": 2000 },
+      "envelope": { "decay": 0.05 }
+    }
+  }
 }
 ```
 
-Path aliases are auto-detected from your `tsconfig.json`.
+Push it to a GitHub repo. Others can install it with:
+
+```bash
+npx @litlab/audx 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 |
+| `loadTheme(url)` | Load a sound theme from a URL |
+| `defineTheme(json)` | Create a theme from a JSON object |
+| `useTheme(url)` | React hook for loading and playing themes |
 
-## Requirements
+## Documentation
 
-- Node.js 18+
+Full docs at [audx.site](https://audx.site).
 
 ## License
 
-MIT
+[MIT](https://github.com/ommgh/audio/blob/main/LICENSE)