TuningForkComposer

A step sequencer as data. No process, no screen — a struct and pure functions over it, so the same composer can be drawn by a terminal, a notebook or a web page.

def deps do
  [
    {:tuning_fork, "~> 0.1.12"},
    {:tuning_fork_composer, "~> 0.1"}
  ]
end
alias TuningFork.Composer

project =
  Composer.new(bpm: 100)
  |> Composer.add_track(kind: :drum, sound: "kick")
  |> Composer.toggle_step(0, 0)
  |> Composer.toggle_step(0, 4)

Composer.to_source(project)   # Elixir source, as a string
Composer.to_score(project)    # a TuningFork.Score, ready to render
Composer.to_song(project)     # a TuningFork.Song: one section, a stem per track

Modules

Module For
TuningFork.Composer The project struct, and every edit
TuningFork.Composer.Track One row: its instrument and its steps
TuningFork.Composer.Source Writing a project out as Elixir
TuningFork.Composer.Json To and from string-keyed maps, for the wire
TuningFork.Composer.Song Describing the project as a song bundle
TuningFork.Composer.Bake Rendering the bundle's audio and score
TuningFork.Composer.Arrangement A song as tracks of clips placed on bars, with sections and markers
TuningFork.Composer.Arrangement.Clip Notes, steps, a pattern, a Strudel chain, a Sonic Pi loop or a recording
TuningFork.Composer.Arrangement.Track An instrument, its clips, and its level, pan and send
TuningFork.Composer.Arrangement.Json An arrangement to and from JSON-safe maps
TuningFork.Composer.Arrangement.Render A stem per track and the mix
TuningFork.Composer.Arrangement.Bake An arrangement as a song bundle
TuningFork.Composer.Arrangement.Flatten Every clip that can be read as notes, as notes

The grid

meter beats to a bar, division steps to a beat. Width is their product.

Want meter division Steps
the usual 4 4 16
a waltz 3 4 12
triplets 4 3 12
5/4 5 4 20
thirty-seconds 4 8 32

Composer.set(project, :meter, 3) resizes every track for you — grown with rests, or cut short.

Sections

A project with no sections plays its grid bars times. Give it sections and they say how the song is laid out instead: a name, a length in bars, and the tracks that sound in it.

project
|> Composer.add_section("intro", 2, tracks: [0, 1])
|> Composer.add_section("verse", 4)
|> Composer.add_section("chorus", 4)

Composer.sections/1 gives them back, and a project without any is one section named after :name, :bars long, so nothing that reads a project has to special-case the simple one. A track's :plays starts again with each section, so "x." is every other bar of every section it is in; Composer.passes_at/2 is the whole song's on/off string for a track.

Baking writes one sections entry per section, in order, with the times a game cues them by.

Steps

A step is one of three things:

0           # silence
3           # scale degree 3, one step long
{3, 4}      # scale degree 3, held over 4 steps

Read them with Track.read/1, which normalises all three to {degree, length}, and build them with Track.write/2. Degree 1 is the first note of Composer.scale(project).

Writing a front end

Hold a project. Turn input into one call. Draw what comes back.

def handle_event({:cell_clicked, track, step}, state) do
  %{state | project: Composer.toggle_step(state.project, track, step)}
end

def handle_event({:cell_dragged, track, from, to}, state) do
  %{state | project: Composer.set_length(state.project, track, from, to - from + 1)}
end

Every editing function takes a project and returns one. Indices out of range are no-ops, so there is nothing to check before calling.

To draw a row:

track = Composer.track(project, index)
held = Track.held(track)      # [false, true, true, false, ...]

for {step, i} <- Enum.with_index(track.steps) do
  case Track.read(step) do
    {0, _} -> if Enum.at(held, i), do: "held", else: "empty"
    {degree, _} -> "note #{degree}"
  end
end

For menus: Composer.drums/0, Composer.instruments/0, Composer.scales/0, TuningFork.Kit.banks/0 for the :kit setting, and Composer.settings/0 for what set/3 accepts.

A track's :plays says which repeats of the grid it sounds on — "..xx" waits two bars — as a string of x and . cycled over the piece's bars; Composer.passes/2 resolves it, and nil plays them all.

