docs/demo/demo-midi.md · cgcardona/muse

1

# Muse Music Plugin — Tour de Force

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.

---

## Setup

```bash

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"

```

---

## Act I — What's in the Track?

29

30

### `muse notes` — musical notation view

31

32

```

33

$ muse 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 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 notes tracks/melody.mid --commit HEAD~10

60

muse notes tracks/melody.mid --bar 4 # just bar 4

61

muse notes tracks/melody.mid --json # machine-readable

```

---

## Act II — See the Score

67

68

### `muse piano-roll` — ASCII piano roll

69

70

```

71

$ muse 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

└────────────────────────┴────────────────────────┘

1 2 3 1 2 3

```

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 piano-roll tracks/melody.mid --bars 1-8

90

muse piano-roll tracks/melody.mid --commit HEAD~5 --resolution 4 # sixteenth-note grid

```

---

## Act III — The Harmonic Layer

96

97

### `muse harmony` — chord analysis and key detection

98

99

```

100

$ muse 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

────────────────────────────────────────────────────────

1 Gmaj 4 G, B, D

2 Amin 3 A, C, E

3 Cmaj 4 C, E, G

4 D7 5 D, F#, A, C

5 Gmaj 4 G, B, D

6 Emin 3 E, G, B

7 Amin 3 A, C, E

8 Dmaj 4 D, F#, A

Pitch class distribution:

118

G ████████████████████ 8 (34.8%)

119

B ████████ 3 (13.0%)

120

D ██████████ 4 (17.4%)

A ████████ 3 (13.0%)

C ██████ 2 ( 8.7%)

E ██ 1 ( 4.3%)

F# ██ 1 ( 4.3%)

```

**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 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 harmony` is gold: an agent composing in a key can verify

133

the harmonic content of its work before committing.

---

## Act IV — The Dynamic Layer

138

139

### `muse velocity-profile` — dynamic range analysis

140

141

```

142

$ muse 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

ppp ( 1– 15) │ │ 0

pp ( 16– 31) │ │ 0

p ( 32– 47) │ │ 0

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

```

```

$ muse 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.

---

## Act V — Note-Level History

175

176

### `muse note-log` — what changed in each commit

177

178

```

179

$ muse 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

...

```

**Every change expressed in musical language**, not binary diffs.

201

202

`muse 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.

---

## Act VI — Note Attribution

210

211

### `muse note-blame` — which commit wrote these notes?

212

213

```

214

$ muse 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 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.

---

## Act VII — Where is the Compositional Instability?

241

242

### `muse note-hotspots` — bar-level churn

243

244

```

245

$ muse note-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 hotspots` for code.

262

263

```bash

264

muse note-hotspots --track tracks/melody.mid # focus on one track

265

muse note-hotspots --from HEAD~20 --top 5 # last 20 commits

```

---

## Act VIII — Agent Command: Transpose

271

272

### `muse transpose` — surgical pitch transformation

```bash

# Preview

$ muse 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 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`

```

```bash

muse transpose tracks/bass.mid --semitones -12 # down an octave

295

muse transpose tracks/melody.mid --semitones 5 # up a perfect fourth

296

muse transpose tracks/melody.mid --semitones 2 --clamp # clamp to MIDI range

297

```

298

299

For AI agents, `muse transpose` is the music equivalent of `muse 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.

After transposing:

```bash

muse status # shows melody.mid as modified

308

muse 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.

---

## Act IX — Agent Command: Mix

318

319

### `muse mix` — layer two tracks into one

320

321

```bash

322

$ muse mix tracks/melody.mid tracks/harmony.mid \

323

--output tracks/full.mid \

--channel-a 0 \

--channel-b 1

✅ 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 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 transpose tracks/violin.mid --semitones 0 # keeps content hash consistent

346

muse mix tracks/violin.mid tracks/cello.mid --output tracks/strings.mid --channel-a 0 --channel-b 1

347

muse 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 harmony tracks/ensemble.mid

352

muse velocity-profile tracks/ensemble.mid --by-bar

```

