ToneForge

A procedural audio platform that generates placeholder sound effects instantly, so development never stalls waiting for final audio assets.

ToneForge lets developers generate placeholder sounds from recipes and seeds during prototyping — exploring variations in seconds, sharing reproducible results via seed numbers, and building with real audio feedback from day one. When the sound designer delivers final assets, swap them in. Every output is deterministic: same seed + same recipe = same result, across machines and runs.

What It Does

• Generate -- Procedural and sample-hybrid sound synthesis via the Web Audio API (browser-native, with optional offline rendering in Node.js)
• Compose -- Layer multiple sounds into stacks with per-layer gain, pan, and sample-accurate timing
• Sequence -- Schedule sounds into temporal patterns with state-driven transitions and probabilistic variation
• Analyze -- Extract audio features (envelope, spectral, loudness, transient) in batch
• Classify -- Semantic labeling via rule-based and AI model inference, with human correction
• Explore -- Sweep parameter spaces, discover outliers, rank and cluster variants
• Store -- Structured library with metadata indexing, similarity search, and deterministic regeneration
• Deploy -- Real-time playback engine with seed-based variation and baked fallback, targeting browser and Node.js
• Sync -- Deterministic multi-client behavioural synchronisation: compact events resolved locally, with no audio streaming
• Integrate -- Non-interactive CI pipeline (generate → validate → compile → export) and engine export via toneforge sync
• Exchange -- Browse, install and publish versioned, license-declared procedural packages via the marketplace command group

What It Is Not

ToneForge is not a DAW, a music sequencer, a black-box AI audio generator, or a replacement for sound designers. It generates placeholder and prototype audio so teams can develop with sound from the start. Final assets come from your sound designer — ToneForge makes sure you're never blocked waiting for them.

Status

MVP complete. The generate command renders and plays a procedural sci-fi UI confirm sound with seed-based variation and verified byte-level determinism.

Getting Started

git clone <repo-url> && cd ToneForge
npm install

On local development machines, npm install runs a safe postinstall step that attempts npm link, making two CLI commands available on your PATH:

• tf -- short alias (recommended for daily use)
• toneforge -- full name (used in demos and documentation)

Both commands are identical -- they run bin/dev-cli.js, which loads src/cli.yargs.ts (and the current CLI pipeline) directly via tsx. No build step is needed, and source changes are reflected immediately.

The command migration matrix and cutover gates are tracked in docs/cli-cutover-checklist.md.

Quick start

tf generate --recipe ui-scifi-confirm --seed 42

Run the interactive demo

npm run demo

The guided walkthroughs live in demos/ -- see the Demo Index for the full list. For a machine-consumption example, demos/machine-use.md walks through scripts/report-available-sounds.sh, a reusable batch script that consumes toneforge list recipes --json, filters out already-used sounds, and reports the remaining candidates as text or JSON -- useful when automating asset discovery in a build or CI pipeline.

Run the web demo

Starts the backend server and Vite dev server:

npm run dev:web

To open the demo from another device on the same LAN/Tailscale network, use npm run dev:web -- --host: the launcher derives the host's own hostnames/IPs and passes them to the backend as ALLOWED_ORIGINS (dev-only; production stays localhost,127.0.0.1). See web/README.md for details.

Run the runtime audio demo

The runtime is render-backed: a scripted session drives State and Context changes, each runtime event resolves to a recipe through a recipe resolver, and the existing offline renderer mixes the result — no second synthesis engine. Playing it lets you hear behaviour change (a footstep moving from stone to gravel, then walking to sprinting) instead of reading an event log:

toneforge runtime demo

The demo is deterministic (a fixed seed reproduces the same event log and the same rendered samples) and can be verified in CI without audio hardware:

toneforge runtime demo --json                 # print the resolved event timeline
toneforge runtime demo --output ./runtime-demo/  # export WAVs + timeline.json
toneforge runtime demo --seed 7 --json          # seed override

The scenario lives in presets/runtime/footsteps.json. See RUNTIME_PRD.md §19 for the render/playback pipeline design.

Drive the runtime live

runtime start opens a live session — the runtime embeds in a host and reacts to commands as they arrive, rendering each event through a bounded LRU buffer cache and scheduling it for playback at its sequence-relative time:

toneforge runtime start
# runtime> start walk          # begin continuous footsteps
# runtime> context surface=gravel
# runtime> param footstep-gravel pitch 1.5   # audible on the next loop pass
# runtime> state sprint
# runtime> stop
# runtime> quit

