Current section
Files
Jump to
Current section
Files
tuning_fork_composer
README.md
README.md
# 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.
```elixir
def deps do
[
{:tuning_fork, "~> 0.1.12"},
{:tuning_fork_composer, "~> 0.1"}
]
end
```
```elixir
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.
```elixir
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:
```elixir
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.
```elixir
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:
```elixir
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
```elixir
# 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.
```console
$ mix tuning_fork.bake song.json
test: 2 stems, 1.0s at 44100 Hz -> track/song
```
```elixir
{: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.
```elixir
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:
```console
$ 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 |