Skip to the page
Lathe

Lathe guide

Lathe's note notation

A short text format for writing and reading MIDI parts through the AI assistant (MCP) tools. write_notes takes it as pattern, get_notes answers in it, and notation_guide gives the assistant the full reference below.

All pages

Why

write_notes took one JSON object per note: {"pitch": "F#2", "start_bar": 3.375, "length_beats": 0.25, "velocity": 96}. That is about 25 tokens a note, so a bar of 16th-note drums cost around 600, and every position was a fraction to work out (3.375 is bar 3, 16th 7). Assistants dealt with it by writing a Python script to produce the JSON: the music was in the script, and the session paid for the script, the output and the reasoning about both.

The notation is built from formats models already know: drum-machine step grids, Strudel/Tidal "mini-notation" for melodies, and note names. A bar of drums is three short lines. Positions come from the layout, so there's no arithmetic. Microtiming and per-note velocity are optional details on any note, so a plain part stays short and a detailed one costs only what it needs.

Goals

  • Write any part Lathe can hold: every pitch, start, length and velocity, to a small fraction of a

    millisecond.

  • Read back losslessly: get_notes output, written back with write_notes over the same bars,

    gives the same notes.

  • Familiar first. Where a symbol means something in Strudel, it means the same here, or it isn't

    used.

  • Errors say where: line, label, bar and step, and what was expected. Nothing is written if any

    line fails.

  • The JSON note list stays for anything the notation can't say.

Not covered yet: controller data (CC), pitch bend, per-note expression (MPE), and tempo or time-signature changes inside a pattern (Lathe has one tempo per song). See "Later".

The format

A pattern is lines. # starts a comment. Blank lines are ignored.

A pattern covers the bars given to write_notes (from_bar to to_bar). Each line is a loop: a one-bar line fills every bar of the range, a two-bar line alternates, and so on. A line longer than the range is an error. write_notes's repeat still repeats the whole range.

Pitches are note names or MIDI numbers, as in Lathe: C3 = 60 = middle C, F#2, Bb1, C-1. Any case. Drum names stand for the General MIDI notes Lathe's Drums plays:

Name (and short forms)Note
kick (bd)36
rim (rs)37
snare (sd)38
clap (cp)39
hat (hh, chh)42
phat (ph)44 (pedal hat)
ohat (oh, ohh)46
ltom (lt), mtom (mt), htom (ht)41, 45, 48
crash (cr)49
ride (rd)51
tamb54
cowbell (cb)56

Grid lines (drums, or any one pitch)

grid 16
kick   x... ..x. x... ....
snare  .... x... .... x..o
hat    8.6. 9.6. 8.6. 9.67

The first word is the lane: the pitch every hit plays. Then one character per step:

. or -rest
xhit, velocity 100
Xaccent, 120
oghost, 45
1-9hit at that level: 14, 28, 42, 56, 71, 85, 99, 113, 127

Spaces are ignored. | marks bar lines; with them, every bar must have exactly grid steps. Without them, the steps must fill whole bars. A hit lasts one step.

grid N sets the steps per bar for the lines after it. The default is 16th notes (16 in 4/4, 14 in 7/8); grid 12 gives 8th-note triplets in 4/4, grid 24 16th triplets.

A line is a grid line when it has a run of two or more step characters (x...). kick x x x x is a token line: four quarter notes.

Token lines (melodies, chords, exact timing)

bass:  c2:110 ~ [c2:80 c2:70-6ms] ~ | f1:105=2 _ ~ g1:90+4ms
keys:  [c3,e3,g3] _ _ ~ | <[a2,c3,e3] [f2,a2,c3]> _ _ ~
pad:   {Am7} _ {Fmaj7} _ | {Cmaj7} _ {G6}:90 _
snare: ~ x:96+6ms ~ x:100+8ms

The label is optional and ends with :. When it's a pitch or drum name, x, X and o in the line play it. Otherwise it's only a name for the line.

| separates bars. Each bar is divided evenly among its top-level tokens, as a Strudel cycle is. A line without | is one bar.

c3, F#2, 36, snarea note
x X oa hit on the line's lane (100, 120, 45)
~rest
_hold: the note before lasts one more step
[a b c]the three share one step
[a,b,c]played together (a chord); [a b, c d] two sequences at once
{Am7} {C/E} {Bbmaj7}2a chord by name, as [ , ] would play it. The root is in octave 3 (or the octave right after the brace), the rest stacked closely above it; a / note goes below. Known: maj m dim aug sus2 sus4 5 6 m6 7 maj7 m7 mmaj7 m7b5 dim7 7sus4 add9 madd9 9 maj9 m9 11 m11 13. Braces, because G6 or C7 on their own are notes
<a b>in turn, each time the line plays: a the first time, b the second, then a again. A one-bar line plays every bar, so it alternates bar by bar
a*3a, three times in its step

