muse

<essential_principles> ## What Is Muse Muse is a domain-specific language for declaring audio plugins. A `.muse` file describes one plugin: identity, parameters, audio I/O, format metadata, and signal processing logic. The compiler (`muse`) parses, resolves, generates Rust/nih-plug code, and builds native CLAP + VST3 binaries. ## Language Shape ``` plugin "Name" { // metadata: vendor, version, url, email, category // format blocks: clap { ... }, vst3 { ... } // I/O: input stereo, output stereo // voices N (polyphony, instruments only) // unison { count N detune X } (voice stacking, requires voices) // sample name "path" [external] (WAV sample declaration) // wavetable name "path" [external] (WAV wavetable declaration) // midi { note { ... } cc N { ... } } (instruments only) // param name: type = default in min..max { smoothing/unit/display } // gui { theme/accent/size/layout/panel/widgets/css } (custom editor) // process { signal chain } // test "name" { input/set/assert } } ``` Signal chains use `->` to pipe audio left-to-right: ``` input -> lowpass(param.cutoff) -> gain(param.volume) -> output ``` 37 built-in DSP functions + 3 audio primitives: `play`, `loop`, `wavetable_osc`. DSP functions: `sine`, `saw`, `square`, `triangle`, `noise`, `pulse`, `lfo`, `lowpass`, `highpass`, `bandpass`, `notch`, `peak_eq`, `low_shelf`, `high_shelf`, `adsr`, `ar`, `gain`, `pan`, `delay`, `mod_delay`, `allpass`, `comb`, `mix`, `crossfade`, `clip`, `tanh`, `fold`, `bitcrush`, `soft_clip`, `chorus`, `compressor`, `rms`, `peak_follow`, `gate`, `dc_block`, `sample_and_hold`, `semitones_to_ratio`. Audio primitives operate on declared samples/wavetables (not in the DSP registry). ## Key Constraints - **One plugin per file.** Every `.muse` file has exactly one `plugin "Name" { ... }` block. - **Brace-delimited.** No significant whitespace. All blocks use `{ }`. - **Category is a bare identifier** — `category effect`, not `category "effect"`. - **Param types:** `float`, `int`, `bool`, `enum [variant1, variant2]`. - **Unit suffixes on numbers:** `440Hz`, `50ms`, `0.5s`, `-12dB`, `50%`, `2st`. No space between number and suffix. - **`->` is lowest precedence.** Arithmetic binds tighter than signal chains. - **`split`/`merge` must pair.** Every `split { ... }` needs a `-> merge` in the same chain. - **Instruments need a `midi` block** with `note { ... }` to receive MIDI. Implicit bindings: `note.pitch`, `note.velocity`, `note.gate`, `note.pressure`, `note.bend`, `note.slide`, `note.number`. - **`voices N` enables polyphony.** Process block runs per-voice. All DSP state is automatically per-voice. Requires `midi` block. - **`unison { count N detune X }` stacks voices.** Each note spawns N detuned voices. Requires `voices`. - **Process block implicit bindings:** `input`, `output`, `sample_rate`. ## Known Limitations - **No CC test events.** Test blocks support `note on`/`note off` for MIDI injection but not control change events. - **macOS only.** The build pipeline (`muse build`) produces macOS CLAP + VST3 bundles. No Linux or Windows support. - **Polyphony is per-voice mono.** Each voice outputs mono, summed to the output bus. No per-voice stereo panning yet. - **Avoid Rust reserved words as variable names.** Don't use `mod`, `fn`, `type`, etc. as `let` binding names in process blocks — they'll break the generated Rust code. - **GUI editor crashes in VST3 hosts.** The web view editor (`gui { }` block) works in `muse preview` standalone mode but crashes when opened inside Ableton Live's VST3 host. Use `muse preview` to verify GUI appearance. Headless plugins (without `gui` block) work fine in all DAWs. - **`muse preview` audio input is macOS-only.** The `--input mic` option requires microphone permission (macOS will prompt on first use). The `--input file:<path>` option accepts WAV files only — mono or stereo, any sample rate (resampling not applied; a rate mismatch warning is printed). - **`muse preview` instruments ignore `--input`.** Only effect plugins use audio input routing. Instruments generate audio from MIDI — the `--input` flag is silently ignored for instrument plugins. - **WAV only for samples and wavetables.** No MP3, OGG, FLAC support. - **No sample rate conversion.** If WAV sample rate differs from host, playback speed varies. - **External mode loads samples relative to current working directory at plugin load time.** The host's CWD determines where external samples are found. ## CLI Quick Reference ``` muse check <file> [--format json] # Parse + resolve only muse compile <file> [--output-dir <dir>] [--format json] [--no-build] [--release] muse test <file> [--format json] # Run test blocks muse build <file> [--output-dir <dir>] [--format json] # Full build → CLAP + VST3 muse preview <file> [--format json] [--midi-port <name|list>] [--input <source>] # Live audio preview with hot-reload (macOS) ``` Exit codes: `0` success, `1` compile/check/test error, `2` build/I/O error. ## Plugin Template (Copy This) ```muse plugin "My Effect" { vendor "Your Name" version "0.1.0" category effect clap { id "com.yourname.my-effect" description "Short description" features [audio_effect, stereo] } vst3 { id "YourMyEffect1" subcategories [Fx] } input stereo output stereo param amount: float = 0.5 in 0.0..1.0 { smoothing linear 10ms } process { input -> gain(param.amount) -> output } test "passes signal" { input sine 440Hz 1024 samples set param.amount = 1.0 assert output.peak > 0.0 } test "silence in produces silence out" { input silence 512 samples assert output.rms < -120dB } } ``` </essential_principles> <intake> Before routing, determine what the user needs: **What do you want to do?** 1. **Create a new plugin** from a description → `workflows/create-plugin.md` 2. **Debug a compiler error** from muse check/compile/test output → `workflows/debug-errors.md` 3. **Extend an existing plugin** (add params, change DSP, add tests) → `workflows/extend-plugin.md` If the user's intent is clear from their message, skip the question and route directly. </intake> <routing> ## Workflow Routing | User Intent | Workflow | Required Reading | |---|---|---| | Create new plugin from description | `workflows/create-plugin.md` | `references/language-reference.md`, `references/dsp-primitives.md`, `references/test-syntax.md`, `references/plugin-recipes.md` | | Fix compiler/test errors | `workflows/debug-errors.md` | `references/error-codes.md`, `references/cli-commands.md` | | Add features to existing plugin | `workflows/extend-plugin.md` | `references/language-reference.md`, `references/dsp-primitives.md`, `references/test-syntax.md` | | Create plugin with custom GUI | `workflows/create-gui-plugin.md` | `references/language-reference.md`, `references/dsp-primitives.md`, `references/test-syntax.md`, `references/cli-commands.md`, `references/error-codes.md`, `references/plugin-recipes.md` | ## Reference Files | File | Contents | |---|---| | `references/language-reference.md` | Complete syntax guide: plugin structure, params, process blocks, signal chains, routing, MIDI, GUI blocks, metadata, type system | | `references/test-syntax.md` | Test block grammar, signal types, assertion properties, operators, JSON output format | | `references/dsp-primitives.md` | All 37 DSP functions + 3 audio primitives (play, loop, wavetable_osc) by category with signatures and descriptions | | `references/error-codes.md` | E001–E015 with causes and fix patterns (E015: duplicate sample/wavetable names; E003: unknown sample/wavetable in play/loop/wavetable_osc) | | `references/cli-commands.md` | All 5 CLI commands with flags, exit codes, JSON output schemas | | `references/plugin-recipes.md` | 21 annotated example patterns: gain, filter, synth, multiband, tremolo, distortion, chorus, dynamics, pulse synth, poly, MPE, unison, GUI (Tier 1), GUI (Tier 2), echo, EQ, gate, phaser, drum machine, wavetable synth, looping sampler | </routing>