Documentation · Quick reference

Quick reference

All 35 constructs, one line each. Follow a name for its page and runnable examples.

The document

one text: The documentA project is one text. Every line is an expression, a rule or a command, and they run from the top down.
%%%: Comments and fillersA single % starts a comment that runs to the end of the line. Two or more, %%, is a filler that plays nothing and lasts no time.
ruleshelp: Housekeepingrules prints every rule defined so far. help prints the quick reference.

bpm n: TempoQuarter notes per minute. A plain note is one UNIT, a sixteenth, so a unit lasts 15/bpm seconds.
meter nunit 1/n: Meter and unitmeter is how many beats a measure has and unit is the note value of one beat, so meter 6 with unit 1/8 is 6/8. The default is 4/4.

key <root>[oct] <quality>: KeyThe key that scale degrees resolve against: a root, an optional octave, and maj, min, harm or mel.
mode diatonic | chromatic | midi: ModeWhat a bare number means. diatonic, the default, reads it as a scale degree. chromatic counts semitones from the key root. midi reads a MIDI note number.
c4 f#3 eb5 m60: Literal notesA pitch named outright: a lowercase letter, an optional accidental, an octave number. c4 is middle C.
1 '3 .5 6# 8: Scale degreesA bare number is a step of the current scale. ' raises it an octave, . lowers it, # and b alter it by a semitone.
i<n>s<n>: Relative pitchi<n> is n semitones from the last pitch written. s<n> is n steps of the current scale. The figure moves wherever you start it.
!c4Name(a b): Anchors!c4 sets the pitch that relatives count from, without playing it. Name(a b c) states a relative rule once from each note.
><: Melodic minor directionIn a mel key, > selects the ascending form, with raised 6 and 7, and < the descending form, with natural 6 and 7.

1MajcMin75Dom9: Chord symbolsOne token that sounds a whole chord: a root, then a quality. The root is a note name (c, eb) or a degree (1, 5).
1Dia5Dia7: Chords from the scaleDia stacks thirds from the scale itself, so the key decides the quality.
1Maj$3$1-5-3: VoicingsA $ after a chord lists its members from the bottom up.
{a, b}: Voices togetherFields inside braces, separated by commas, sound at the same time. The first field sets the length and the others stretch or squeeze to fit it.

kick snare hat: DrumsGeneral MIDI drum names are sounds, written like notes.
inst name = sound: AliasesGive a sound a short name of your own. The target can be a drum name, a MIDI drum number or a note.

--*n: Rests- is one unit of silence. Longer rests take the same duration marks as notes.
_n+n/n: DurationA note is one unit, a sixteenth, until a mark changes it. _n multiplies, +n adds units, /n divides.
*n: RepeatPlay the item before it n times. Bare * is twice.

@k@~k: Transpose@k moves a figure by k semitones. @~k moves it by k steps of the current scale, so it stays in the key.
~: RetrogradeThe figure played backwards. Durations go with their notes.
^: InversionThe figure mirrored around the axis: what went up goes down. The axis is degree 1 unless axis says otherwise.
axis <degree | first>: Inversion axisWhere ^ mirrors. The default is degree 1. axis 3 mirrors around the third, and axis first mirrors each figure around its own first note.

Name ::= …: RulesName a figure with Name ::= body. Uppercase names are rules; lowercase words are sounds.
Name[a:b]: SlicesA python slice over the ITEMS a reference plays: Row[:4], Row[2:], Row[::-1].
Name \i x: OverridesState a rule with one item replaced. The index is ZERO-BASED and counts what the reference PLAYS.
Cell ::= $1 …Cell(x): Cells and holesA rule with holes. $1 is filled by the first argument, $2 by the second. When there are more arguments than holes, the cell repeats to use them all.

A ::= x = yA#n: Alternatives= separates alternatives, which makes a rule a generator with one derivation per alternative. A bare reference plays the first; Name#n plays the nth.
x?x? y: Optional slotsx? plays x or a rest of the same length. x? y plays x or y, with y fitted to x's length. Either way the beat never moves.
x&( ): Repetition and groupsx& is zero or more x. Parentheses group items so a postfix covers all of them. One or more is x x&.
Name#a;b;c: SelectorsAfter #, segments separated by ; choose a derivation by what it holds. A number picks, asc and desc order by pitch, and anything else must match the item at that position.

|: BarsA barline stretches or squeezes what it holds to fill one measure of the current meter.
assert A == B: AssertPlay both sides silently and compare them event for event. It sounds nothing. If they differ, the line is an error that shows the first difference.