TuningForkDrafter

Four terminal front ends for tuning_fork, drawn with Drafter.

cd tuning_fork_drafter
mix deps.get                # first time only
mix tuning_fork.live        # live coding patterns, like Strudel
mix tuning_fork.loops       # live coding named loops, like Sonic Pi
mix tuning_fork.compose     # step sequencer, like a drum machine
mix tuning_fork.midi        # a MIDI keyboard in, a pattern out, both on one key strip

Which one

compose is for composing visually rather than by writing code. Notes are placed on a grid with the arrows and the mouse, and nothing has to be typed — which is the whole point of it, not a limitation of it. It writes ordinary TuningFork.Part source out with w, so a tune begun on the grid can be carried on in code by anyone who wants to, but it is a complete way of working on its own.

live and loops are the two live-coding models, for writing music as code. They are genuinely different from each other rather than two skins on one thing:

All three sit on the same core. What a row means is TuningFork.Session, what it draws is TuningFork.Session.View, and what it plays through is TuningFork.Stage — none of that lives here.

Live coding

mix tuning_fork.live
mix tuning_fork.live --cps 0.75
mix tuning_fork.live --pattern "bd*4" --pattern "hh*8?"

One mini-notation (TuningFork.Pattern.Mini) pattern a row, as many rows as you write. Ctrl+E and it takes over at the next cycle line — nothing stops.

Live
▶  cycle 12.44 · 0.50 cps · 4 on

1 ▸ s("bd!4") |> scope()
2   hh*8?0.2
3   ~ [cp] ~ cp
4   n("<0 [4] 0 9 7>*16")
5   |> scale("g:minor") |> transpose(-12) |> shape(:saw)
6   |> cutoff(220) |> resonance(16)
7   |> lpenv(2.7) |> lpsustain(0.1) |> lpdecay(0.14)
8   |> pianoroll()

Enter breaks a line in two, so a chain is written down the screen — a row starting |> carries on the one above it. Backspace at the start of a line joins it back. There is no row count to run out of.

The token sounding right now is bracketed — ~ [cp] ~ cp, <0 [4] 0 9 7> — on every row, following <> alternation and *n as the pattern engine plays them.

A row draws nothing unless it asks. End a chain with pianoroll() or scope(). A scope traces the row it is written under, rendered from that row alone rather than read off the speakers. In a pianoroll the note sounding is drawn hollow.

--, // or _ in front of a line parks it. Tab puts a marker on and takes off whichever of the three is there. A parked line is not played, not drawn and not checked, so a half-written one sitting behind an _ never reports anything.

Press ? for the sound names — every drum the kit knows, how to write notes, the whole notation and the keys, generated from the kit itself so it cannot drift.

Sound names

? in the app is the live list. In code it is TuningFork.Kit:

TuningFork.Kit.drums()      # every drum name
TuningFork.Kit.families()   # the same, grouped by kind
TuningFork.Kit.notes()      # c0 to b8

bd:3 shifts a drum's pitch. Notes are a letter, s for sharp or b for flat, and an octave — c3, fs4, eb2. A whole number is a MIDI note (69 is a4); a number with a decimal point is hertz (440.0).

A slot that will not parse says why underneath and keeps playing what it played before, so a half-typed edit never drops out.

Slots holding a piece from strudel.cc — $: rows, method chains, let variables, setcps, samples('github:…') — play as written, and evaluating takes the tempo the piece sets. An error lands on the line it came from. See TuningFork.Strudel for what is read.

Drawing

Where the terminal has a pixel protocol — kitty, iTerm2 or sixel — each row draws a pianoroll through french_curve. Everywhere else it draws blocks. --text forces blocks.

An image per row per frame is what makes a terminal flicker, so:

• paused, nothing is redrawn at all — Ctrl+P is for the quiet screen as much as the quiet speakers
• pictures are rebuilt on a 100 ms clock, not every frame, in a process of their own so that building them never sits between a keystroke and the screen
• only rows that ask get one — pianoroll() or scope() on the end of a chain

If it still flickers on your terminal, --text is always steady.

When the pictures do not keep up

A terminal app cannot print — the screen belongs to the drawing — so it writes a trace instead:

TUNING_FORK_TRACE=/tmp/live.log mix tuning_fork.live

Every tick logs the cycle it read and whether the last frame was still being built; every frame logs how long it waited and how long it took. A tick logging drawing=true was dropped, which is what to look for.

MIDI

mix tuning_fork.midi
mix tuning_fork.midi --voice gm_epiano1 --pattern 's("bd*4, hh*8")'

i and o walk the inputs and outputs the machine has, ending on a virtual port of the app's own that other software sees by name. Keys played on the input sound on this machine with the instrument v picks and light the strip blue; p plays the pattern out of the output with MIDI clock and lights what it sends yellow; ← → and enter send one key. e edits the pattern — one expression, as a row of mix tuning_fork.live is; + and - set the cycles per second; the log under the strip shows both streams. With no device at all, open the two virtual ports and point a soft synth at "TuningFork Out".

