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.
bd sd bd sd 1 cycle 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:
bd sd hh 1 cycle 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.
bd ~ sd ~ 1 cycle 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.
bd [sd sd] bd sd 1 cycle 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:
bd [sd [sd sd]] bd [~ sd] 1 cycle Three words in a group divide the slot into thirds, which gives a triplet:
bd [sd sd sd] bd sd 1 cycle 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:
hh*8 1 cycle On a step inside a longer sequence, it speeds up only that step:
bd sd*2 bd sd*4 1 cycle 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:
[bd sd]*2 1 cycle /n goes the other way. It slows the text down so that it takes n cycles. These strips show two cycles:
[bd sd hh sd]/2 2 cycles 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:
bd sd/2 hh sd 2 cycles 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:
bd <sd hh> 4 cycles 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:
bd <sd hh> bd <sd [sd sd]> 4 cycles 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.
bd(3,8) 1 cycle 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.
bd(5,8) 1 cycle 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:
bd(3,8,2) 1 cycle The step count is not limited to 8:
bd(7,16) 1 cycle 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:
bd(3,8) sd 1 cycle Weights and repeats: @, _, !
By default every step gets the same share. @n gives a step n shares:
bd@3 sd 1 cycle _ 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:
bd _ _ sd 1 cycle ! repeats a step. bd!3 is three bd steps in a row, so the pattern now has four steps of a quarter each:
bd!3 sd 1 cycle 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:
bd*3 sd 1 cycle 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:
bd! sd hh 1 cycle 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?:
hh*8? 4 cycles A number sets the chance of dropping, so ?0.3 drops about 30 percent and keeps the rest:
hh*8?0.3 4 cycles 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:
bd ~ sd ~, hh*8 1 cycle 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.
c3 e3 g3 1 cycle 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:
c3 [e3 g3]*2 ~ <b3 d4> 2 cycles 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.
c4:1 e4:0.6 g4:0.3 e4:0.6 1 cycle Chords from layers
A comma inside brackets stacks notes on the same step, which makes a chord:
[c3,e3,g3] ~ [f3,a3,c4] ~ 1 cycle 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>"))
0 [2 4]*2 <5 7> 2 cycles 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()
c3:min7 f3:7 [g3:sus4 g3] 1 cycle .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)
<c3:min7 f3:7> 2 cycles 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:
c2(3,8) ~ [eb2 g2] 1 cycle 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.
bd(3,8), ~ sd ~ sd, hh*8?0.2 2 cycles 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
| Symbol | Meaning | Example |
|---|---|---|
| space | Next step in the cycle | c3 e3 g3 |
~ or - | Rest | c3 ~ g3 |
[ ] | Group: fills one step | c3 [e3 g3] |
, | Layer: plays at the same time | [c3,e3,g3] |
*n | Play the step n times in its slot | c3*2 |
/n | Slow the step by n | [c3 e3]/2 |
< > | One option per cycle, in turn | <c3 e3 g3> |
(p,s) | Euclidean rhythm: p hits over s steps | c3(3,8) |
(p,s,r) | The same, rotated by r steps | c3(3,8,2) |
@n | Give the step n shares | c3@3 e3 |
_ | Add a share to the previous step | c3 _ e3 |
!n | Repeat the step, n steps in all | c3!3 |
? or ?n | Drop sometimes, the same way every time | c3?0.3 |
:v | Velocity from 0 to 1 (notes only) | c4:0.6 |
The reference for every symbol is the Mini-notation page of the Sigil.Sound documentation.