---

## The Full Collaborative Music Workflow

358

359

Here's what a multi-agent music session looks like with Muse:

### Session Setup

```bash

muse init --domain music

365

# Agent A starts the melody

366

echo "..." | muse-generate --type melody > muse-work/tracks/melody.mid

367

muse commit -m "Agent A: initial melody sketch"

368

```

369

370

### Agent B Adds Harmony

```bash

# Agent B branches

git checkout -b feat/harmony # Muse branching

375

376

# Analyse what Agent A wrote

377

muse notes tracks/melody.mid

378

muse harmony tracks/melody.mid # Key: G major

379

muse velocity-profile tracks/melody.mid # Dynamic: mf

380

381

# Generate a compatible harmony

382

echo "..." | muse-generate --type harmony --key "G major" > muse-work/tracks/harmony.mid

383

muse commit -m "Agent B: add harmony in G major"

```

### Merge

```bash

# Three-way merge at the note level

390

muse merge feat/harmony

391

392

# If both agents touched the same MIDI file:

393

# Muse splits into melodic / rhythmic / harmonic / dynamic / structural dimensions

394

# Each dimension merges independently

395

# Only true note-level conflicts surface as merge conflicts

```

### Quality Check

```bash

# After merge, verify the full picture

402

muse harmony tracks/melody.mid # still G major?

403

muse note-hotspots --top 5 # which bars got the most revisions?

404

muse velocity-profile tracks/melody.mid # did the dynamics survive the merge?

405

muse piano-roll tracks/melody.mid --bars 1-8 # visual sanity check

```

---

## The Full Command Matrix

411

412

| Command | What it does | Impossible in Git because… |

413

|---------|-------------|---------------------------|

414

| `muse notes` | Every note as musical notation | Git stores .mid as binary |

415

| `muse note-log` | Note-level change history | Git log shows binary diffs |

416

| `muse note-blame` | Per-bar attribution | Git blame is per line |

417

| `muse harmony` | Chord analysis + key detection | Git has no MIDI model |

418

| `muse piano-roll` | ASCII piano roll visualization | Git has no MIDI model |

419

| `muse note-hotspots` | Bar-level churn leaderboard | Git churn is file/line-level |

420

| `muse velocity-profile` | Dynamic range + histogram | Git has no MIDI model |

421

| `muse transpose` | Surgical pitch transformation | Git has no musical operations |

422

| `muse mix` | Combine two tracks into one | Git has no MIDI assembly |

423

424

Plus the core VCS operations, all working at note level:

425

426

| Command | What's different in Muse |

427

|---------|-------------------------|

428

| `muse commit` | Structured delta records note-level inserts/deletes |

429

| `muse diff` | Shows "C4 added at beat 3.5", not "binary changed" |

430

| `muse merge` | Three-way merge per dimension (melodic/harmonic/dynamic/structural) |

431

| `muse show` | Displays note-level changes in musical notation |

---

## For AI Agents Creating Music

436

437

When millions of agents are composing music in real-time, you need:

438

439

1. **Musical reads** — `muse notes`, `muse harmony`, `muse piano-roll` return

440

structured note data that agents can reason about, not binary blobs

441

442

2. **Musical writes** — `muse transpose`, `muse mix` apply well-defined

443

transformations that produce valid MIDI, with full note-level attribution

444

445

3. **Creative intelligence** — `muse harmony` gives agents harmonic awareness;

446

`muse velocity-profile` gives dynamic awareness; `muse note-hotspots` reveals

447

which sections are in flux

448

449

4. **Semantic merges** — two agents independently harmonizing the same melody

450

can merge at the note level — changes to non-overlapping notes never conflict

451

452

5. **Structured history** — every commit records a note-level structured delta;

453

every note has a content ID; `muse note-blame` attributes any bar to any agent

454

455

Muse doesn't just store your music. It understands it.

---

*Next: [Code Demo →](demo-code.md)*