Reading Mini-Notation: A Visual Guide

Mini-notation writes a rhythm or a melody as one line of text. This guide takes each symbol in turn and draws what it does.

Sigil.Sound, the audio library behind the Sound Script device, can write a pattern as a line of text:

Mini.Notes("c3 [e3 g3]*2 ~ <b3 d4>")

That is a lot of punctuation for four steps, and it reads like noise the first time. Each symbol does one small thing, though, and there are only a dozen of them. This post goes through them one at a time and draws the result.

How to read the strips

There are two kinds of strip on this page.

A drum strip looks like the step strip of a drum machine. Each distinct word gets a lane, and each pad is one event. The bright edge on the left is where the event starts. The length of the pad is the slice of the cycle that the step owns.

A note strip is a piano roll: time runs left to right, pitch runs bottom to top, and each bar is one note. It is the same view as the Output drawer of the Sound Script device when a script sends notes out of Note Out.

In both, the faint vertical lines are beats and the brighter line marks the start of a cycle. The strips are not mock-ups. They are generated by running the real Mini parser over the text above each one and drawing the events it returns, so what you see is what the library produces.

One caveat about the drum strips: words like bd and sd are only labels here. Mini.Parse lets you decide what a word means, but Mini.Notes reads note names. The last section of this post shows how to write the same drum patterns with Mini.Notes and play them in a Sound Script.

The cycle

A pattern is one cycle, and a cycle is four beats. At 120 bpm that is two seconds. Words separated by spaces are steps, and the steps share the cycle equally.

Drum strip bd sd bd sd 1 cycle
1234 bd sd

Four steps, so each one gets a quarter of the cycle. The step count does not have to fit the beat grid. Three steps divide the cycle into thirds:

Drum strip bd sd hh 1 cycle
1234 bd sd hh

Rests: ~

A ~ is a step with nothing in it. It still takes its slot, so the other steps keep their places. A - on its own does the same thing.

Drum strip bd ~ sd ~ 1 cycle
1234 bd sd

Groups: [ ]

Square brackets turn several words into one step. The words inside share that step’s slot, the same way the steps outside share the cycle.

Drum strip bd [sd sd] bd sd 1 cycle
1234 bd sd

There are still four steps at the top level. The second one is a group, so its slot is split in two. Groups nest, and each level halves or thirds whatever is left:

Drum strip bd [sd [sd sd]] bd [~ sd] 1 cycle
1234 bd sd

Three words in a group divide the slot into thirds, which gives a triplet:

Drum strip bd [sd sd sd] bd sd 1 cycle
1234 bd sd

Speed: * and /

*n plays a step n times inside its own slot. hh*8 is the one step in the pattern, so its slot is the whole cycle:

Drum strip hh*8 1 cycle
1234 hh

On a step inside a longer sequence, it speeds up only that step:

Drum strip bd sd*2 bd sd*4 1 cycle
1234 bd sd

A group followed by *2 plays the group twice in its slot. Here the group is the whole pattern, so this is another way to write bd sd bd sd:

Drum strip [bd sd]*2 1 cycle
1234 bd sd

/n goes the other way. It slows the text down so that it takes n cycles. These strips show two cycles:

Drum strip [bd sd hh sd]/2 2 cycles
CYCLE 1CYCLE 2 bd sd hh

Use / on a whole group when you want a long phrase. On a single step among others it is easy to misread, because the slowed step lasts n slots and runs into its neighbours:

Drum strip bd sd/2 hh sd 2 cycles
CYCLE 1CYCLE 2 bd sd hh

In cycle 1 the sd starts in its slot and lasts two slots, so it overlaps the hh. In cycle 2 the slot is empty.

One per cycle: < >

Angle brackets hold a list of options, and the pattern plays one option per cycle, in order. When it reaches the end of the list it starts over. These strips show four cycles:

Drum strip bd <sd hh> 4 cycles
CYCLE 1CYCLE 2CYCLE 3CYCLE 4 bd sd hh

The bd plays every cycle. The second step is sd in cycles 1 and 3 and hh in cycles 2 and 4. An option can be a group, so a step can change its rhythm as well as its sound:

Drum strip bd <sd hh> bd <sd [sd sd]> 4 cycles
CYCLE 1CYCLE 2CYCLE 3CYCLE 4 bd sd hh

Euclidean rhythms: (pulses,steps)

bd(3,8) spreads 3 hits over 8 steps as evenly as it can. You give it the count and the library finds the spacing. Here each pad is one of the 8 steps. The hits land on steps 1, 4 and 7, so the gaps between them are 3, 3 and 2 steps.