start runs a continuous transport that keeps the active sequence looping; state/context changes reconfigure it live and stop halts it. Each iteration uses a distinct deterministic seed, so the loop evolves rather than repeating identically. param <id> <name> <value> adjusts a continuous sound's intensity, gain, pitch or filter; because a whole WAV is rendered per event, the change is audible on the next loop pass (iteration-granular).

For deterministic, non-interactive replay (and CI), use a command script — --json streams one JSON object per runtime event and performs no playback, and --iterations bounds the loop so it terminates:

toneforge runtime start --script ./session.txt
toneforge runtime start --script ./session.txt --iterations 4
toneforge runtime start --script ./session.txt --json --iterations 4
toneforge runtime start --cache-size 128 --no-seed-variation

For a long-running service, --serve keeps the runtime alive and processing commands over time: it does not require a TTY, does not exit when stdin closes, and shuts down cleanly on SIGINT/SIGTERM or a quit command:

toneforge runtime start --serve

See RUNTIME_PRD.md §19 and Browser Runtime Usage.

Browser support

ToneForge is Runtime-aware: the Runtime, renderer, and recipe registry run in the browser using the native Web Audio API. node-web-audio-api is an optional dependency used only for offline rendering in Node.js and is never bundled into browser builds. See Using ToneForge in the Browser for installation, the Runtime API, and recipe-rendering examples.

Web demo — CI-safe CLI in the PTY

The web demo spawns a terminal PTY for the frontend to execute CLI commands. To make toneforge and tf resolvable inside that PTY without a global npm link, the server prepends a shim directory (bin/tf-shim/) to the PTY PATH at startup. The shim scripts delegate to bin/dev-cli.js, so the commands work in CI and on any machine.

Troubleshooting

In CI, the postinstall step skips linking automatically. If linking is unavailable locally (permissions/restricted environments), you'll see a non-failing message and can use the loader script directly:

./bin/dev-cli.js generate --recipe ui-scifi-confirm --seed 42

The docs/prd/ directory contains detailed product requirements documents for planned modules beyond the MVP.

Planned Tech Stack

• JavaScript / TypeScript
• Native Web Audio API in the browser
• Offline rendering via OfflineAudioContext (browser-native, or node-web-audio-api in Node.js)
• WAV export
• JSON configuration for presets, stacks, sequences, and library entries
• npm distribution

Architecture

ToneForge is organized as a pipeline of modular layers:

Layer	Modules
Sound creation	Core, Stack, Sequencer
Playback	Runtime, Mixer
Analysis	Analyze, Classify, Explore
Storage	Library
Intelligence	Intelligence, Intent, Memory
Behavior	State, Context
Output	Visualizer, Haptics, Palette
Production	CLI, Compiler, Validator, Integrations, Network, Marketplace

Each module has a dedicated PRD in docs/prd/.

Planned CLI

Commands beyond the MVP (not yet implemented):

toneforge generate --recipe laser --seed 42 --output laser.wav
toneforge stack --config stack.json --output combo.wav
toneforge analyze --input sound.wav --features envelope,spectral
toneforge explore --recipe laser --sweep gain:0.1-1.0 --count 100
toneforge library add --input sound.wav --tags "weapon,laser"

Marketplace

The marketplace command group browses, installs and publishes procedural asset packages (recipes, stacks, sequences, palettes) — versioned, license-declared and Validator-gated:

toneforge marketplace search [--category <c>] [--json]
toneforge marketplace install <package>@<version> [--json]
toneforge marketplace publish --package <dir> --name <n> --version <v> [--json]

See the Marketplace usage guide for runnable examples, and docs/prd/MARKETPLACE_PRD.md for the authoritative specification.

Documentation

• System Architecture PRD
• Intelligence — assistive, read-only library audit, recommendations, and exploration suggestions (suggests, never mutates)
• Intent & Memory — structured goals behind a human approval gate, plus the append-only project-local memory store and --use-memory context
• Core Module PRD
• Network — deterministic behavioural sync: events, host/join, late join, and bounded drift handling
• Integrations — engine adapter mapping and toneforge sync --target unity|web (deterministic, idempotent export)
• Network & Integrations usage — usage guide for the Network and Integrations modules
• Marketplace usage — the toneforge marketplace search/install/publish workflow, licensing, provenance and versioning
• ToneForge in CI — the toneforge pipeline CI workflow
• ToneGraph v0.1 Specification
• Casual Game Recipe Book — a guided tour of 100 procedural recipes, from single-oscillator blips to layered stings.
• Browser Runtime Usage
• Mixer Rules
• Visualizer
• Haptics
• All Module PRDs
• Research Questions

License

ToneForge is released under the MIT License.