Any note, hit or group can carry up to four suffixes, in this order, no spaces:

:96velocity 1-127 (default 100; X 120, o 45)
+8ms, -5mslater or earlier, in milliseconds
+20%, -10%later or earlier, as a share of the note's own step
=1.5length in beats (default: its step, plus any holds)
*3repeat within the step (last)

c3:96+8ms=1.5. On a group, suffixes apply to every note inside that doesn't set its own: [c3,e3,g3]:80.

Feel

swing 58%            # every second 16th, 58% of the way through its 8th (50% is straight)
swing 62% 8          # every second 8th instead
humanize 6ms 8vel seed 3
humanize 5ms 6vel all  # vary notes' own timing and velocity too
swing off
humanize off

They apply to the lines after them until changed. Swing moves notes that start exactly on the off-beat it names, before any +ms. A swing line that moves no notes is almost always a slip (swing 58% swings 16ths, so a part in 8ths comes out straight): write_notes' reply points it out under "Check:", with the fix (swing 58% 8) when the part is in 8ths. Humanize nudges timing by up to ± the given milliseconds and velocity by up to ± the given amount, but leaves alone what a note sets itself (its own offset, its own velocity). With all, it varies those too, around what the note set: a lead with written dynamics and pushed notes (c4:96+6ms) can still be played a little loose. The same text and seed always give the same notes, so undo, the cloud and a re-run all agree.

Reading back (get_notes)

get_notes answers in the notation by default (format: "list" gives the old JSON). The first line says which bars it covers and how to write it back:

# "Beat", bars 1 to 3 (4/4, 120 BPM). write_notes from_bar 1, to_bar 3 with this pattern gives the same notes.
kick   x... ..x. x... .... | x... ..x. x... ..x.
snare  .... x... .... x... | .... x... .... x..o
hat    x.x. x.x. x.x. x.x. | x.x. x.x. x.x. xXx.
  • On a track whose instrument is a drum machine (its name has "drum" in it), each pitch is a lane,

    named when it's a drum name. A lane whose hits all sit on one grid, last one step and use the

    grid's velocities is a grid line; otherwise it's a token line with suffixes only where needed.

  • On other tracks, notes go into as few token lines ("voices") as keep them from overlapping:

    chords are [ , ], lengths are holds where they fit the bar's steps and = where they don't,

    and anything off the grid gets a % offset, which is exact at any tempo.

  • Swing is recognised: when every note in a lane or voice sits on a straight step, or on an

    off-beat moved later by one same amount, it reads back as a swing line and a straight part

    (swing off before the next line that isn't swung). 16ths first, then 8ths (swing 62% 8).

  • A note played just before a bar line (within a quarter of a 16th) reads back on the next bar's

    first step with a negative offset (x-4.8%), not at the very end of the bar before. In the last

    bar of the range there's no next bar, so it stays where it is.

  • Humanize is never guessed back; its effect shows as offsets and velocities.

Round trip: the same notes, starts and lengths within 0.0001 beats (well under a millisecond), velocities exact.

In the MCP tools

  • write_notes: new pattern (string), instead of notes. Same from_bar, to_bar, repeat

    and mode. Its reply says which lines looped to fill the bars, and how many times

    (kick and snare: 1 bar, played 16 times; bass: 4 bars, played 4 times), so a short line

    that ran under the wrong section shows up. Its description carries a few lines and two examples; that's paid in every

    session, so it stays short.

  • get_notes: new format, "pattern" (default) or "list".
  • notation_guide: no arguments; returns the reference above (symbols, velocity table, feel,

    common mistakes). Read-only, so it doesn't count as the assistant changing the song.

Errors

Line 3 (hat), bar 2: 15 steps, but grid is 16. Each bar between | needs exactly 16. Line 2 (bass), bar 2: "q3" isn't a note (C3 is middle C; drums: kick, snare, hat...). Line 4 (snare): this line is 3 bars but bars 1 to 3 are 2. Shorten it or widen the range.

Code

  • Source/Assistant/Notation.h/.cpp: parse (text to notes, for a range) and format (notes to

    text), plus the drum names and the guide text. No dependence on the engine, so it's tested on

    its own.

  • AssistantTools.cpp: write_notes takes pattern, get_notes gives it, notation_guide.
  • Tests: parsing each symbol, errors, swing and humanize (and all), the loop summary, and

    round trips of random parts (drums, chords, offsets, odd meters), swung parts and hits just

    before a bar line.

Later

  • Controller lanes: cc74 0 . . 64 . . 127 (a grid of values) and pitch bend.
  • Read-back that names chords ({Am7} instead of [a3,c4,e4,g4]) and chord inversions.
  • Compact read-back of repeated bars (! or a repeat count).
  • Measure: tokens and mistakes per song in the weekly videos task, before and after.

This page is docs/notation.md in Lathe's source, and changes with the app.