Named loops

mix tuning_fork.loops
mix tuning_fork.loops --loop 'drums=part(bpm: 120, synth: Kit.voice("bd", 0.3)) |> play(:c3, 1)'

Each loop is a block of Elixir, written either with TuningFork.Part — a cursor moving through beats, where play sounds a note and moves on — or in Sonic Pi's words, where play and sample sound at the cursor and sleep moves it:

bells   use_bpm 120
        sample :perc_bell, rate: rrand(0.125, 1.5)
        sleep rrand(0.5, 2)

acid    use_synth :tb303
        with_fx :reverb, mix: 0.3 do
          times 16 do
            play choose(chord(:e3, :minor)), release: 0.1, cutoff: rrand_i(50, 90)
            sleep 0.125
          end
        end

A Part pipeline must come to a Score or a Part; a Sonic Pi block is the round it played, as long as its sleeps. ? lists both vocabularies. Sample names need the tuning_fork_samples package, which this one lists as an optional dependency.

Loops
▶  2 loops

drums ▸ part(bpm: 120, synth: Kit.voice("bd", 0.3))
        |> play(:c3, 1) |> play(:c3, 1)
        round 7 · beat 1.5

bass    part(bpm: 120, synth: Kit.voice(%{note: "c2", shape: :saw}, 0.4))
        |> play(:c2, 2) |> play(:g2, 2)
        round 3 · beat 0.5 · waiting

Ctrl+E takes over when that loop comes round — not at some shared cycle line, so a four-beat loop and a three-beat one each land on their own downbeat. waiting marks a loop holding an edit until it gets there. Ctrl+R swaps on the next chunk instead.

Broken source changes nothing. The reason appears under the loop and whatever was last evaluated keeps playing, because the app never hands the stage a score that would not build.

Step sequencer

A step sequencer in a terminal, drawn with Drafter over TuningFork.Composer (tuning_fork_composer).

For composing by ear and by eye rather than by writing code. Notes go on the grid with the arrows, the mouse and the space bar; nothing is typed and nothing has to be learnt about patterns, cycles or the DSL. w writes the tune out as ordinary source if you ever want it in code, but you never have to.

mix tuning_fork.compose

Compose
96 bpm · 2 bars · 4/4 · a2 minor_pentatonic · gain 0.5
             1           2           3           4
▸ kick      [█] ·  ·  ·  █  ·  ·  ·  █  ·  ·  ·  █  ·  ·  ·
  snare      ·  ·  ·  ·  █  ·  ·  ·  ·  ·  ·  ·  █  ·  ·  ·
  hat        █  ·  █  ·  █  ·  █  ·  █  ·  █  ·  █  ·  █  ·
  bass       1  ·  ·  ·  1  ▬  ▬  ·  4  ·  ·  ·  3  ·  ·  ·

▸ marks the row, [ ] the step. █ a drum hit, a digit a scale degree, ▬ a note held from earlier, · silence. Dimmed rows are muted.

Mouse

Keys

Options

mix tuning_fork.compose --bpm 120 --bars 4 --meter 3 --division 8
mix tuning_fork.compose --empty --out beat.exs

What w writes

Ordinary TuningFork.Part source, ending in a Wav.write!. Run it anywhere:

mix run song.exs      # writes song.wav

Nothing of this package appears in it.

Playing

p starts, p again stops — only ever one at a time, and quitting stops it too.

The grid loops live on a stage, one repeat at a time: each repeat is built from the grid as it stands when that repeat comes round, so an edit is heard at the next repeat, and the settings line says which repeat is sounding.

p needs tuning_fork_speaker, which is an optional dependency. Without it the editor still runs and still writes source — it just says so instead of playing.

Using it from your own project

Rather than cd-ing here, add it as a dependency and the task comes with it:

{:tuning_fork_drafter, "~> 0.1"}

Then mix tuning_fork.compose works from your project, and --out writes beside your code.

Notes on Drafter

Facts that are not obvious from its docs, kept here because this app depends on them:

• Props go under :props — Drafter.run(App, props: %{project: p}). Anything at the top level of the options is silently ignored, so passing project: directly means mount/1 gets %{} with no error anywhere
• mount/1 receives props as a map, not a keyword list
• Mouse events are {:mouse, %{type: type, x: x, y: y, button: _, mods: _}} — type, not action, whatever Drafter.Event.mouse/4 suggests
• type is :mouse_down, :mouse_up, :move or :scroll; :scroll also carries :direction
• x and y are zero-based from the top left
• Key events are {:key, :q}, {:key, :left}, {:key, :+} — the character as an atom
• update/2 returns the new state, or {:stop, reason} to quit
• Widget helpers used here: vertical/2, label/2, header/1, footer/1