Manual

Refrain

Describes version 0.3.0

A sequencer you write. Type a line, and Refrain plays it as MIDI notes, locked to your host's bar. It drives any instrument, and it has a small synth of its own so you can hear a line before you have routed anything.

It is free.

In one minute

Open Refrain. It is already playing c3 ~ e3 [g3 c4] on its own synth.
Click in the text and change a note. The new line starts at the next bar.
Type rev( around it to hear the same bar backwards.
Press Mutate for a musical change you did not think of.
Drag MIDI clip into your host to keep what you have.

Everything below is that, in more detail.

The line

The text is the sequence. A cycle (one bar by default) is divided evenly between the steps you type, so x x x x is four beats and x x x is three across the same bar.

You type	You get
`x`	a hit on the key
`~`	a rest
`_`	hold the step before this one longer
`0` `2` `4` `-1`	a degree of the Scale, counted from the key, or from the chord under it when you write a progression. See The harmony
`c3` `eb2` `f#` `bb4`	that note, whatever the key is. No octave means octave 3
`bd` `sn` `hh` `oh` `cp` `cl`	a drum, on its General MIDI note. Never transposed
`c3'maj` `0'm7` `g'sus4`	a chord: a note or degree, a quote, a chord name
`c3'maj7'drop2`	that chord spread this way, whatever the Chords menu says
`c3'maj7'inv2`	that chord turned over, `inv1` to `inv3`
`c3+` `0-`	an octave up, or down. Repeat the sign to go further

Words you do not recognise are hits, so boom tick tick is a rhythm.

The key

The bar across the top is what the words mean, and it is the answer to "what does that dropdown do".

Key is a note and an octave. A plain x plays it, and degree 0 is the same note. The line at the right of the bar always says which note that is.
Scale is what the degrees count in. In the roll, the rows that belong to the key are open and the rest are shaded, with the key's own row in amber, so you can see the scale rather than remember it.
Snap folds every note into that scale: Nearest, Up or Down. With it off, note names are exactly what you typed. With it on, you can type a chromatic run and hear a scale.
Chords is the voicing every chord is dressed in, and the number beside it is the inversion. Two notes on the same step are a chord however you wrote them, so [c3, e3, g3] is voiced just like c3'maj.

Nothing here is ever disabled. When a control has nothing to act on the line at the right of the bar says so and says what to type: a control you cannot turn is a control you cannot learn.

A label dims when the text does not use it yet. Type a degree and the key lights up.

Shaping a hit

You type	You get
`x^`	louder: a quarter above the Velocity knob
`x.`	quieter: half
`x^0.8`	that fraction of the Velocity knob
`x^100`	exactly velocity 100, whatever the knob says
`x:2`	held two steps long
`x:0.5`	half a step
`g3&`	slide into it from whatever sounded last on its channel
`c3'maj%`	spread a chord into a run upwards
`c3'maj%d`	downwards. `%ud` and `%du` go both ways
`c3'maj%ud8`	the same, over eight notes, so it fills the step
`c3'maj7%o`	outside in: lowest, highest, next lowest, meeting in the middle
`c3'maj7%i`	inside out, which is that walk backwards
`c3'maj7%a`	an Alberti figure: bottom, top, middle, top
`c3'maj7%p`	a pedal: the lowest note between every other one
`c3'maj7%w`	a walk: one step at a time through the chord, never a leap, the same every bar
`c3'maj7%r`	a new order every bar
`c3'maj7%s`	one scramble, kept: jumbled, and the same every bar

They stack, in any order: c3^:2 is a loud, long C3.

Shaping a group

You type	You get
`[a b]`	split one step into parts
`[a, b]`	layer them: both sound
`[a \| b]`	one of them, chosen fresh each cycle
`<a b>`	alternate: one per cycle
`a*n`	n times inside its step
`a/n`	once every n cycles
`a!n`	repeat the step n times
`a?`	keep it half the time. `a?0.8` for 80 %
`a(k,n)`	Euclidean: k hits spread over n steps
`a(k,n,r)`	the same, rotated by r
`a@w`	give the step weight w, so it takes more of the bar

A modifier on a group applies to everything inside it: [c3 e3]^ accents both.

Several lines

Everything after // on a line is a comment. A line of the form name = ... names a pattern; use the name below it as a word. A name may use the names above it.

// a drum kit, one line each
kick  = bd ~ ~ bd ~ ~ bd ~
snare = ~ ~ sn ~ ~ ~ sn ~
hats  = [hh hh]*4
[kick, snare, hats]

Any other line is part of the pattern; several of them join into one.

The harmony

A line named chords is the progression the rest of the text is heard against.

chords = 1'm7 4'7 0'maj7 0'maj7
0 2 4 2

That is a two-five-one, and the melody over it is four degrees. A degree is counted along the Scale from the root of the chord sounding under it, so those same four degrees are D, B, G, E: the line follows the changes without being rewritten. Degree 0 is the chord's root, 2 is its third, 4 its fifth, 6 its seventh, and the odd numbers between are the passing notes.

With no chords line, a degree is counted from the Key, which is what it has always meant. Writing a progression only adds; nothing you already have changes.

chords is an ordinary definition, so it does not sound by itself. Write the word into your pattern to hear it:

chords = 1'm7 4'7 0'maj7 0'maj7
[chords, 0 2 4 2]

Note names, plain x and drums are not moved by the harmony. c3 is C3 whatever chord is underneath, because you asked for C3. Only degrees follow.

The bar across the top names the chord you are on while it plays: Dm7, G7, Cmaj7, and just the letter when it is a plain triad.

A chord written on a degree follows the progression too. 0'maj is a major triad on whatever root is under it, so chords = 1'm7 4'7 with 0'maj 0'maj gives a D major triad and then a G major one. Only chords written on note names, c3'maj, stay where you put them.

Chords: Lead. The eighth voicing picks, for each chord, the inversion that sits nearest the middle of the key's register. A progression then moves by a step or two instead of leaping every time its root does. It decides from the chord alone, so it is the same every time you play it.

The rest of the voicings. Fourteen in all, and every one of them is the same notes in a different arrangement, so the harmony never changes, only the spacing.


Close	as written, lowest first
Open	the middle voice up an octave
Drop 2, Drop 3	the second or third voice from the top, an octave down. The standard way to stop a close chord sounding thick
Drop 2+4	both of them. Wider still, and the one guitar players reach for
Spread	every voice an octave above the one below it. Enormous
Shell	the fifth thrown away, root, third and seventh kept. What a left hand plays
Rootless	the root thrown away instead. The colour without the anchor, for when a bass is already playing it
Fourths	stacked fourths from the root. Modal, unsettled, no third to place it
Quintal	stacked fifths. Open and ringing, more air than a chord usually has
Cluster	every voice folded inside one octave, seconds and all. Tight and bright
Wide	the root drops an octave and the top rises one. A hole in the middle
Bell	the top voice two octaves up, ringing over the rest

None of them change which notes are in the chord, so a progression keeps its harmony whichever you pick, and the inversion beside the menu still applies on top.

Changing a pattern

A handful of words take a pattern and give back a pattern. This is the thing a written sequence does that a drawn one cannot: you say "and now backwards" once and it stays true, however often you change your mind about the notes.

You type	You get
`rev(a)`	the same bar, backwards
`transpose(n, a)`	every note moved n steps along the Scale. Negative goes down
`invert(a)`	the line turned upside down, about the middle of its own range
`iter(n, a)`	the bar starts one nth later each cycle, coming round after n
`palindrome(a)`	there one cycle, back the next
`every(n, f, a)`	do `f` to it every nth cycle, where `f` is `rev`, `invert` or `palindrome`
`off(n, a)`	and again, `n` of a cycle later, layered over it
`off(n, f, a)`	the same, with `f` done to the copy on the way
`ply(n, a)`	every hit becomes `n` hits inside its own step
`ramp(v1, v2, a)`	fade the velocity from one level to another across it, so a run swells or dies away
`swing(n, a)`	swing this part only, from 0 to 1, whatever the Swing knob is doing to everything else
`accel(n, a)`	speed it up across the span. `accel(2, ..)` ends twice as fast as it starts; below 1 slows down
`chunk(n, f, a)`	cut the bar into `n` and do `f` to a different one each cycle
`channel(n, a)`	send it out on MIDI channel `n`, whatever the knobs say
`cc(n, a)`	its levels become controller `n` instead of notes: 1 is the mod wheel, 11 expression, 74 a filter

off is the one worth learning first. One line becomes two voices:

riff = 0 2 4 2
[riff, off(0.125, rev, riff)]

channel lets one Refrain drive a rack. Everything in it goes to that channel, so a kit, a bass and a lead can be three lines in one text:

kit  = bd ~ sn ~
line = 0 2 4 2
[channel(10, kit), channel(1, line)]

cc sends a controller rather than a note, and a controller value is just a level, so everything you already know about shaping levels shapes it too. A mod wheel swell under a line, in one bar:

line = 0 2 4 2
[line, cc(1, ramp(1, 127, x*16))]

ramp sets the ends, x*16 decides how often a value is sent, and cc(1, ..) says which controller hears it. cc(74, x^100 x^20) puts a filter in two places instead of sweeping; cc(11, channel(3, x*8)) sends expression to channel 3 alone. The Velocity knob is not involved: a controller is a position, not how hard something was hit.

The row of words above the text writes any of these around what you have already written, which is the quickest way to find out what they do.

They are worth most on a name, because then you write the line once:

riff = c3 ~ e3 g3
riff rev(riff) transpose(2, riff) invert(riff)

Change a note in riff and all four bars follow.

They take modifiers like anything else, they nest, and they can sit anywhere a word can: rev(riff)*2, transpose(1, rev(riff)), c3 rev(e3 g3) c4.

Two things they will not do. Drums never transpose: transpose(3, bd sn) is still a kick and a snare, because a kit is a set of sounds and not a scale. And every takes only the verbs that need no number of their own, so every(4, rev, a) works and every(4, transpose, a) does not.

A plain x does transpose, into the note that many steps above the key. It stops being "the key" at that point, which is the price of hearing it move.

The editor helps

It is a language, so the editor is built to spare you having to remember it.

As you type a word, a list appears saying what each choice is: bd is a kick on C1, riff is your own pattern with its first few notes, rev( is the same bar backwards, and c3'maj shows you C3 E3 G3. Up and down to choose, Return or Tab to take one, Escape to dismiss.
Between the brackets of a verb, a panel names each argument and lights the one you are on: off(shift, [change], pattern), with a line saying what that argument is for. It follows you past each comma.
The row of words above the text writes a verb around what you have. Hovering one says what it would do before you press it.
Errors say what to do, not only what is wrong, and name what you probably meant: reverse( suggests rev(, and c3'major suggests c3'maj.
Point at any word and it says what it is, here, in your key: 0 is "degree 2, which is F3 here, counted from the Dm7 under it"; hh is "a hat on F#1, never transposed"; riff shows you your own pattern.
The ? sheet lists the whole language on one page, and clicking any row loads that example.

Everything above answers about the pattern you actually have, through the same path the plugin plays it by, so nothing here can tell you one thing while you hear another.

Where you are

Under the text is one cycle of the pattern. Every pitch that plays gets a row, highest at the top, named down the right side, with the key's own note in amber. A four-note line is four rows. Notes are amber, drums pink, plain hits white; they are brighter for louder, and they light as they fire. The playhead sweeps across, and the four beats of the bar are marked behind.

What you see is what is played, not what you typed. Swing and Drift move the marks off the beat lines exactly as they move the notes, Gate and a note's own :n set how wide each one is, and Humanise varies how bright they are. Turn a knob and the picture answers.

Along the top: what a plain x sounds as and at what level, and on the right, which cycle you are on, which cycle of a longer pattern, when the next evolution lands, and whether a change you typed is waiting for the next bar. When a pattern spans more than one cycle, a row of pips shows which one is playing.

There was a piano roll here, with a row for every semitone between the lowest note and the highest, and notes you could click into the empty ones. The clicking was a second way of saying what the text already says, and the empty rows were most of the window. What is left is the part that was doing the work.

Hearing it

Audition plays the notes on a built-in synth: four sounds under Tone, level under Volume, with the meter in the header.

It has a kit as well as the four tones. Anything arriving on the Drums channel is played as a drum rather than as a pitched note, so bd sn hh oh sounds like a kick, a snare and two hats instead of four low piano notes. The kit follows the General MIDI numbering, so it covers kicks, snares, rims, claps, hats, toms, cymbals, clave, cowbell and shakers.

Playing harder opens the tone as well as raising the level, the way an instrument does, so Velocity and Humanise change how a part sounds and not only how loud it is. Gate now holds the note while it is open rather than letting it fade first, so short and long are audible as articulation.

It is a synth, not a sampler: nothing here is a recording, which is why the whole plugin is still a small download.

It belongs to the standalone application, where nothing follows Refrain. In a host Refrain is a MIDI effect, and a MIDI effect is given no audio at all, by the plugin standards themselves; the instrument after Refrain is what makes the sound there. The toggle is greyed out to say so.

The standalone also opens a virtual MIDI port called Refrain on macOS and Linux. Any synth on the machine can listen to it; the header's status line names it.

An on-screen keyboard appears when Trigger is set to Restart on note or Play the key, because those two read notes and this is how you feed them one without reaching for hardware. Under Free it is not there: anything that sends MIDI already does the same job, and a keyboard you are not using is a sixth of the window saying so.

The controls

Control	What it does
Velocity	the level a plain hit plays at, before its own `^` or `.`
Gate	how much of its step a note holds, before its own `:`
Swing	how much of the Groove to apply. At zero everything sits on the grid
Groove	the feel: where each step of the bar sits, and how hard it is played
Drift	small timing moves. Hold keeps them the same every cycle, vary re-rolls
Humanise	level variation, so a part breathes rather than machine-guns. It follows Drift's hold or vary
Volume	the built-in synth's level
Cycle	how long one pass through the text lasts
Trigger	Free: runs with the transport, and notes you play pass through. Restart on note: a note-on restarts the cycle. Play the key: it also moves the whole pattern to the key you played
Tempo	Host follows your DAW; Manual uses BPM
Evolve	mutate on its own, every so many cycles, exactly on the boundary. It is anchored to the line as you last left it: over hundreds of generations the words stay, the bar keeps its downbeat and its density, and the shape still leans the way you wrote it. It develops the names you define as well as the pattern line, so a text whose music lives in `riff = ...` evolves too, and it never touches `chords` or a verb you wrote

Groove

A groove is a table. For each step of a short repeating window it says how far to move a hit that lands there and how hard to play it, and Swing blends the whole thing in from nothing. Those two rows are everything a feel is made of, which is why there are thirteen of them and adding another is a line of data rather than a change to the plugin.

Groove	What it does
Straight	nothing. Everything on the grid
Swing	the offbeats halfway to the next step. What the knob has always meant
Shuffle	further than swing, and softer on the offbeat
MPC 54, MPC 62	the shallower swings a drum machine offers
Laid back	everything a little behind, more so off the beat
Pushed	everything a little ahead
Backbeat	straight timing, weight on two and four
Downbeat	weight on one
Off the beat	weight between the beats instead of on them
Dilla	late offbeats, an early third, uneven weight
Waltz	three to the bar, weight on the first
Rolling	an eight-step feel that leans further as the bar goes on

Each groove says what its window is measured in. A backbeat is a fact about beats, so it reads one entry per beat; a swing is a fact about the notes between them. Swing, Shuffle and the two machine swings follow whatever the finest subdivision in your bar is, which is what a swing knob has always done.

That is why a timing feel does nothing to a bar of four quarter notes: swing moves what sits between the beats, and there is nothing there. The bar across the top says so when it happens, rather than leaving you turning a knob. The accent grooves work on anything.

Humanise is separate and still random: a groove is a feel you chose, and humanise is the hand that never plays it twice the same.

Buttons

? the notation sheet. Click an example to load it.
Undo steps back through mutations, roll edits, evolutions and presets.

Mutate makes one musical change. Right-click, or use the arrow, to choose the kind. The kind you pick stays picked: the button takes its name, so it always says what pressing it will do, and it keeps doing that until you choose another. Pick Surprise me to go back to any of them. They come in two families.

Rhythm
Push	move a hit off the grid
Fill	turn the end of the bar into a roll
Ghost	sneak a quiet hit into a rest
Roll	ratchet a hit
Space	open a rest where it is busiest
Answer	make the second half reply to the first
Shuffle	move the steps around without changing them

Notes
Transpose	move a run of notes up or down the scale
Invert	turn the line upside down around its own centre
Retrograde	the same notes, in the opposite order
Turn	rotate the notes against the rhythm
Sequence	say a fragment again, a step higher or lower
Smooth	pull the widest leap toward stepwise motion
Ornament	slip a passing note between two notes
Harmonise	add a scale third or sixth under a note

The note family moves pitches along the Scale, so a mutation lands in the key. It leaves the rhythm exactly where it was, and the rhythm family leaves the pitches alone: one axis at a time, unless you ask for Surprise. Drums are never transposed, and no mutation ever puts a word in the line that the line was not already using.

Presets opens the browser: categories on the left, search at the top. The bank is written to teach the language, from First steps to Songs. Save preset... keeps yours; Show folder opens where they live.
MIDI clip drags the pattern into your host as a MIDI clip, or click it to save a .mid file. It goes out on the channels above, so a kit lands on the drum channel.
1 to 8 are pattern slots. Click one to switch at the next bar; whatever you were working on stays in the slot you left. A slot with something in it is drawn brighter, and hovering names it. They are saved with the session. A comment at the top of a slot names it: // verse.
The chain, under the slots, plays them in an order: type 1 1 2 3 and they take a cycle each, switching on the bar like everything else. Leave it empty and the slot you picked keeps playing. Editing while a chain runs edits the slot that is playing.

Dragging a clip in

Drop a .mid file on the window and Refrain reads it as notation. It picks the shortest Cycle that holds the whole clip, and the coarsest grid that still places every note within a quarter step of where it really is, so a simple part comes back as simple text.

Notes on channel 10 come back as drum words. Velocity is set to the clip's usual level and only the notes that disagree carry a level of their own. Gate opens fully, so each note's written length is the whole truth about how long it sounds.

What a clip cannot tell Refrain is how you would have written it: a phrase you typed as x*4 comes back as four hits. It says the same thing.

In a host

Refrain is a MIDI effect: put it before an instrument on the same track, or on its own track routed to one, whichever your host prefers.

Ableton Live: drop Refrain on a MIDI track, then your instrument after it.
Logic Pro: Refrain appears under MIDI FX on an instrument track.
REAPER: put Refrain first in the chain, the instrument after it.
Bitwig, FL Studio, Cubase: a note effect before the instrument.

The pattern is locked to the host's bar, so it lines up with everything else. Typing changes the sound at the next cycle boundary, never mid-bar.

Files

Presets live in Monoglyph Audio/Refrain/Presets under your user data folder, one JSON file each. They are portable: copy them between machines.

Credits

Refrain is by Monoglyph Audio. Its notation is our own parser; the shape of the language follows TidalCycles and Strudel, which are worth your time.