Overview

Cells, statements, types, names, blocks, lengths and scope.

Cells

A cell is a program. The interpreter evaluates its statements top to bottom, one per line, and each play renders one output. Nothing else makes sound. // starts a comment, and a line that starts with | continues the line above it, at a bar line.

Statement	Example	Allowed
Setting	set tempo 90	Top level only, outside every block. See Settings.
with	with key E { ... }	Anywhere a statement or a line goes: settings for its block only. See with.
Declaration	steps fill = x-x-	Anywhere. See Names.
Line	kick: x--x---	In a block, or after play. See Types.
Group	(intro verse verse)	In a block, or after play. What plays in order goes in brackets. See Groups.
bar, every	bar 4 { ... }	In a block, or after play. See bar and every.
play	play groove	Top level only, which includes the top of a with there. See play.

Types

Every value has one of five types. A line is a kit piece or an instrument, a colon and a value, and the name before the colon decides the value’s type. So the drums and the pitched instruments never take each other’s values: a steps name on bass is an error, and so is a notes name on kick. A pattern holds lines of both.

Type	A value is	Literal	Used	See
steps	Hits for one kit piece, as steps or beats.	x--x---, 2 4	After a kit piece’s colon.	Steps
notes	Notes for one instrument, one at a time, by name or by degree of the key.	E---F# E-E--, 1---3---5---	After notes on an instrument’s line.	Notes
chords	Bars of chords.	Am F|C G	After chords on an instrument’s line.	Chords
pattern	Lines that play together and repeat.	{ kick: x--- }	After play, on a line of its own, or in a group.	Patterns

| block | Lines that play together once. | { crash: 1 } | After play, on a line of its own, or in a group. | Blocks |

Names

A declaration binds a name to a value: <type> <name> = <value>. The type is required. A name is accepted only where its type is, and only below its declaration.

A name of any type starts with a lowercase letter, then holds letters and digits, with a capital for each new word: riff, partA, countIn, at100. It is at least two characters long and not a Roman numeral, so it never reads as a step or a chord. Two names that differ only in their capitals are an error, including when one comes from a cell above. A name is defined once in a cell: defining it again is an error, inside a block too when it’s defined outside it. A cell can define again a name from a cell above.

Blocks

A block is statements in braces, and it evaluates to a value. Where the block is decides its type.

Block	Evaluates to
After pattern <name> =, play, bar or every	A pattern.
After with and its settings	At the top of a cell, the statements in it. Anywhere else, a pattern, played with the settings.
After a kit piece’s colon	One steps value, from layers.
After an instrument’s colon	Layers of notes and chords that sound together.

The statements in a block start together, one per line. What plays in order goes in brackets: a group holds names, blocks, groups and lines, one after another, separated by spaces or new lines. Braces hold what plays together and brackets what plays in order, so a newline never decides between them.

Written	Plays
{ ... } on a line of its own	Together with the other lines.
({ ... } { ... })	One after another.
intro verse, { ... } outro	An error: what plays in order goes in brackets.

The kick plays first and the snare after it, with the hats under both.

A block holds one line per kit piece or instrument. To layer one, give its line a block.

Where a line is decides whether it repeats. In a pattern, every line repeats until the pattern ends. Directly in a play, a line plays once. A value is not a loop: x--x--- is seven steps, and the pattern around it does the repeating. So a steps, notes or chords value written as the same figure more than once is an error: hat: x-x- x-x- is hat: x-, and chords Am F|Am F is chords Am F.

Lengths

A length is a number and a unit, written in front of what it measures: 4 bars groove, 2 beats rest, 3 beats C2, every 3 steps. Units are always plural, even after 1: 1 bars. On a line, ... is the length that is left of the block: ...rest, ...x-, ...G1. On a kit piece’s line a length repeats a figure, because a hit has no duration; on an instrument’s line it holds one note, because a note has one.

Unit	Lasts
steps	One step: a sixteenth note, unless every changes it.
beats	A quarter note, in every time signature.
bars	One bar of the current time.

Any number can be arithmetic: set tempo 60*2, every 1/3 beats.

Scope

• A set applies from its line to the end of the cell. It goes only at the top of a cell; inside a block, settings go on a with.
• A with’s settings apply to its block only, and what was set before comes back at its }.
• A declaration applies from its line to the end of the cell, or of the block it is in, including a with’s.
• A pattern is evaluated where it is played, with the settings in effect there, and with the names written above it: a later cell that defines a name again doesn’t change what an earlier pattern plays.
• The settings set at the top and the names declared there carry into other cells; a with’s never do. In the playground, a cell starts from the cells above it. In Jupyter, it starts from the cell named by after.