# Muse

> Write, test, and build audio plugins in the Muse DSL. Use when asked to "create a plugin", "write an audio effect", "build a synth", "make a VST", "CLAP plugin", "audio processing", "DSP effect", or any task involving Muse .muse files.

- Skill: `glittercowboy/muse` (Agent Skill, multi-file: 11 files)
- Install (CLI): `npx skillmds@latest add glittercowboy/muse`
- Raw SKILL.md: https://api.skillmd.com/api/skills/glittercowboy/muse/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: glittercowboy (https://skillmd.com/u/glittercowboy)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/glittercowboy/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>