Songs and patterns

A song

Field	Meaning
bpm	Beats per minute. Each step in a pattern is a sixteenth note, so 4 steps make a beat.
swing	0 to 0.5. Delays every other step by that fraction of a step, for a bouncier feel. Optional.
key	The key, for scale degrees and in-key sound effects: "C major", "A minor", "D dorian". Optional.
transpose	Shift the whole song by this many semitones. Optional.
instruments	Named instruments (see Instruments).
sections	Named sections. Each maps instrument names to a pattern.
order	Section names in the order they play. The song loops back to the start.

const song = {
  bpm: 120,
  instruments: { lead: {}, bass: { wave: "triangle", octave: -1 } },
  sections: {
    verse: { lead: "C5 . E5 G5", bass: "C3 . . ." },
    chorus: { lead: "F5 - - . A5 - - .", bass: "F2 . . . C3 . . ." },
  },
  order: ["verse", "verse", "chorus"],
};

Steps

A pattern is steps separated by spaces.

Step	Means
C4, Eb5, F#3	A note: a letter, an optional # or b, and an octave. A4 is 440 Hz.
C4+E4+G4	A chord: notes joined with +.
Am7@3, Cmaj7@4, G@3	A named chord in an octave: major, m, 7, maj7, m7, dim, aug, sus2, sus4, 6, m6, add9, 9.
^1, ^5, ^3@5	A scale degree of the song's key (^1 is the root), in octave 4 or the one after @.
x	A hit, for drums.
X	An accented, louder hit.
.	Silence.
-	Hold the step before for one more step.
|	Ignored. Use it to mark bars.

C5 . E5 G5 | . E5 C5 . | D5 - - - | . . . .

That's a melody over four bars of four steps, ending on a D held for four steps.

Accents, ghost notes and chance

Any note, chord or hit can end with modifiers:

Ending	Means
!	Accent: louder. C5!
_	Ghost note: quieter. x_
?	Plays half the time. x?
?30	Plays 30% of the time. x?30

Chances are seeded: the same song plays the same way every time, so tests and replays stay stable.

Keys and scale degrees

With a key, write melodies in scale degrees and they always fit the key; change key and the whole melody moves:

{ key: "A minor", sections: { a: { lead: "^1 . ^3 ^5 | ^8 - ^7 ." } } }

Keys: major, minor, dorian, phrygian, lydian, mixolydian, pentatonic, minor pentatonic and blues, on any root ("F# minor"). Sound effects use the key too: see Sound design.

Variations and fills

A track can be a list of patterns. They take turns, one for each time the section plays:

kick: [
  "x . . . x . . . | x . . . x . . .",
  "x . . . x . . . | x . . . x . x x", // every second time: a fill
],

Patterns repeat to fill a section

A section lasts as long as its longest pattern. Shorter patterns repeat, so a drum loop can be one bar under a long melody:

{
  lead: "C5 . E5 G5 . E5 C5 . | D5 . F5 A5 . F5 D5 .", // 16 steps
  kick: "x . . .", // repeats four times
  hat: ". . x .", // repeats four times
}

Mistakes

Anything that isn't a note, a hit or one of the symbols above throws when the song plays, and the error names the step:

plonk: "Q9" isn't a note (try "C4", "Eb5" or "F#3")