demo-midi.md
markdown
| 1 | # Muse MIDI Plugin — Demo |
| 2 | |
| 3 | > **Version control for music is not "track changes to audio files."** |
| 4 | > **It is: version control that understands music.** |
| 5 | |
| 6 | This is the full walk-through of every music-domain capability in Muse. |
| 7 | Every command below reasons about MIDI at the level of **individual notes, |
| 8 | chords, bars, and dimensions** — things no VCS has ever modelled. |
| 9 | |
| 10 | Git stores music as binary blobs. Muse stores it as a **content-addressed |
| 11 | graph of note events**, each with a stable identity that survives transpositions, |
| 12 | rearrangements, and cross-track moves. |
| 13 | |
| 14 | --- |
| 15 | |
| 16 | ## Setup |
| 17 | |
| 18 | ```bash |
| 19 | muse init --domain music |
| 20 | # Add some MIDI files to muse-work/ |
| 21 | cp ~/compositions/melody.mid muse-work/tracks/melody.mid |
| 22 | cp ~/compositions/bass.mid muse-work/tracks/bass.mid |
| 23 | muse commit -m "Initial composition" |
| 24 | ``` |
| 25 | |
| 26 | --- |
| 27 | |
| 28 | ## Act I — What's in the Track? |
| 29 | |
| 30 | ### `muse midi notes` — musical notation view |
| 31 | |
| 32 | ``` |
| 33 | $ muse midi notes tracks/melody.mid |
| 34 | |
| 35 | tracks/melody.mid — 23 notes — cb4afaed |
| 36 | Key signature (estimated): G major |
| 37 | |
| 38 | Bar Beat Pitch Vel Dur(beats) Channel |
| 39 | ────────────────────────────────────────────────── |
| 40 | 1 1.00 G4 80 1.00 ch 0 |
| 41 | 1 2.00 B4 75 0.50 ch 0 |
| 42 | 1 2.50 D5 72 0.50 ch 0 |
| 43 | 1 3.00 G4 80 1.00 ch 0 |
| 44 | 2 1.00 A4 78 1.00 ch 0 |
| 45 | 2 2.00 C5 75 0.75 ch 0 |
| 46 | ... |
| 47 | |
| 48 | 23 note(s) across 8 bar(s) |
| 49 | ``` |
| 50 | |
| 51 | **Why Git can't do this:** `git show HEAD:tracks/melody.mid` gives you a |
| 52 | binary blob. `muse midi notes` gives you the *actual musical content* — pitch |
| 53 | names, beat positions, durations, velocities — readable as sheet music, |
| 54 | queryable by an agent, auditable in a code review. |
| 55 | |
| 56 | Use `--commit` to see the notes at any historical point: |
| 57 | |
| 58 | ```bash |
| 59 | muse midi notes tracks/melody.mid --commit HEAD~10 |
| 60 | muse midi notes tracks/melody.mid --bar 4 # just bar 4 |
| 61 | muse midi notes tracks/melody.mid --json # machine-readable |
| 62 | ``` |
| 63 | |
| 64 | --- |
| 65 | |
| 66 | ## Act II — See the Score |
| 67 | |
| 68 | ### `muse midi piano-roll` — ASCII piano roll |
| 69 | |
| 70 | ``` |
| 71 | $ muse midi piano-roll tracks/melody.mid --bars 1-4 |
| 72 | |
| 73 | Piano roll: tracks/melody.mid — cb4afaed (bars 1–4, res=2 cells/beat) |
| 74 | |
| 75 | D5 │D5════════ │ │ |
| 76 | C5 │ │C5════ C5════│════ |
| 77 | B4 │ B4════ │ │ |
| 78 | A4 │ │A4════════ │ |
| 79 | G4 │G4════════ G4════════ │ │ |
| 80 | └────────────────────────┴────────────────────────┘ |
| 81 | 1 2 3 1 2 3 |
| 82 | ``` |
| 83 | |
| 84 | One glance tells you everything: which pitches appear, how long they sustain, |
| 85 | where the bar lines fall. This is the visual interface to a content-addressed |
| 86 | note graph. It works on any historical snapshot. |
| 87 | |
| 88 | ```bash |
| 89 | muse midi piano-roll tracks/melody.mid --bars 1-8 |
| 90 | muse midi piano-roll tracks/melody.mid --commit HEAD~5 --resolution 4 # sixteenth-note grid |
| 91 | ``` |
| 92 | |
| 93 | --- |
| 94 | |
| 95 | ## Act III — The Harmonic Layer |
| 96 | |
| 97 | ### `muse midi harmony` — chord analysis and key detection |
| 98 | |
| 99 | ``` |
| 100 | $ muse midi harmony tracks/melody.mid |
| 101 | |
| 102 | Harmonic analysis: tracks/melody.mid — cb4afaed |
| 103 | Key signature (estimated): G major |
| 104 | Total notes: 23 · Bars: 8 |
| 105 | |
| 106 | Bar Chord Notes Pitch classes |
| 107 | ──────────────────────────────────────────────────────── |
| 108 | 1 Gmaj 4 G, B, D |
| 109 | 2 Amin 3 A, C, E |
| 110 | 3 Cmaj 4 C, E, G |
| 111 | 4 D7 5 D, F#, A, C |
| 112 | 5 Gmaj 4 G, B, D |
| 113 | 6 Emin 3 E, G, B |
| 114 | 7 Amin 3 A, C, E |
| 115 | 8 Dmaj 4 D, F#, A |
| 116 | |
| 117 | Pitch class distribution: |
| 118 | G ████████████████████ 8 (34.8%) |
| 119 | B ████████ 3 (13.0%) |
| 120 | D ██████████ 4 (17.4%) |
| 121 | A ████████ 3 (13.0%) |
| 122 | C ██████ 2 ( 8.7%) |
| 123 | E ██ 1 ( 4.3%) |
| 124 | F# ██ 1 ( 4.3%) |
| 125 | ``` |
| 126 | |
| 127 | **This is impossible in Git** because Git has no model of what the bytes in a |
| 128 | `.mid` file mean. Muse stores every note as a typed semantic event with a |
| 129 | stable content ID. `muse midi harmony` reads the note graph and applies music |
| 130 | theory to find the implied chords — at any commit, for any track. |
| 131 | |
| 132 | For AI agents, `muse midi harmony` is gold: an agent composing in a key can verify |
| 133 | the harmonic content of its work before committing. |
| 134 | |
| 135 | --- |
| 136 | |
| 137 | ## Act IV — The Dynamic Layer |
| 138 | |
| 139 | ### `muse midi velocity-profile` — dynamic range analysis |
| 140 | |
| 141 | ``` |
| 142 | $ muse midi velocity-profile tracks/melody.mid |
| 143 | |
| 144 | Velocity profile: tracks/melody.mid — cb4afaed |
| 145 | Notes: 23 · Range: 48–96 · Mean: 78.3 · RMS: 79.1 |
| 146 | |
| 147 | ppp ( 1– 15) │ │ 0 |
| 148 | pp ( 16– 31) │ │ 0 |
| 149 | p ( 32– 47) │ │ 0 |
| 150 | mp ( 48– 63) │████ │ 2 ( 8.7%) |
| 151 | mf ( 64– 79) │████████████████████████ │ 12 (52.2%) |
| 152 | f ( 80– 95) │████████████ │ 8 (34.8%) |
| 153 | ff ( 96–111) │██ │ 1 ( 4.3%) |
| 154 | fff (112–127) │ │ 0 |
| 155 | |
| 156 | Dynamic character: mf |
| 157 | ``` |
| 158 | |
| 159 | ``` |
| 160 | $ muse midi velocity-profile tracks/melody.mid --by-bar |
| 161 | |
| 162 | bar 1 ████████████████████████████████ avg= 80.0 (4 notes) |
| 163 | bar 2 ██████████████████████████ avg= 76.0 (3 notes) |
| 164 | bar 3 ████████████████████████████ avg= 78.0 (4 notes) |
| 165 | bar 4 ████████████████████████████████ avg= 80.5 (5 notes) |
| 166 | ``` |
| 167 | |
| 168 | The per-bar view reveals the dynamic arc of the composition — a crescendo |
| 169 | building through bars 1–4, a release in bars 5–6. Agents can use this to |
| 170 | verify that a composition has the intended emotional shape. |
| 171 | |
| 172 | --- |
| 173 | |
| 174 | ## Act V — Note-Level History |
| 175 | |
| 176 | ### `muse midi note-log` — what changed in each commit |
| 177 | |
| 178 | ``` |
| 179 | $ muse midi note-log tracks/melody.mid |
| 180 | |
| 181 | Note history: tracks/melody.mid |
| 182 | Commits analysed: 12 |
| 183 | |
| 184 | cb4afaed 2026-03-16 "Add bridge section" (4 changes) |
| 185 | + A4 vel=78 @beat=9.00 dur=1.00 ch 0 |
| 186 | + B4 vel=75 @beat=10.00 dur=0.75 ch 0 |
| 187 | + G4 vel=80 @beat=11.00 dur=1.00 ch 0 |
| 188 | + D5 vel=72 @beat=12.00 dur=0.50 ch 0 |
| 189 | |
| 190 | 1d2e3faa 2026-03-15 "Revise verse harmony" (2 changes) |
| 191 | + D4 vel=75 @beat=5.00 dur=1.00 ch 0 |
| 192 | - C4 vel=72 @beat=5.00 dur=1.00 ch 0 (removed) |
| 193 | |
| 194 | a3f2c9e1 2026-03-14 "Initial composition" (14 changes) |
| 195 | + G4 vel=80 @beat=1.00 dur=1.00 ch 0 |
| 196 | + B4 vel=75 @beat=2.00 dur=0.50 ch 0 |
| 197 | ... |
| 198 | ``` |
| 199 | |
| 200 | **Every change expressed in musical language**, not binary diffs. |
| 201 | |
| 202 | `muse midi note-log` is the musical equivalent of `git log -p` — but instead of |
| 203 | showing `+line` / `-line`, it shows `+note` / `-note` with pitch name, beat |
| 204 | position, velocity, and duration. A composer reading this log understands |
| 205 | immediately what changed between commits. |
| 206 | |
| 207 | --- |
| 208 | |
| 209 | ## Act VI — Note Attribution |
| 210 | |
| 211 | ### `muse midi note-blame` — which commit wrote these notes? |
| 212 | |
| 213 | ``` |
| 214 | $ muse midi note-blame tracks/melody.mid --bar 4 |
| 215 | |
| 216 | Note attribution: tracks/melody.mid bar 4 |
| 217 | |
| 218 | D5 vel=72 @beat=1.00 dur=0.50 ch 0 |
| 219 | F#5 vel=75 @beat=1.50 dur=0.50 ch 0 |
| 220 | A5 vel=78 @beat=2.00 dur=1.00 ch 0 |
| 221 | C6 vel=72 @beat=3.00 dur=0.50 ch 0 |
| 222 | A5 vel=75 @beat=3.50 dur=0.50 ch 0 |
| 223 | |
| 224 | 5 notes in bar 4 introduced by: |
| 225 | cb4afaed 2026-03-16 alice "Add D7 arpeggiation in bar 4" |
| 226 | ``` |
| 227 | |
| 228 | **This is strictly impossible in Git.** |
| 229 | |
| 230 | Git cannot tell you "these specific notes in bar 4 were added in commit X" |
| 231 | because Git has no model of notes or bars. `muse midi note-blame` traces the |
| 232 | exact content IDs of each note in the bar through the commit history to find |
| 233 | the commit that first inserted them. |
| 234 | |
| 235 | For AI agents working collaboratively: "which agent wrote this phrase?" |
| 236 | One command. One answer. |
| 237 | |
| 238 | --- |
| 239 | |
| 240 | ## Act VII — Where is the Compositional Instability? |
| 241 | |
| 242 | ### `muse midi hotspots` — bar-level churn |
| 243 | |
| 244 | ``` |
| 245 | $ muse midi hotspots --top 10 |
| 246 | |
| 247 | Note churn — top 10 most-changed bars |
| 248 | Commits analysed: 47 |
| 249 | |
| 250 | 1 tracks/melody.mid bar 8 12 changes |
| 251 | 2 tracks/melody.mid bar 4 9 changes |
| 252 | 3 tracks/bass.mid bar 8 7 changes |
| 253 | 4 tracks/piano.mid bar 12 5 changes |
| 254 | 5 tracks/melody.mid bar 16 4 changes |
| 255 | |
| 256 | High churn = compositional instability. Consider locking this section. |
| 257 | ``` |
| 258 | |
| 259 | Bar 8 is the trouble spot. Twelve revisions. An agent or composer working |
| 260 | on a large piece can use this to identify which sections are unresolved — |
| 261 | the musical equivalent of `muse code hotspots` for code. |
| 262 | |
| 263 | ```bash |
| 264 | muse midi hotspots --track tracks/melody.mid # focus on one track |
| 265 | muse midi hotspots --from HEAD~20 --top 5 # last 20 commits |
| 266 | ``` |
| 267 | |
| 268 | --- |
| 269 | |
| 270 | ## Act VIII — Agent Command: Transpose |
| 271 | |
| 272 | ### `muse midi transpose` — surgical pitch transformation |
| 273 | |
| 274 | ```bash |
| 275 | # Preview |
| 276 | $ muse midi transpose tracks/melody.mid --semitones 7 --dry-run |
| 277 | |
| 278 | [dry-run] Would transpose tracks/melody.mid +7 semitones |
| 279 | Notes: 23 |
| 280 | Shifts: G4 → D5, B4 → F#5, D5 → A5, … |
| 281 | Pitch range: D5–A6 (was G4–D6) |
| 282 | No changes written (--dry-run). |
| 283 | |
| 284 | # Apply |
| 285 | $ muse midi transpose tracks/melody.mid --semitones 7 |
| 286 | |
| 287 | ✅ Transposed tracks/melody.mid +7 semitones |
| 288 | 23 notes shifted (G4 → D5, B4 → F#5, D5 → A5, …) |
| 289 | Pitch range: D5–A6 (was G4–D6) |
| 290 | Run `muse status` to review, then `muse commit` |
| 291 | ``` |
| 292 | |
| 293 | ```bash |
| 294 | muse midi transpose tracks/bass.mid --semitones -12 # down an octave |
| 295 | muse midi transpose tracks/melody.mid --semitones 5 # up a perfect fourth |
| 296 | muse midi transpose tracks/melody.mid --semitones 2 --clamp # clamp to MIDI range |
| 297 | ``` |
| 298 | |
| 299 | For AI agents, `muse midi transpose` is the music equivalent of `muse code patch`: |
| 300 | a single command that applies a well-defined musical transformation. The |
| 301 | agent says "move this track up a fifth" — Muse applies it surgically and |
| 302 | records the note-level delta in the next commit. |
| 303 | |
| 304 | After transposing: |
| 305 | |
| 306 | ```bash |
| 307 | muse status # shows melody.mid as modified |
| 308 | muse midi harmony tracks/melody.mid # verify the new key — still G major? No, now D major |
| 309 | muse commit -m "Transpose melody up a fifth for verse 2" |
| 310 | ``` |
| 311 | |
| 312 | The commit's structured delta records every note that changed pitch — |
| 313 | a note-level diff of the entire transposition. |
| 314 | |
| 315 | --- |
| 316 | |
| 317 | ## Act IX — Agent Command: Mix |
| 318 | |
| 319 | ### `muse midi mix` — layer two tracks into one |
| 320 | |
| 321 | ```bash |
| 322 | $ muse midi mix tracks/melody.mid tracks/harmony.mid \ |
| 323 | --output tracks/full.mid \ |
| 324 | --channel-a 0 \ |
| 325 | --channel-b 1 |
| 326 | |
| 327 | ✅ Mixed tracks/melody.mid + tracks/harmony.mid → tracks/full.mid |
| 328 | melody.mid: 23 notes (G4–D6) |
| 329 | harmony.mid: 18 notes (C3–B4) |
| 330 | full.mid: 41 notes (C3–D6) |
| 331 | Run `muse status` to review, then `muse commit` |
| 332 | ``` |
| 333 | |
| 334 | `muse midi mix` is the compositional assembly command for the AI age. An agent |
| 335 | that has generated a melody and a harmony in separate tracks can combine them |
| 336 | into a single performance track without a merge conflict. |
| 337 | |
| 338 | The `--channel-a` / `--channel-b` flags assign distinct MIDI channels to each |
| 339 | source so instruments can be differentiated in the mixed output. |
| 340 | |
| 341 | Agent workflow for a full arrangement: |
| 342 | |
| 343 | ```bash |
| 344 | # Agent generates individual parts |
| 345 | muse midi transpose tracks/violin.mid --semitones 0 # keeps content hash consistent |
| 346 | muse midi mix tracks/violin.mid tracks/cello.mid --output tracks/strings.mid --channel-a 0 --channel-b 1 |
| 347 | muse midi mix tracks/strings.mid tracks/piano.mid --output tracks/ensemble.mid --channel-a 0 --channel-b 2 |
| 348 | muse commit -m "Assemble full ensemble arrangement" |
| 349 | |
| 350 | # Verify the harmonic content of the final mix |
| 351 | muse midi harmony tracks/ensemble.mid |
| 352 | muse midi velocity-profile tracks/ensemble.mid --by-bar |
| 353 | ``` |
| 354 | |
| 355 | --- |
| 356 | |
| 357 | ## Act X — Rhythmic Intelligence |
| 358 | |
| 359 | ### `muse midi rhythm` — syncopation, swing, quantisation |
| 360 | |
| 361 | ``` |
| 362 | $ muse midi rhythm tracks/drums.mid |
| 363 | |
| 364 | Rhythmic analysis: tracks/drums.mid — working tree |
| 365 | Notes: 64 · Bars: 8 · Notes/bar avg: 8.0 |
| 366 | Dominant subdivision: sixteenth |
| 367 | Quantisation score: 0.942 (very tight) |
| 368 | Syncopation score: 0.382 (moderate) |
| 369 | Swing ratio: 1.003 (straight) |
| 370 | ``` |
| 371 | |
| 372 | Every rhythmic dimension in one command — impossible in Git. |
| 373 | |
| 374 | ```bash |
| 375 | muse midi rhythm tracks/drums.mid --commit HEAD~3 # historical snapshot |
| 376 | muse midi rhythm tracks/bass.mid --json # agent-readable |
| 377 | ``` |
| 378 | |
| 379 | --- |
| 380 | |
| 381 | ### `muse midi tempo` — BPM estimation |
| 382 | |
| 383 | ``` |
| 384 | $ muse midi tempo tracks/drums.mid |
| 385 | |
| 386 | Tempo analysis: tracks/drums.mid — working tree |
| 387 | Estimated BPM: 96.0 |
| 388 | Ticks per beat: 480 |
| 389 | Confidence: high (ioi_voting method) |
| 390 | ``` |
| 391 | |
| 392 | Uses inter-onset interval voting to estimate the underlying beat. Use `--json` to pipe into downstream agents that need to match tempo across branches. |
| 393 | |
| 394 | --- |
| 395 | |
| 396 | ### `muse midi density` — note density arc |
| 397 | |
| 398 | ``` |
| 399 | $ muse midi density tracks/drums.mid |
| 400 | |
| 401 | Note density: tracks/drums.mid — working tree |
| 402 | Bars: 8 · Peak: bar 5 (6.25 notes/beat) · Avg: 5.1 |
| 403 | |
| 404 | bar 1 ████████████ 4.00 notes/beat (16 notes) |
| 405 | bar 2 ████████████████████ 5.25 notes/beat (21 notes) |
| 406 | bar 3 █████████████ 4.25 notes/beat (17 notes) |
| 407 | bar 4 █████████████ 4.00 notes/beat (16 notes) |
| 408 | bar 5 ████████████████████ 6.25 notes/beat (25 notes) ← peak |
| 409 | ``` |
| 410 | |
| 411 | Reveals textural arc: sparse verses, dense choruses, quiet codas. |
| 412 | |
| 413 | --- |
| 414 | |
| 415 | ## Act XI — Pitch & Harmony (Deep) |
| 416 | |
| 417 | ### `muse midi scale` — scale and mode detection |
| 418 | |
| 419 | ``` |
| 420 | $ muse midi scale tracks/epiano.mid --top 3 |
| 421 | |
| 422 | Scale analysis: tracks/epiano.mid — working tree |
| 423 | |
| 424 | Rank Root Scale Confidence Out-of-scale |
| 425 | ───────────────────────────────────────────────────────── |
| 426 | 1 E natural minor 0.971 0 |
| 427 | 2 E dorian 0.929 2 |
| 428 | 3 A major 0.886 4 |
| 429 | ``` |
| 430 | |
| 431 | Goes beyond key: tests 15 scale types (major, minor, all seven modes, pentatonic, blues, whole-tone, diminished, chromatic) across all 12 roots. |
| 432 | |
| 433 | ```bash |
| 434 | muse midi scale tracks/lead.mid # top 3 matches |
| 435 | muse midi scale tracks/melody.mid --top 5 --json # agent-readable |
| 436 | ``` |
| 437 | |
| 438 | --- |
| 439 | |
| 440 | ### `muse midi tension` — harmonic tension curve |
| 441 | |
| 442 | ``` |
| 443 | $ muse midi tension tracks/epiano.mid |
| 444 | |
| 445 | Harmonic tension: tracks/epiano.mid — working tree |
| 446 | |
| 447 | bar 1 ▂▂▂▂▂▂▂▂ 0.08 consonant |
| 448 | bar 2 ████████████████ 0.43 mild |
| 449 | bar 3 ████████████████████ 0.67 tense |
| 450 | bar 4 ████ 0.12 consonant |
| 451 | ``` |
| 452 | |
| 453 | Scores each bar's dissonance level from 0 (consonant) to 1 (maximally tense). Agents can use this as a quality gate: tension should build toward climaxes and resolve at cadences. |
| 454 | |
| 455 | --- |
| 456 | |
| 457 | ### `muse midi cadence` — cadence detection |
| 458 | |
| 459 | ``` |
| 460 | $ muse midi cadence tracks/epiano.mid |
| 461 | |
| 462 | Cadence analysis: tracks/epiano.mid — working tree |
| 463 | Found 2 cadences |
| 464 | |
| 465 | Bar Type From To |
| 466 | ────────────────────────────────────── |
| 467 | 5 half Em Bdom7 |
| 468 | 9 authentic Bdom7 Em ← resolution |
| 469 | ``` |
| 470 | |
| 471 | Detects authentic, deceptive, half, and plagal cadences at phrase boundaries. Use `--strict` to fail CI if a composition lacks proper phrase closure. |
| 472 | |
| 473 | --- |
| 474 | |
| 475 | ### `muse midi contour` — melodic contour |
| 476 | |
| 477 | ``` |
| 478 | $ muse midi contour tracks/lead.mid |
| 479 | |
| 480 | Melodic contour: tracks/lead.mid — working tree |
| 481 | Shape: arch |
| 482 | Pitch range: D3 – C6 (35 semitones) |
| 483 | Direction changes: 6 |
| 484 | Avg interval size: 2.43 semitones |
| 485 | |
| 486 | Interval sequence (semitones): |
| 487 | +2 +3 +2 -1 +4 -3 +2 -2 -3 +1 -1 +2 … |
| 488 | ``` |
| 489 | |
| 490 | Six shape types: ascending, descending, arch, valley, wave, flat. A fast structural fingerprint: detect when an agent has accidentally flattened or inverted a melody. |
| 491 | |
| 492 | --- |
| 493 | |
| 494 | ## Act XII — Structure & Counterpoint |
| 495 | |
| 496 | ### `muse midi motif` — recurring pattern detection |
| 497 | |
| 498 | ``` |
| 499 | $ muse midi motif tracks/lead.mid |
| 500 | |
| 501 | Motif analysis: tracks/lead.mid — working tree |
| 502 | Found 2 motifs |
| 503 | |
| 504 | Motif 0 [+2 +2 -3] 3× first: E4 bars: 1, 5, 9 |
| 505 | Motif 1 [-2 +4 -2] 2× first: G4 bars: 3, 7 |
| 506 | ``` |
| 507 | |
| 508 | Scans the interval sequence between consecutive notes for repeated sub-sequences. Identifies thematic material independent of key — the pattern `[+2 +2 -3]` is the same motif whether it starts on E4 or G3. |
| 509 | |
| 510 | ```bash |
| 511 | muse midi motif tracks/melody.mid --min-length 4 --min-occurrences 3 |
| 512 | muse midi motif tracks/theme.mid --commit HEAD~5 # did the motif survive the merge? |
| 513 | ``` |
| 514 | |
| 515 | --- |
| 516 | |
| 517 | ### `muse midi voice-leading` — counterpoint lint |
| 518 | |
| 519 | ``` |
| 520 | $ muse midi voice-leading tracks/strings.mid |
| 521 | |
| 522 | Voice-leading check: tracks/strings.mid — working tree |
| 523 | ⚠️ 2 issues found |
| 524 | |
| 525 | Bar Type Description |
| 526 | ────────────────────────────────────────────────────── |
| 527 | 6 parallel_fifths voices 0–1: parallel perfect fifths |
| 528 | 9 large_leap top voice: leap of 11 semitones |
| 529 | ``` |
| 530 | |
| 531 | Detects parallel fifths, parallel octaves, and large leaps in the top voice. Use `--strict` in CI pipelines to block agents from committing harmonically problematic voice-leading. |
| 532 | |
| 533 | ```bash |
| 534 | muse midi voice-leading tracks/choir.mid --strict # CI gate |
| 535 | muse midi voice-leading tracks/strings.mid --json # agent-readable |
| 536 | ``` |
| 537 | |
| 538 | --- |
| 539 | |
| 540 | ### `muse midi instrumentation` — channel & register map |
| 541 | |
| 542 | ``` |
| 543 | $ muse midi instrumentation tracks/full_score.mid |
| 544 | |
| 545 | Instrumentation map: tracks/full_score.mid — working tree |
| 546 | Channels: 3 · Total notes: 106 |
| 547 | |
| 548 | Ch Notes Range Register Mean vel |
| 549 | ─────────────────────────────────────────────── |
| 550 | 0 34 C2–G2 bass 84.2 |
| 551 | 1 40 E4–B5 treble 71.8 |
| 552 | 2 32 C3–A4 mid 78.6 |
| 553 | ``` |
| 554 | |
| 555 | Shows which MIDI channels carry notes, the pitch range each channel spans, and the register. Verify that the bass channel stays low and the melody occupies the right register. |
| 556 | |
| 557 | --- |
| 558 | |
| 559 | ## Act XIII — History Deep-Dive |
| 560 | |
| 561 | ### `muse midi compare` — semantic diff between commits |
| 562 | |
| 563 | ``` |
| 564 | $ muse midi compare tracks/epiano.mid HEAD~2 HEAD |
| 565 | |
| 566 | Semantic comparison: tracks/epiano.mid |
| 567 | A: HEAD~2 (1b3c8f02) B: HEAD (3f0b5c8d) |
| 568 | |
| 569 | Dimension A B Δ |
| 570 | ────────────────────────────────────────────────────────── |
| 571 | Notes 18 32 +14 |
| 572 | Bars 4 8 +4 |
| 573 | Key E minor E minor = |
| 574 | Density avg 4.5/beat 5.1/beat +0.6 |
| 575 | Swing ratio 1.00 1.00 0.0 |
| 576 | Syncopation 0.11 0.38 +0.27 (more syncopated) |
| 577 | Quantisation 0.97 0.94 -0.03 |
| 578 | Subdivision quarter sixteenth changed |
| 579 | ``` |
| 580 | |
| 581 | Musical meaning of a diff: not "binary changed" but "8 bars added, syncopation doubled, subdivision tightened to sixteenth notes." |
| 582 | |
| 583 | --- |
| 584 | |
| 585 | ## Act XIV — Multi-Agent Intelligence |
| 586 | |
| 587 | ### `muse midi agent-map` — bar-level blame |
| 588 | |
| 589 | ``` |
| 590 | $ muse midi agent-map tracks/lead.mid |
| 591 | |
| 592 | Agent map: tracks/lead.mid |
| 593 | |
| 594 | Bar Last author Commit Message |
| 595 | ────────────────────────────────────────────────────────────── |
| 596 | 1 agent-melody 3f0b5c8d Groove: full kit + lead |
| 597 | 2 agent-melody 3f0b5c8d Groove: full kit + lead |
| 598 | 3 agent-harmony 4e2c91aa Harmony: modal interchange |
| 599 | 4 agent-harmony 4e2c91aa Harmony: modal interchange |
| 600 | 5 agent-arranger 1b2c3d4e Structure: add bridge |
| 601 | ``` |
| 602 | |
| 603 | The musical equivalent of `git blame` at the bar level. "Which agent owns bars 3–4?" One command. |
| 604 | |
| 605 | ```bash |
| 606 | muse midi agent-map tracks/lead.mid --depth 100 # walk deeper history |
| 607 | muse midi agent-map tracks/bass.mid --json # pipe to dashboard |
| 608 | ``` |
| 609 | |
| 610 | --- |
| 611 | |
| 612 | ### `muse midi find-phrase` — phrase similarity search |
| 613 | |
| 614 | ``` |
| 615 | $ muse midi find-phrase tracks/lead.mid --query query/motif.mid --depth 20 |
| 616 | |
| 617 | Phrase search: tracks/lead.mid (query: query/motif.mid) |
| 618 | Scanning 20 commits… |
| 619 | |
| 620 | Score Commit Author Message |
| 621 | ────────────────────────────────────────────────────────────────── |
| 622 | 0.934 3f0b5c8d agent-melody Groove: full arrangement |
| 623 | 0.812 4e2c91aa agent-harmony Harmony: modal interchange |
| 624 | 0.643 2d9e1a47 agent-melody Groove: syncopated kick |
| 625 | ``` |
| 626 | |
| 627 | Answer the question: "At which commit did this theme first appear, and on which branches does it still live?" Uses pitch-class histogram and interval fingerprint similarity — finds the motif regardless of transposition. |
| 628 | |
| 629 | --- |
| 630 | |
| 631 | ### `muse midi shard` — partition for parallel agents |
| 632 | |
| 633 | ``` |
| 634 | $ muse midi shard tracks/full.mid --shards 4 |
| 635 | |
| 636 | Shard plan: tracks/full.mid → 4 shards |
| 637 | Total bars: 16 · ~4 bars per shard |
| 638 | |
| 639 | Shard 0 bars 1– 4 → shards/full_shard_0.mid (48 notes) |
| 640 | Shard 1 bars 5– 8 → shards/full_shard_1.mid (52 notes) |
| 641 | Shard 2 bars 9–12 → shards/full_shard_2.mid (41 notes) |
| 642 | Shard 3 bars 13–16 → shards/full_shard_3.mid (38 notes) |
| 643 | |
| 644 | ✅ 4 shards written to shards/ |
| 645 | ``` |
| 646 | |
| 647 | The musical equivalent of `muse coord shard` for code: partition a composition into non-overlapping bar ranges so an agent swarm can work in parallel with zero note-level conflicts. Merge the shards back with `muse midi mix`. |
| 648 | |
| 649 | ```bash |
| 650 | muse midi shard tracks/symphony.mid --bars-per-shard 32 --output-dir agents/ |
| 651 | muse midi shard tracks/full.mid --shards 8 --dry-run # preview plan |
| 652 | ``` |
| 653 | |
| 654 | --- |
| 655 | |
| 656 | ## Act XV — Transformation Commands |
| 657 | |
| 658 | ### `muse midi quantize` — snap to rhythmic grid |
| 659 | |
| 660 | ```bash |
| 661 | # Preview |
| 662 | $ muse midi quantize tracks/piano.mid --grid 16th --strength 0.8 --dry-run |
| 663 | |
| 664 | [dry-run] Would quantise tracks/piano.mid → 16th-note grid (strength=0.80) |
| 665 | Notes adjusted: 28 / 32 |
| 666 | Avg tick shift: 18.4 · Max: 57 |
| 667 | No changes written (--dry-run). |
| 668 | |
| 669 | # Apply |
| 670 | $ muse midi quantize tracks/piano.mid --grid 16th |
| 671 | ``` |
| 672 | |
| 673 | Grid values: `whole`, `half`, `quarter`, `8th`, `16th`, `32nd`, `triplet-8th`, `triplet-16th`. |
| 674 | Use `--strength` < 1.0 for partial quantisation that preserves human feel. |
| 675 | |
| 676 | --- |
| 677 | |
| 678 | ### `muse midi humanize` — add human feel |
| 679 | |
| 680 | ```bash |
| 681 | $ muse midi humanize tracks/piano.mid --timing 0.015 --velocity 10 --seed 42 |
| 682 | |
| 683 | ✅ Humanised tracks/piano.mid |
| 684 | 32 notes adjusted |
| 685 | Timing jitter: ±0.015 beats · Velocity jitter: ±10 |
| 686 | Run `muse status` to review, then `muse commit` |
| 687 | ``` |
| 688 | |
| 689 | Applies controlled randomness to onset times and velocities. Use `--seed` for reproducible results in deterministic agent pipelines. |
| 690 | |
| 691 | --- |
| 692 | |
| 693 | ### `muse midi invert` — melodic inversion |
| 694 | |
| 695 | ```bash |
| 696 | $ muse midi invert tracks/melody.mid --pivot E4 --dry-run |
| 697 | |
| 698 | [dry-run] Would invert tracks/melody.mid (pivot: E4 / MIDI 64) |
| 699 | Notes: 23 |
| 700 | Transforms: G4 → C4, B4 → A3, D5 → F3, … |
| 701 | New range: B1–E4 (was E4–G6) |
| 702 | No changes written (--dry-run). |
| 703 | ``` |
| 704 | |
| 705 | Every upward interval becomes downward and vice versa, reflected around the pivot. Classic fugal transformation — combinable with the original for invertible counterpoint. |
| 706 | |
| 707 | --- |
| 708 | |
| 709 | ### `muse midi retrograde` — play it backward |
| 710 | |
| 711 | ```bash |
| 712 | $ muse midi retrograde tracks/melody.mid |
| 713 | |
| 714 | ✅ Retrograded tracks/melody.mid |
| 715 | 23 notes reversed (G4 → was last, now first) |
| 716 | Duration preserved · original span: 8.00 beats |
| 717 | Run `muse status` to review, then `muse commit` |
| 718 | ``` |
| 719 | |
| 720 | Reverses pitch order while preserving timing, velocity, and duration. Fundamental twelve-tone operation; impossible to describe in Git's binary model. |
| 721 | |
| 722 | --- |
| 723 | |
| 724 | ### `muse midi arpeggiate` — chords → arpeggios |
| 725 | |
| 726 | ```bash |
| 727 | $ muse midi arpeggiate tracks/epiano.mid --rate 8th --order up-down |
| 728 | |
| 729 | ✅ Arpeggiated tracks/epiano.mid (8th-note rate, up-down order) |
| 730 | 8 chord clusters → 40 arpeggio notes |
| 731 | Run `muse status` to review, then `muse commit` |
| 732 | ``` |
| 733 | |
| 734 | Orders: `up`, `down`, `up-down` (ping-pong), `random` (with `--seed` for reproducibility). |
| 735 | |
| 736 | --- |
| 737 | |
| 738 | ### `muse midi normalize` — rescale velocities |
| 739 | |
| 740 | ```bash |
| 741 | $ muse midi normalize tracks/lead.mid --min 50 --max 100 |
| 742 | |
| 743 | ✅ Normalised tracks/lead.mid |
| 744 | 32 notes rescaled · range: 62–104 → 50–100 |
| 745 | Mean velocity: 83.0 → 75.2 |
| 746 | Run `muse status` to review, then `muse commit` |
| 747 | ``` |
| 748 | |
| 749 | Linearly maps the existing velocity range to [--min, --max], preserving relative dynamics. Essential first step when integrating tracks from multiple agents recorded at different volumes. |
| 750 | |
| 751 | --- |
| 752 | |
| 753 | ## The Full Collaborative Music Workflow |
| 754 | |
| 755 | Here's what a multi-agent music session looks like with Muse: |
| 756 | |
| 757 | ### Session Setup |
| 758 | |
| 759 | ```bash |
| 760 | muse init --domain music |
| 761 | # Agent A starts the melody |
| 762 | echo "..." | muse-generate --type melody > muse-work/tracks/melody.mid |
| 763 | muse commit -m "Agent A: initial melody sketch" |
| 764 | ``` |
| 765 | |
| 766 | ### Agent B Adds Harmony |
| 767 | |
| 768 | ```bash |
| 769 | # Agent B branches |
| 770 | git checkout -b feat/harmony # Muse branching |
| 771 | |
| 772 | # Analyse what Agent A wrote |
| 773 | muse midi notes tracks/melody.mid |
| 774 | muse midi harmony tracks/melody.mid # Key: G major |
| 775 | muse midi velocity-profile tracks/melody.mid # Dynamic: mf |
| 776 | |
| 777 | # Generate a compatible harmony |
| 778 | echo "..." | muse-generate --type harmony --key "G major" > muse-work/tracks/harmony.mid |
| 779 | muse commit -m "Agent B: add harmony in G major" |
| 780 | ``` |
| 781 | |
| 782 | ### Merge |
| 783 | |
| 784 | ```bash |
| 785 | # Three-way merge at the note level |
| 786 | muse merge feat/harmony |
| 787 | |
| 788 | # If both agents touched the same MIDI file: |
| 789 | # Muse splits into melodic / rhythmic / harmonic / dynamic / structural dimensions |
| 790 | # Each dimension merges independently |
| 791 | # Only true note-level conflicts surface as merge conflicts |
| 792 | ``` |
| 793 | |
| 794 | ### Quality Check |
| 795 | |
| 796 | ```bash |
| 797 | # After merge, verify the full picture |
| 798 | muse midi harmony tracks/melody.mid # still G major? |
| 799 | muse midi hotspots --top 5 # which bars got the most revisions? |
| 800 | muse midi velocity-profile tracks/melody.mid # did the dynamics survive the merge? |
| 801 | muse midi piano-roll tracks/melody.mid --bars 1-8 # visual sanity check |
| 802 | ``` |
| 803 | |
| 804 | --- |
| 805 | |
| 806 | ## The Full Command Matrix — 31 Semantic Porcelain Commands |
| 807 | |
| 808 | ### Notation & Visualization |
| 809 | |
| 810 | | Command | What it does | |
| 811 | |---------|-------------| |
| 812 | | `muse midi notes` | Every note as musical notation: pitch name, beat, velocity, duration | |
| 813 | | `muse midi piano-roll` | ASCII piano roll — pitches on Y-axis, time on X-axis | |
| 814 | | `muse midi instrumentation` | Per-channel note range, register (bass/mid/treble), velocity map | |
| 815 | |
| 816 | ### Pitch, Harmony & Scale |
| 817 | |
| 818 | | Command | What it does | |
| 819 | |---------|-------------| |
| 820 | | `muse midi harmony` | Bar-by-bar chord detection + Krumhansl-Schmuckler key signature | |
| 821 | | `muse midi scale` | Scale/mode detection: 15 types × 12 roots, ranked by confidence | |
| 822 | | `muse midi contour` | Melodic contour shape (arch, ascending, valley, wave…) + interval sequence | |
| 823 | | `muse midi tension` | Harmonic tension curve: dissonance score per bar from interval weights | |
| 824 | | `muse midi cadence` | Cadence detection: authentic, deceptive, half, plagal at phrase boundaries | |
| 825 | |
| 826 | ### Rhythm & Dynamics |
| 827 | |
| 828 | | Command | What it does | |
| 829 | |---------|-------------| |
| 830 | | `muse midi rhythm` | Syncopation score, swing ratio, quantisation accuracy, dominant subdivision | |
| 831 | | `muse midi tempo` | BPM estimation via IOI voting; confidence rated high/medium/low | |
| 832 | | `muse midi density` | Notes-per-beat per bar — textural arc of a composition | |
| 833 | | `muse midi velocity-profile` | Dynamic range, RMS velocity, and histogram (ppp–fff) | |
| 834 | |
| 835 | ### Structure & Voice Leading |
| 836 | |
| 837 | | Command | What it does | |
| 838 | |---------|-------------| |
| 839 | | `muse midi motif` | Recurring interval-pattern (motif) detection, transposition-invariant | |
| 840 | | `muse midi voice-leading` | Parallel fifths/octaves + large leaps — classical counterpoint lint | |
| 841 | | `muse midi compare` | Semantic diff across key, rhythm, density, swing between two commits | |
| 842 | |
| 843 | ### History & Attribution |
| 844 | |
| 845 | | Command | What it does | |
| 846 | |---------|-------------| |
| 847 | | `muse midi note-log` | Note-level commit history: pitches added/removed per commit | |
| 848 | | `muse midi note-blame` | Per-bar attribution: which commit introduced each note | |
| 849 | | `muse midi hotspots` | Bar-level churn leaderboard: which bars change most across commits | |
| 850 | |
| 851 | ### Multi-Agent Intelligence |
| 852 | |
| 853 | | Command | What it does | |
| 854 | |---------|-------------| |
| 855 | | `muse midi agent-map` | Bar-level blame: which agent last edited each bar | |
| 856 | | `muse midi find-phrase` | Similarity search for a melodic phrase across all commit history | |
| 857 | | `muse midi shard` | Partition composition into N bar-range shards for parallel agent work | |
| 858 | | `muse midi query` | MIDI DSL predicate query: bar, pitch, velocity, agent, chord | |
| 859 | |
| 860 | ### Transformation |
| 861 | |
| 862 | | Command | What it does | |
| 863 | |---------|-------------| |
| 864 | | `muse midi transpose` | Shift all pitches by N semitones; dry-run + clamp support | |
| 865 | | `muse midi invert` | Melodic inversion around a pivot pitch | |
| 866 | | `muse midi retrograde` | Reverse pitch order (retrograde transformation) | |
| 867 | | `muse midi quantize` | Snap onsets to a rhythmic grid with adjustable strength | |
| 868 | | `muse midi humanize` | Add timing/velocity jitter for human feel; seed for determinism | |
| 869 | | `muse midi arpeggiate` | Convert chord voicings to arpeggios (up/down/up-down/random) | |
| 870 | | `muse midi normalize` | Rescale velocities to a target dynamic range | |
| 871 | | `muse midi mix` | Combine notes from two MIDI tracks into one output file | |
| 872 | |
| 873 | ### Invariants & Quality Gates |
| 874 | |
| 875 | | Command | What it does | |
| 876 | |---------|-------------| |
| 877 | | `muse midi check` | Enforce MIDI invariant rules: polyphony, range, key, parallel fifths | |
| 878 | |
| 879 | --- |
| 880 | |
| 881 | Every command above operates on structured note data and works at any historical commit. |
| 882 | Every one is impossible in Git, which stores MIDI as an opaque binary blob. |
| 883 | |
| 884 | --- |
| 885 | |
| 886 | ## For AI Agents Creating Music |
| 887 | |
| 888 | When millions of agents are composing music in real-time, you need: |
| 889 | |
| 890 | 1. **Musical reads** — `notes`, `harmony`, `scale`, `contour`, `rhythm`, `tension`, `density` |
| 891 | return structured data agents can reason about, not binary blobs. |
| 892 | |
| 893 | 2. **Musical writes** — `transpose`, `invert`, `retrograde`, `quantize`, `humanize`, |
| 894 | `arpeggiate`, `normalize`, `mix` apply well-defined transformations with full note-level |
| 895 | attribution in the next commit. |
| 896 | |
| 897 | 3. **Swarm coordination** — `shard` partitions the composition for parallel agents; |
| 898 | `agent-map` shows who owns which bars; `find-phrase` locates thematic material across |
| 899 | branches; `query` answers arbitrary musical questions across all history. |
| 900 | |
| 901 | 4. **Quality gates** — `check` enforces MIDI invariants; `voice-leading --strict` blocks |
| 902 | parallel fifths; `cadence` verifies phrase closure; `tension` ensures the emotional arc. |
| 903 | |
| 904 | 5. **Semantic merges** — two agents independently harmonizing the same melody |
| 905 | can merge at the note level — changes to non-overlapping notes never conflict. |
| 906 | |
| 907 | 6. **Structured history** — every commit records a note-level structured delta; |
| 908 | every note has a content ID; `note-blame` attributes any bar to any agent; |
| 909 | `compare` shows the musical meaning of any diff. |
| 910 | |
| 911 | Muse doesn't just store your music. It understands it. |
| 912 | |
| 913 | --- |
| 914 | |
| 915 | *Next: [Code Demo →](demo-code.md)* |