:kit chooses the sounds: :synth is the kit's own drums and TuningFork.Gm synth voices, with nothing to fetch; a drum machine name such as "RolandTR909" plays that machine's recordings and the General MIDI soundfonts, through TuningFork.Kit.instrument/4, fetched the first time they are heard.

Playing and writing

# play what is on screen, without evaluating source
project |> Composer.to_score() |> TuningFork.Score.render(44_100)

# write source that runs on its own
File.write!("song.exs", Composer.to_source(project, output: :wav))

Both skip muted and empty tracks.

Baking a bundle

A bundle is a directory a game reads with tuning_fork alone: the mix, a recording per stem, the score, and the song.json that names them. Nothing is generated at load.

$ mix tuning_fork.bake song.json
test: 2 stems, 1.0s at 44100 Hz -> track/song
{:ok, song} = TuningFork.Composer.Bake.bake(project, "priv/music/night", rate: 48_000)
TuningFork.Song.validate(song, dir: "priv/music/night")   # :ok

Bake at the rate the game plays at, not the one you monitor at: the bundle stores the rate, and a mismatch is resampled at load. score.mid is a format 1 file — a conductor track with the tempo and time signature, then a track per stem, drums on channel 10.

Arrangements

An arrangement is a song laid out on bars rather than repeated from one grid. Each track has an instrument and clips, and each clip starts on a bar and runs for a number of beats. A clip holds notes, drum steps, a pattern on the track's instrument, a Strudel chain, a Sonic Pi loop or a recording.

alias TuningFork.Composer.Arrangement
alias TuningFork.Composer.Arrangement.{Bake, Clip, Track}

arrangement =
  Arrangement.new(
    name: "river",
    bpm: 132,
    sections: [%{name: "road", bar: 1, bars: 8}, %{name: "river", bar: 9, bars: 8}],
    markers: [%{name: "fall", bar: 17, beat: 0.0}],
    tracks: [
      Track.new(
        name: "drums",
        instrument: "kick",
        clips: [Clip.new(kind: :steps, beats: 64.0, steps: %{"kick" => "x...x...", "hat" => "x.x.x.x."})]
      ),
      Track.new(
        name: "bass",
        instrument: "bass",
        gain_db: -2.0,
        clips: [Clip.new(kind: :pattern, beats: 64.0, pattern: "x--.x--.", pitches: [38, 41])]
      ),
      Track.new(
        name: "lead",
        instrument: "gm_flute",
        send: 0.3,
        clips: [
          Clip.new(
            kind: :notes,
            bar: 9,
            beats: 32.0,
            notes: [%{beat: 0.0, pitch: 69, length: 1.0, velocity: 0.8, sound: nil}]
          )
        ]
      ),
      Track.new(
        name: "pad",
        instrument: "strings",
        clips: [Clip.new(kind: :strudel, beats: 80.0, strudel: ~S|note("<[d3,f3,a3] [bb2,d3,f3]>").slow(2)|)]
      )
    ]
  )

{:ok, song} = Bake.bake(arrangement, "priv/music/river", rate: 48_000, playable: ["lead"])

Patterns use the compact notation of TuningFork.Composer.Arrangement.Pattern: x and X accent, o a normal hit, . a rest, - holds, | and spaces are skipped. A pattern on a pitched track plays pitches or chords one per hit, cycling. Steps and patterns repeat to fill their clip, and every note is cut at its clip's end.

The baked bundle has a stem per audible track, the arrangement's sections with their seconds, its markers under "markers", and every stem's notes ("notes") or drum hits ("hits") with their bar and beat, so a game can chart any stem.

TuningFork.Composer.Arrangement.Json writes an arrangement as JSON for other programs, with "format": "tuning_fork.arrangement", and mix tuning_fork.bake bakes such a file:

$ mix tuning_fork.bake river.arrangement.json --rate 48000 --playable lead
river: 4 stems, 36.4s at 48000 Hz -> river

A program that plays notes and nothing else takes TuningFork.Composer.Arrangement.Flatten.with_notes/1, which rewrites steps, patterns and Strudel clips as the notes they play.

Front ends that exist

Package Draws with
tuning_fork_drafter Drafter, in a terminal — mix tuning_fork.compose
tuning_fork_kino Kino, in Livebook — the Compose smart cell