Drum strip bd(3,8) 1 cycle
1234 bd

Five hits cannot divide eight steps exactly, so the gaps are as close as whole steps allow: 2, 1, 2, 1 and 2. Two pairs of hits sit next to each other, and that is the most even spacing there is.

Drum strip bd(5,8) 1 cycle
1234 bd

A third number rotates the result. bd(3,8,2) has the same three hits as bd(3,8), moved two steps earlier and wrapped around the end:

Drum strip bd(3,8,2) 1 cycle
1234 bd

The step count is not limited to 8:

Drum strip bd(7,16) 1 cycle
1234 bd

The rhythm is spread over the step it is attached to. On its own that step is the whole cycle. In a longer sequence it is only the slot:

Drum strip bd(3,8) sd 1 cycle
1234 bd sd

Weights and repeats: @, _, !

By default every step gets the same share. @n gives a step n shares:

Drum strip bd@3 sd 1 cycle
1234 bd sd

_ adds one share to the step before it. This is the same pattern, written so that the steps line up when you read the text by eye:

Drum strip bd _ _ sd 1 cycle
1234 bd sd

! repeats a step. bd!3 is three bd steps in a row, so the pattern now has four steps of a quarter each:

Drum strip bd!3 sd 1 cycle
1234 bd sd

Compare that with *. bd*3 stays one step and squeezes three hits into its slot, so the pattern still has two steps and bd keeps half the cycle:

Drum strip bd*3 sd 1 cycle
1234 bd sd

The difference to remember: * changes how fast a step plays, and ! adds steps. A ! with no number repeats the step once, so bd! sd hh has four steps:

Drum strip bd! sd hh 1 cycle
1234 bd sd hh

Sometimes: ?

A ? after a step drops it some of the time. With no number it is a coin flip per event. These strips show four cycles of hh*8?:

Drum strip hh*8? 4 cycles
CYCLE 1CYCLE 2CYCLE 3CYCLE 4 hh

A number sets the chance of dropping, so ?0.3 drops about 30 percent and keeps the rest:

Drum strip hh*8?0.3 4 cycles
CYCLE 1CYCLE 2CYCLE 3CYCLE 4 hh

The choice looks random but is repeatable. Cycle 3 drops the same hits every time you play the pattern, so the groove has variation without changing from run to run.

Layers: ,

A comma starts a second line that plays at the same time as the first. Each layer is read on its own, so the steps in one do not need to match the steps in the other:

Drum strip bd ~ sd ~, hh*8 1 cycle
1234 bd hh sd

The first layer has two hits and the second has eight. They line up because both layers are read across the same cycle. Put layers inside brackets to limit them to one step.

Notes

Everything above applies to Mini.Notes, which reads note names instead of drum words. A name is a letter A to G, an optional # or b, and an octave, so c4 is middle C and eb3 is E flat in octave 3. Names are not case sensitive, and a name with no octave is in octave 3.

Note strip c3 e3 g3 1 cycle
1234 G3E3C3

Here is the pattern from the start of the post. It runs over two cycles. The group [e3 g3]*2 plays four short notes, the ~ leaves a gap, and <b3 d4> picks b3 in the first cycle and d4 in the second:

Note strip c3 [e3 g3]*2 ~ <b3 d4> 2 cycles
CYCLE 1CYCLE 2 D4B3G3E3C3

Velocity: :

A colon and a number from 0 to 1 sets how hard a note is played. The bars get brighter as the velocity goes up. Without it, notes use 0.8.

Note strip c4:1 e4:0.6 g4:0.3 e4:0.6 1 cycle
1234 G4E4C4

Chords from layers

A comma inside brackets stacks notes on the same step, which makes a chord:

Note strip [c3,e3,g3] ~ [f3,a3,c4] ~ 1 cycle
1234 C4A3G3F3E3C3

Scale degrees

Mini.Integers reads whole numbers. Hand them to a Scale and they become notes in that key, so you can change the key without rewriting the pattern. Degree 0 is the root and 7 is the root an octave up.

Scale.Major(Pitch.C3).Notes(Mini.Integers("0 [2 4]*2 <5 7>"))
Note strip 0 [2 4]*2 <5 7> 2 cycles
CYCLE 1CYCLE 2 C4A3G3E3C3

Chord names

Mini.Chords reads a root and a quality separated by a colon: c3:min7, f3:7, g3:sus4. .Notes() plays each chord as a block over its step:

Mini.Chords("c3:min7 f3:7 [g3:sus4 g3]").Notes()
Note strip c3:min7 f3:7 [g3:sus4 g3] 1 cycle
1234 D#4D4C4B3A#3A3G3F3D#3C3

.Arp() spreads each chord into a run instead. Each chord here lasts one cycle, and its four notes share that cycle:

Mini.Chords("<c3:min7 f3:7>").Arp(ArpMode.Up)
Note strip <c3:min7 f3:7> 2 cycles
CYCLE 1CYCLE 2 D#4C4A#3A3G3F3D#3C3

A rhythm inside a step

The same rule as the drum strips: a Euclidean rhythm fills only its own slot. In c2(3,8) ~ [eb2 g2] the first third of the cycle holds a three-hit rhythm on c2:

Note strip c2(3,8) ~ [eb2 g2] 1 cycle
1234 G2D#2C2

Putting it together

Here is a drum groove written as layers over two cycles: a kick on (3,8), a snare on beats 2 and 4, and eight hats a cycle with a fifth of them dropped.

Drum strip bd(3,8), ~ sd ~ sd, hh*8?0.2 2 cycles
CYCLE 1CYCLE 2 bd hh sd

In a Sound Script the three drums are three patterns, each one a Mini.Notes line with a single note name. What the note name means is up to the voice that plays it, so each line is paired with its own sound. The melody from earlier goes out of Note Out at the same time:

var kick  = Mini.Notes("c1(3,8)").Play(v =>
    Sine(Constant(45) + Constant(1).Adsr(0.001, 0.06, 0, 0.01) * 110).Adsr(0.001, 0.25, 0, 0.02));
var snare = Mini.Notes("~ c3 ~ c3").Play(v =>
    Noise().BandPass(1800, q: 1.2).Adsr(0.001, 0.12, 0, 0.05));
var hats  = Mini.Notes("c4*8?0.2").Play(v =>
    Noise(4).HighPass(7000).Adsr(0.001, 0.04, 0, 0.01));

Out.Notes(Mini.Notes("c3 [e3 g3]*2 ~ <b3 d4>"));

(kick * 0.7 + snare * 0.3 + hats * 0.2).Limit()

The kick, snare and hats come out of Audio Out. The last Out.Notes call sends the melody out of Note Out, and the Output drawer draws it as a note strip, like the one above. Wire Note Out to a synth to hear it.

In the Sound Script device the pattern text must be a string literal, not a variable, and a knob cannot change it. To change a pattern, edit the text and apply the script again.

When the text is wrong

A mistake is reported with its position in the text, and nothing plays until it is fixed. These are the messages the parser gives for some common ones. The column is counted from 1.

Text What the parser says
c3 *2 Unexpected '*' (column 4 in "c3 *2")
[c3 e3 Missing ']' (column 7 in "[c3 e3")
c3(9,8) (9,8) is not a valid rhythm: pulses must be between 0 and steps (column 3 in "c3(9,8)")
c3 e3) Unexpected ')' (column 6 in "c3 e3)")
_ c3 '_' needs a step before it to extend (column 1 in "_ c3")
c3*0 The speed factor must be above zero and at most 1024 (column 3 in "c3*0")
c3:2 '2' is not a velocity between 0 and 1. (column 1 in "c3:2")

The first row is the one to know. A modifier has to touch the step it belongs to. c3*2 is one step, and c3 *2 is a stray *.

The parser also refuses patterns that would be too heavy to play: a speed factor above 1024, a rhythm of more than 1024 steps, or brackets nested more than 32 deep.

Cheat sheet

SymbolMeaningExample
spaceNext step in the cyclec3 e3 g3
~ or -Restc3 ~ g3
[ ]Group: fills one stepc3 [e3 g3]
,Layer: plays at the same time[c3,e3,g3]
*nPlay the step n times in its slotc3*2
/nSlow the step by n[c3 e3]/2
< >One option per cycle, in turn<c3 e3 g3>
(p,s)Euclidean rhythm: p hits over s stepsc3(3,8)
(p,s,r)The same, rotated by r stepsc3(3,8,2)
@nGive the step n sharesc3@3 e3
_Add a share to the previous stepc3 _ e3
!nRepeat the step, n steps in allc3!3
? or ?nDrop sometimes, the same way every timec3?0.3
:vVelocity from 0 to 1 (notes only)c4:0.6

The reference for every symbol is the Mini-notation page of the Sigil.Sound documentation.