the ultimate vocal synthesizer - sing, speak, beatbox, and more
Rust
CHIMERA
A physical-modeling voice synthesizer: a Rust engine (wasm in an AudioWorklet, native for tests and the CLI) under a React UI. See the README.
Working here
- Do what was asked, the simplest way. Side work nobody asked for (experiments, tooling, paid runs) is a proposal with its cost. If the work grows well past the estimate, stop and say so.
- Weigh every feature against README → Vision & scope; anything outside it is a proposal with its cost, not work to do.
- Before repeating or reversing earlier work, read its history (
git log -- <path>,git log -S). - Commit small. The subject names what changed and the trap, in searchable words; the body gives the why, what you ruled out, what you ran (with numbers) and what you didn't test.
- Keep each fixed bug's reproduction as a test.
- PRs follow
CONTRIBUTING.md: the body is written top-down, with evidence, and ends with the model and harness that wrote it. - Code outranks this file: fix the file when they disagree. When something breaks unnoticed, add a rule here, with a check.
Map
crates/chimera/: the engine (no I/O).crates/chimera-wasm/: the browser's C ABI.crates/chimera-cli/:chimera render | compare csd | compare tsp | diagnose | calibrate.src/wasm/: the UI's facade over the engine.src/worklet/: the AudioWorklet.src/ui/: React and the canvas renderers.src/song/: Sing's tunes, fitting words to them, clip recording.tests/: bun tests on the wasm build.tools/: e2e, layout lint, spectrogram, speech judges (asr/Whisper,tsp/the real speakers' data).docs/: architecture, the engine contract (rust-engine.md), the UI look, the singer and speech judges, the hill-climb rules, and how a language plugs in (language-front-ends.md).
Rules
- The engine's contract (
docs/rust-engine.md): transcendental math only throughchimera::math, no allocation while rendering, output independent of block size.cargo testenforces each. - The voice must hold at any device sample rate (a Bluetooth headset runs the page at 16 kHz,
and an airway simulated too slowly goes NaN: silence, no error). Check:
cargo test -p chimera --test engine the_voice_holds. - Any change to the sound or the plans fails the golden tests, by design. Re-bless with
CHIMERA_BLESS=1 cargo test --workspace --no-fail-fast, run twice. Human-voice audio, plans (including the beat sounds' gestures and the beat player), the tract geometry and the human airway's transfer functions re-bless; seecrates/chimera/tests/golden/README.mdfor the rest. *.generated.jsontables are regenerated (chimera calibrate,tools/gen-*), never edited. Vowel calibration isn't bit-reproducible, so rerun it only when the formants should move.src/wasm/chimera.wasmis a gitignored build product. After a Rust change,bun test testsalone tests the old engine: usebun run test. Don't share a cargotarget/between checkouts.- Gesture records are defined twice, in
crates/chimera-wasm/src/lib.rsandsrc/wasm/wire.ts. Change both and bumpLAYOUT_VERSION. - The wasm loads before the UI. A module that calls the engine at import must not be reachable
from
src/main.tsx's static imports. Check:bun tools/e2e.tsagainstbun run preview. - DOM content flows in
.screen-body, never absolutely positioned. Check:bun run lint:layout. - Nothing copyrighted goes in git.
public/shows/is gitignored; never ship CSD audio or anything derived from it. - Voice tuning follows
docs/hill-climb/README.mdand never edits its judges.
Checks
| When you touch | Run |
|---|---|
| anything | bun run test and bun run typecheck |
crates/chimera/ sound |
re-bless goldens (above); cargo run --release -q -p chimera --example bench against the previous commit |
crates/chimera-wasm/, src/wasm/, src/worklet/, src/main.tsx |
bun run build && bun run preview, then bun tools/e2e.ts |
src/ui/, src/show/, CSS |
bun run lint:layout |