21. The command line and scripts

VI. Reference

The command line and scripts

The studio is one program, studio. Without a command it opens the window; with one, it renders songs, makes songs of synth takes and MIDI files, writes songs as takes, or makes sampler programs of SFZ files, and opens no window. This chapter is every command and option, the window scripts that play the window from a file, the build's steps, the examples in the repository, and what the studio says when it can't do what it's asked. --help prints the commands:

zig build run-studio -- --help

studio --help

Usage:
  studio [SONG | TAKE.txt | --project FILE] [--play BAR] [--cycle FROM TO] [--track N]
         [--view arrange|device|editor|desk] [--no-midi] [--period FRAMES] [--no-audio]
         [--capture IMAGE.png [--capture-at SECONDS] [--capture-size WxH]] [--script FILE] [--log FILE]
         [--ai live|off|replay DIR|record DIR] [--model NAME]
      Open the studio window on a song's folder, a take made into a new song, or
      a new song with one synth on a synth project, and four tracks for its parts.
  studio render SONG OUTPUT.wav [--from BAR] [--to BAR] [--with-reference]
      Render a song to a 32-bit float WAV file. SONG is the song's folder,
      which holds its song.json. The reference track plays only with
      --with-reference.
  studio import TAKE.txt SONG
      Make a new song of a synth take: its project becomes the synth's state,
      and its script the tracks, clips, and lanes of SONG, a new folder.
  studio import SONG.mid SONG
      Make a new song of a Standard MIDI File: a track for each MIDI track and
      channel, channel 10 on a drum machine, and its tempo, key, and markers.
  studio export SONG TAKE.txt
      Write a song on one synth as a take: TAKE.txt, and its project, TAKE.json,
      beside it. `synth render TAKE.txt` plays it as `studio render` plays SONG.
  studio import-sfz INSTRUMENT.sfz PROGRAM.json [--name NAME]
      Make a sampler program of an SFZ multisample in the library folder: its
      regions become keygroups, folded into four velocity zones each.

Options for every command:
  --library DIR       the folder samples are named in (default: library)
  --sample-memory MB  the sample pool's size, which every sampler shares (default: 512)

Options:
  --project FILE      start a new song on a synth project
  --play BAR          play from this bar, counting from 1
  --cycle FROM TO     loop from the start of bar FROM to the start of bar TO
  --track N           select track N, counting from 1
  --view device       show the selected track's device, on its channel
  --view editor       show the selected clip's editor
  --view desk         show the desk: a strip a device, the returns, and the master
  --no-midi           don't listen for MIDI
  --period FRAMES     frames per audio buffer, 32 to 4096 (default 128)
  --no-audio          don't open an audio device; the song still plays in the window
  --capture FILE.png  save a picture of the window, twice the window's size, and quit
  --capture-at SECONDS
                      take it this many seconds into the song (default 0.5)
  --capture-size WxH  the window's size for the picture, or the script (default 1440x900)
  --script FILE      play a script of the window's keys and mouse in a hidden window, and quit:
                      key ctrl+z, down shift, up shift, click PLACE, rclick PLACE, double PLACE,
                      drag PLACE to PLACE, move PLACE, choose ROW, wheel N, type TEXT, paste TEXT,
                      drop FILE PLACE, wait SECONDS, print, capture FILE.png, a step a line; a
                      PLACE is X Y or a name, such as key, record, lane bass bar 9, or inspector role
  --log FILE         write the session's presses as a script's lines, each with what took it
  --ai live           ask TypeSafe's model for the say line, the start line, and the lists'
                      fields, keeping each answer in the cache: the default with a key in
                      TYPESAFE_API_KEY
  --ai off            ask nothing: the default without a key
  --ai replay DIR     answer only from DIR's kept answers, as tests and scripts do
  --ai record DIR     as live, and keep each request and answer in DIR too
  --model NAME        the model's version (default jev-1.13.0)
  --from BAR          render from this bar, counting from 1, as the song stands there
  --to BAR            stop at the start of this bar

zig build builds the studio into zig-out/bin/studio, beside the synth. zig build run-studio -- ARGS builds it and runs it with the arguments after --, from the repository's root, so paths are from there; run zig-out/bin/studio itself to give paths from anywhere else. The library folder, library/ unless --library names another, is found from where the studio runs too.

Opening the window

Without a command, the studio opens its window on what it's given:

Given Opens
nothing a new song: a synth, and four tracks, part 1 to part 4, one on each of its channels, 32 bars long
SONG the song in the folder SONG
TAKE.txt a new song of a synth take, as studio import makes it
--project FILE a new song: a synth on the project, and a track for each of its four parts

A new song has no folder, and its first Ctrl+S asks for one. The studio opens one of the last three at most: a song and --project together are a mistake. A MIDI file opens from a drop on the window, or as studio import makes it; named on the command line, it's read as a folder, and isn't one.

zig build run-studio -- manual/20-files/fields                  # a song
zig build run-studio -- --project examples/parts.json           # a synth project, made a song
zig build run-studio -- take-1.txt                              # a synth take, made a song

Where it starts

These say where the window starts, whatever it opens:

Option Does
--play BAR plays from the start of bar BAR, counting from 1
--cycle FROM TO puts the locators on bars FROM to TO and cycles between them: from the start of FROM to the start of TO
--track N selects track N, counting from 1, or the last if there are fewer
--view VIEW arrange, the default; device, the selected track's device on its channel; editor, the editor for its first notes clip, Key Edit or Drum Edit; or desk
zig build run-studio -- studio/examples/shoreline --play 49 --cycle 49 57   # loop Shoreline's build
zig build run-studio -- manual/20-files/fields --view device --track 3      # the drum machine's panel

Audio and MIDI

Option Does
--no-audio opens no audio device; the window plays the song itself, silently, and the tag under the meter says audio off
--period FRAMES the audio device's buffer, 32 to 4096 frames; 128, the default, is 2.7 ms at 48 kHz
--no-midi opens no MIDI port, so neither a keyboard nor a controller plays the window

Without them, the studio opens the system's audio device at 48 kHz, and a MIDI port, whose address the song's menu shows, as midi 129:0. An audio device that won't open leaves the song playing silently, with no audio device in red under the meter. Chapter 18 connects a controller.

Rendering

zig build run-studio -- render manual/20-files/fields fields.wav
zig build run-studio -- render manual/20-files/fields loop.wav --from 3 --to 5

studio render SONG OUT.wav writes the song to a 32-bit float stereo WAV file at 48 kHz, from bar 1 to the song's end, and says how long it is and how loud it peaks:

fields.wav: 12.255 s, peak -13.6 dBFS
loop.wav: 4.846 s, peak -13.8 dBFS
  • --from BAR starts at bar BAR. The devices play the song silently from its start up to there, so their sequences, rhythms, and controls stand there as they would; notes started before the bar aren't heard, and the delays and reverbs start empty. A bar at or past the song's end is a mistake.
  • --to BAR stops at the start of bar BAR, which comes after --from's; a bar past the end stops at the end. The two bars above take 4.846 s, not 4.8, as the tempo slows in bar 4.
  • --with-reference plays the song's reference track, which a render leaves out otherwise.

A render needs no window or display, and renders the same file every time. Ctrl+Shift+R in the window writes the same file into the song's folder, the bars between the locators while cycle is on.

Takes and the synth

A synth take, the pair of files the synth records, take-1.txt and its project take-1.json, and a song on one synth go either way:

zig-out/bin/studio export studio/examples/phrase phrase.txt   # a song as a take
zig build run -- render phrase.txt phrase.wav                 # which the synth renders as the song
zig-out/bin/studio import phrase.txt my-phrase                # and a take as a song
phrase.txt: 9.600 s
phrase.wav: 9.600 s, 27 events, peak -17.6 dBFS
my-phrase/song.json: 13 notes on 4 tracks

studio export SONG TAKE.txt writes the song as a take, TAKE.txt, and its project beside it, TAKE.json: every event the song plays, on its frame. The project is the synth's state, with the song's first tempo and swing and "clock": "steady", so the synth's clock never restarts, as the song's doesn't; tempo and swing changes come on their frames. synth render plays the take as studio render plays the song, sample for sample: phrase.wav and studio render studio/examples/phrase are the same file. A song that plays more than one device is a mistake. A take holds no desk, so when the desk changes the sound, the synth's strip set anywhere but flat at 0 dB in the middle with no sends, the master fader off 0 dB, or a lane on the strip, the export says studio: the take leaves out the desk: its strip, its returns, and its lanes.

studio import TAKE.txt SONG makes a new song in the folder SONG. The take's project becomes the synth's state, and each part a track with one clip of its notes, their keys paired into lengths, and its chords, pedal, and programs. A patch and a seq play on one frame start a pattern clip, the other seq and set lines become lane points, and the take's tempo and swing changes become the song's points. Frames become positions through the take's own tempo, to the nearest tick, so exporting an imported take moves no event more than half a tick. A take that loaded a sequence from the keys loses those lines, and the import counts them. A folder that holds a song.json already is left as it is, and the import fails. The synth's book teaches takes.

MIDI files

zig-out/bin/studio import song.mid my-song

studio import SONG.mid SONG makes a new song of a Standard MIDI File, as chapter 9 tells: a track for each MIDI track and channel, channel 10 on a drum machine, the rest on synth parts, and the file's tempo map, key signatures, markers, and names. It says how many notes it made on how many tracks, as a take's import does, and on lines after studio:, what didn't fit: the parts left out past a song's 64 tracks on 8 devices, and time signatures other than 4/4, read as 4/4.

The chords the window offers as a draft, when a MIDI file is dropped on it, aren't in a song the command line makes: open it, and find chords in chords ▾ finds them (chapter 9). Nor does the command line ask the model to name what the file left unnamed.

Sampler programs from SFZ

zig-out/bin/studio import-sfz library/SalamanderGrandPianoV3_48khz24bit/SalamanderGrandPianoV3.sfz library/programs/piano.json --name piano

studio import-sfz INSTRUMENT.sfz PROGRAM.json [--name NAME] makes a program file of an SFZ multisample: its regions become keygroups, more than four velocity layers on a key range fold into four zones that crossfade where they overlap, and release triggers, round robins after the first, and the pedal's noises are left out. The SFZ has to be in the library, since the program names its samples by their place there; the program file may go anywhere, but a song finds it only in the library. --name names the program, its file's name without .json otherwise. The command above is how tools/fetch-samples.sh makes the piano, and says:

library/programs/piano.json: 30 keygroups, 120 samples, from 641 regions
studio: folded 30 keygroups' velocity layers into four crossfading zones
studio: left out 161 regions: release triggers, round robins, and the pedal's

The sampler's book plays them.

The library and sample memory

Two options go with every command, before it or after:

Option Does
--library DIR the folder the sampler names its samples in, library by default
--sample-memory MB the pool of sample memory every sampler shares, 1 to 65536 MB, 512 by default

The pool holds every sound the song's samplers load, as 16-bit frames: the Salamander piano's four velocity layers take 303 MB. A song opens before its samples have loaded, and they sound as they arrive; a capture, a script, and a render load them first. Chapter 20 lays out the library.

Pictures

zig-out/bin/studio manual/20-files/fields --view desk --capture desk.png

--capture FILE.png opens the window hidden, draws it offscreen, saves the picture, and quits: twice the window's size, 2880 × 1800 pixels. --capture-at SECONDS takes it that far into the song, 0.5 s by default, playing from where --play puts it, or stopped. --capture-size WxH sets the window's size, from 1280x720 to 3840x2160, 1440x900 by default, for a capture or a script. A capture reads no keys, mouse, or MIDI. With --no-audio, the window renders the song itself, a frame at a time, as fast as it can, so the picture is the same every time: that's how this manual's pictures are made. With an audio device, it plays those seconds aloud. It still needs a display, to open its hidden window.

Window scripts

--script FILE plays a script of the window's keys and mouse in a hidden window, and quits at its end. The song plays on the window's own thread, 60 frames of song a second, as fast as the computer goes, with no audio device, and the same script always plays the same. A script is a step a line, and # starts a comment. This one plays chapter 20's song, mutes its drums, renames its bass, and opens a menu:

wait 0.1
key space                # play from bar 1
wait 2.4                 # a bar at 100 BPM
print                    # where the song is, what plays, the tracks
click mute drums         # the drums' mute, by its track's name
double track bass        # the bass's name, to type a new one
type low
key enter
rclick lane low bar 3    # the menu of its clip at bar 3, at the pointer
wait 0.1
print
capture menu.png         # a picture of the window as it is
The script's picture: the drums muted, the bass renamed `low`, and the menu of its clip at bar 3, with the song playing on in bar 2. The inspector says the clip's notes are linked.: the view
Fig. 21.1 The script's picture: the drums muted, the bass renamed low, and the menu of its clip at bar 3, with the song playing on in bar 2. The inspector says the clip's notes are linked.

scriptzig build run-studio -- manual/20-files/fields --script manual/21-command-line/walk.txt

manual/20-files/fields/song.json
{
  "tempo": ["1 100", "4.3 100 ramp", "5 92"],
  "brief": "a short loop in A minor that slows into a last hit",
  "swing": ["1 50", "3 58"],
  "end": "6",
  "sections": ["1 intro", "3 loop", "5 tail"],
  "key": ["1 A minor"],
  "chords": ["1 Am7", "2 Dm7", "3 Fmaj7", "4 Em7", "4.3 E7", "5 N.C."],
  "devices": [
    {
      "name": "synth",
      "type": "synth",
      "state": {
        "delay_time": "1/8.",
        "reverb_decay": 60,
        "parts": [
          { "patch": "A33", "level": -12, "reverb_send": 30 },
          {
            "patch": { "cutoff": 400, "resonance": 35, "filter_env": 3, "decay": 0.3, "sustain": 30, "release": 0.1 },
            "level": -2
          }
        ]
      }
    },
    {
      "name": "808",
      "type": "drums",
      "state": {
        "accent": 60,
        "program": "1-1A",
        "voices": { "bd": { "decay": 70 }, "sd": { "snappy": 60 } },
        "rhythms": {
          "1-1": { "name": "file beat", "scale": 4, "steps": 16, "flam": 3,
            "A": ["BD x.....x...x.....", "SD ....X.......f...", "CH x.x.x.x.x.x.x.x.", "AC ....x.......x..."] },
          "1-F1": { "scale": 4, "steps": 16, "flam": 3,
            "A": ["BD x.....x.........", "SD ....X...x.xXfXFX", "CH x.x.x.x........."] }
        }
      }
    },
    {
      "name": "S1000",
      "type": "sampler",
      "state": {
        "channels": [{ "channel": 1, "program": 1, "level": -4 }],
        "programs": [
          {
            "program": 1,
            "name": "chops",
            "keygroups": [
              { "keys": "C2", "zones": [{ "sample": "kick" }] },
              { "keys": "D2", "zones": [{ "sample": "snare" }] },
              { "keys": "E2", "zones": [{ "sample": "roll" }] }
            ]
          }
        ],
        "samples": {
          "kick": { "file": "breaks/808.wav", "root": "C2", "end": 12000, "mode": "one_shot" },
          "snare": { "file": "breaks/808.wav", "root": "D2", "start": 30000, "end": 42000, "mode": "one_shot" },
          "roll": { "file": "breaks/808.wav", "root": "E2", "start": 30000, "end": 45000, "mode": "until_release", "loops": ["30000 37500 0 3"] }
        }
      }
    }
  ],
  "desk": {
    "master": 0,
    "delay": { "return": -6, "time": "1/8.", "feedback": 35, "tone": 4000 },
    "reverb": { "return": 0, "decay": 60, "damp": 6000 },
    "strips": {
      "synth": { "level": 0, "pan": 0, "muted": false, "reverb": -18 },
      "808": { "level": -4, "pan": 0, "muted": false, "high_gain": 2 },
      "S1000": { "level": -2, "pan": 10, "muted": false, "delay": -20, "delay_pre": true }
    }
  },
  "tracks": [
    {
      "name": "pad",
      "device": "synth",
      "channel": 1,
      "keys": "chord 7",
      "role": "pad",
      "clips": [{ "at": "1", "length": "5.0.0", "notes": "pad" }],
      "lanes": {
        "chorus": ["1 I", "3 II"]
      }
    },
    {
      "name": "bass",
      "device": "synth",
      "channel": 2,
      "keys": "pent",
      "role": "bass",
      "clips": [
        { "at": "1", "length": "2.0.0", "notes": "bass" },
        { "at": "3", "length": "2.0.0", "notes": "bass" }
      ],
      "lanes": {
        "cutoff": ["1 400", "3 400 exponential", "5 1600"],
        "desk_delay": ["1 -60", "4.3 -60 linear", "5 -14"]
      }
    },
    {
      "name": "drums",
      "device": "808",
      "channel": 1,
      "role": "drums",
      "clips": [
        { "at": "1", "length": "3.0.0", "pattern": "1-1A" },
        { "at": "4", "length": "1.0.0", "pattern": "1-F1A" }
      ]
    },
    {
      "name": "chops",
      "device": "S1000",
      "channel": 1,
      "role": "sample"
    },
    {
      "name": "groups",
      "kind": "groups",
      "clips": [{ "at": "5", "length": "1.0.0", "group": "last hit" }]
    }
  ],
  "notes": {
    "pad": { "length": "5.0.0", "follow": { "pattern": "whole", "low": "F3" } },
    "bass": {
      "length": "2.0.0",
      "notes": [
        "1.1.0 A1 0.0.840 104",
        "1.2.480 A1 0.0.240 80",
        "1.3.0 E2 0.1.0 96",
        "1.4.0 G2 0.0.480 88",
        "2.1.0 D2 0.0.840 104",
        "2.2.480 D2 0.0.240 80",
        "2.3.0 A1 0.1.0 96",
        "2.4.0 C2 0.0.480 88"
      ]
    },
    "crash": {
      "length": "1.0.0",
      "notes": ["1.1.0 C2 0.1.0 120", "1.1.0 Db3 0.1.0 110"]
    },
    "roll": {
      "length": "1.0.0",
      "notes": ["1.1.0 E2 0.2.0 110", "1.3.0 C2 0.1.0 100"]
    }
  },
  "groups": {
    "last hit": {
      "length": "1.0.0",
      "clips": [
        { "track": "drums", "at": "1", "length": "1.0.0", "notes": "crash" },
        { "track": "chops", "at": "1", "length": "1.0.0", "notes": "roll" }
      ]
    }
  },
  "scenes": {
    "F1": ["drums", "groups"],
    "F2": ["pad"]
  }
}
walk.txt
# Plays chapter 20's song, mutes its drums, renames its bass, and opens
# the menu of the bass's second clip, printing what the window shows on
# the way. Run it from the repository's root:
#
#   zig-out/bin/studio manual/20-files/fields --script manual/21-command-line/walk.txt
wait 0.1
key space                # play from bar 1
wait 2.4                 # a bar at 100 BPM
print                    # where the song is, what plays, the tracks
click mute drums         # the drums' mute, by its track's name
double track bass        # the bass's name, to type a new one
type low
key enter
rclick lane low bar 3    # the menu of its clip at bar 3, at the pointer
wait 0.1
print
capture menu.png         # a picture of the window as it is

Its print lines write what the window shows, to standard output:

2.53 s: playing 2.1.53, arrange, locators 1 to 5, track pad (cutoff 580), tool move, sections intro 1, loop 3, tail 5, inspector "pad", brief "a short loop in A minor that slows into a last hit"
  tracks: pad on synth 1 (1 clips); bass on synth 2 (2 clips); drums on 808 1 (2 clips); chops on S1000 1 (0 clips); groups [groups, 1 clips];
  devices: synth (synth); 808 (drums); S1000 (sampler);
2.82 s: playing 2.1.506, arrange, locators 1 to 5, track low (cutoff 400), clip at 3, tool move, modified, sections intro 1, loop 3, tail 5, inspector "clip bass, bars 3 to 4", brief "a short loop in A minor that slows into a last hit", menu clip
  tracks: pad on synth 1 (1 clips); low on synth 2 (2 clips); drums on 808 1 (2 clips) [muted] (channel silent); chops on S1000 1 (0 clips); groups [groups, 1 clips];
  devices: synth (synth); 808 (drums); S1000 (sampler);

A line says the script's time, whether the song plays and where, the view, the locators, the selected track and its device's cutoff, the selected clip, the tool, modified once the song has changed, the sections, and then what's open: a callout's note, the reference's proposal, practice's summary, the inspector's title, F1's screen, a list and how it's ranked, the brief and its goals, a menu and its row lit, and the say line's panel. Under it come the tracks, each on its device and channel, muted or silent or its strip muted, an audio track with its input, and the devices, and in the desk view each strip where it stands.

The steps:

Step Does
wait SECONDS lets the song play, 0 to 3600 s, to the nearest frame
key KEYS presses a key and lets it go: a name, or a chord of up to four, as ctrl+shift+z
down KEY, up KEY holds a key down, or lets it go; mouse is the left button, where the pointer is
click PLACE presses the left button there and lets it go
rclick PLACE the right button there: the menu of what's there
double PLACE clicks twice there, a double-click
drag PLACE to PLACE presses at the first, moves to the second over 8 frames, and lets go; or drag X1 Y1 X2 Y2
move PLACE moves the pointer there
choose WORDS clicks the row of the menu or the list open with these words
wheel N, wheel X Y turns the wheel N notches, up for more than 0 and down for less, or sideways too; 100 at most
type TEXT types what follows, as into a name or a field
paste TEXT puts what follows on the clipboard, \n a line break, and presses Ctrl+V
say TEXT opens the say line, types what follows, and sends it
drop FILE PLACE drops a file on the window there, as from a file manager
print writes a line of what the window shows
capture FILE.png saves a picture of the window as it is, twice its size

Keys are named by their letter or digit, [, ], ;, ', \, -, =, /, or: space, esc, enter, tab, backspace, delete, left, right, up, down, home, end, shift, ctrl, alt, f1 to f12, kp_0 to kp_9, kp_divide, kp_multiply, and kp_enter.

A place is two numbers, X Y in the window's design units, from its top left at the window's size, or a name, which the window finds as it stands when the step plays, so a script by names plays the same at any size. T is a track's name, P a position, as 9 or 9.4.900, and N a number from 1:

Where Names
the bar song; the views, arrange, device, editor, desk; stop, play, record, cycle, click; the locators, left and right; tempo, swing, key, help, meter
the arrange view the headers, snap, sections, chords, numerals; ruler bar P, ruler end, sections bar P, mark bar P (a section's mark), chords bar P, clips bar P; a track's track T, mute T, device T, program T, triangle T, addlane T, lane T bar P, top T bar P (the top of a track's row, where an audio clip's fades are held); a lane's point, point T PARAM bar P, with low or high after it for the lane's bottom or top; below tracks, or below tracks bar P; an empty song's card, card N
the inspector inspector and one of title, plays, role, transpose, level, pan, device, panel, back, next, knob N, follows, grid, edit, try
an editor the header's grid, quantize, clip, length, show, step, practice, exact; edit key, edit drum, edit list; practice's way one key, way wait, way play, way auto; ruler bar P; roll KEY bar P, as roll D2 bar 2.3; drum row N, drum row N grid, drum row N bar P

choose finds a row by its words: a menu's row or its tools, move, cut, glue, erase, or draw; a list's item by its label; the program list's by how it starts; the device list's by a device's name or new synth, new drums, and new sampler; Ctrl+N's by describe, empty, or a template's name; and the list a Drum Edit row's name opens, as every 1/8 or 2 and 4. A device's panel has no names: a step there gives points, as studio/examples/two-loop/build.txt does on the sampler's.

Mistakes stop the script and the studio, with the step's line or what it couldn't find:

studio: bad.txt:2: no such step; see `studio --help`
studio: bad.txt: no such place now: mute horns
studio: bad.txt: no row "insert bars" open now
studio: bad.txt:3: nothing took "low"; did a click miss its field?

The last is a type that nothing in the window took in its frame, which would otherwise land in whatever reads text next. A script, as a capture, takes no MIDI, neither reads nor writes the keys you've used, and answers the model's questions from the cache alone.

--log FILE goes the other way: the window, open as usual, writes each press as a script's line, with a comment saying what took it, and a wait between presses 50 ms or more apart: a click as its point and the area it was in, as clips or the editor's header, and a key as its name and the command it ran, or nothing. Clicks are points, since the log can't know a place's name; replace them with names to make the log a script that survives the window's layout changing.

The model

How the studio asks TypeSafe's model for the say line, the start line, and the lists' fields, chapter 11's words:

Option Does
--ai live sends what the cache doesn't hold, and keeps each answer: the default with a key in TYPESAFE_API_KEY
--ai off asks nothing: the default without a key
--ai replay DIR answers only from the answers kept in DIR, and sends nothing
--ai record DIR as live, and keeps each request and its answer in DIR too
--model NAME the model's version, jev-1.13.0 by default

live and record need a key, and say so without one. A key with spaces inside is no key, and the song's menu says ai: the key has spaces inside. Every answer goes into the cache, named by its request, so a request asked twice is sent once. A script or a capture never waits on the network: it answers from the cache, or with replay from its folder, and a request neither holds has no answer; record waits for each answer, so the script plays the same when it replays. This manual's figures of words replay folders of answers kept beside their chapters, so they build without a key:

zig-out/bin/studio --script studio/examples/words/build.txt --ai replay studio/examples/words/answers

Only words leave the machine: what you typed, and the studio's words for the song a question needs, such as piano: chords, warm, struck. Never audio, a file, or a path. The song's menu shows what the session has asked: its requests, the tokens they sent, and what they cost, at $0.042 a million tokens.

Building

The build's steps, run from the repository's root:

Command Does
zig build builds zig-out/bin/studio and zig-out/bin/synth
zig build run-studio -- ARGS builds the studio and runs it with ARGS, from the repository's root
zig build run -- ARGS the same for the synth, whose book's chapter 16 has its arguments
zig build test runs the tests: the instruments' DSP, the songs, rendering, the window's layout, the model's answers replayed, and the manual's build tool; -Dtest-filter=WORDS runs those whose names hold the words
zig build eval asks the model the labelled cases in studio/evals/, live with a key, keeps the answers in studio/evals/answers/, and writes studio/evals/report.md; -- --replay measures them again offline, from the answers kept
zig build manual builds this manual into zig-out/manual/; -- --chapter 21 builds one chapter, and --no-capture and --no-clips leave the pictures and the clips out
zig build bench times the transport over an hour of song, the synth as a device on Shoreline, a locate's chase, and the sampler's voices

-Doptimize= picks the build mode: ReleaseSafe unless you say otherwise, and Debug for the tests. zig build test replays the model's answers from studio/evals/answers/, so it needs no key.

The examples

Each folder in studio/examples/ is a song, or a script that builds one in the window from nothing. Those that name a sound in the library need tools/fetch-samples.sh first.

Example What it shows
shoreline the synth manual's Shoreline, written by its structure: the synth's slots in synth.json, each section a clip, the theme's chords one set of notes that two clips link, the script's control moves as lanes, an 808 groove in 808.json from the breakdown on, with a fill every eighth bar, and the sea on a sampler, from the library
lantern a smaller four-part piece on two synths, mixed on the desk with EQ and sends, its lead's delay send rising on a lane
phrase a four-bar melody on the synth's slot A63, which tools/fetch-samples.sh renders as loops/phrase.wav
break a two-bar break on the drum machine at 96 BPM, which tools/fetch-samples.sh renders as breaks/808.wav
pads that break on a sampler, to chop across the pads in the sampler's view, from the library
piano the Salamander piano's program file, soft and then loud, from the library
two-loop build.txt builds the song of Alex Rome's two-loop rule, dropping the library's two loops
first-song build.txt builds a first song from the pop template, by ear, with only the keys and the mouse
recreate build.txt recreates Shoreline's start from a render of it dropped as the reference, as chapter 9 does; render its first 32 bars to zig-out/shoreline.wav first
words build.txt builds a song by saying what it should be, replaying the answers in answers/
tape build.txt puts Lantern on tape: its rhythm synth bounced to an audio track, and a render of phrase dropped on another twice, the second fading out; open lantern with it, after rendering phrase to zig-out/phrase.wav
zig build run-studio -- studio/examples/shoreline
zig build run-studio -- studio/examples/pads --view device
zig-out/bin/studio --script studio/examples/first-song/build.txt

The scripts say how to run them in their first lines, and save their songs in zig-out/; all but words export them there too.

Exit statuses and errors

The studio exits with:

Status When
0 it did what it was asked, or --help, which prints to standard output
1 it couldn't, and said why on standard error, after studio:
2 it couldn't read its arguments, and printed the usage on standard error

A song that doesn't open names its file's line, as chapter 20 shows; the rest name what they couldn't do:

studio: manual/20-files/fields ends before bar 7
studio: --to 3 should come after --from 3
studio: --cycle 5 3: the loop ends after it starts
studio: --capture-size 800x600: from 1280x720 to 3840x2160
studio: --ai live needs a key in TYPESAFE_API_KEY
studio: manual/20-files/fields plays more than one device, and a take holds one synth
studio: can't make my-phrase/song.json: PathAlreadyExists
studio: kit.sfz isn't in the library folder library, where the sampler finds its samples
studio: can't open a window. Use `studio render` without a display.

An option the studio doesn't know, a number out of its range for --period or --sample-memory, an unknown view, or a command with the wrong number of files prints the usage and exits with 2.

Next: the synth's book, the synth on its own, and the other instruments: the drum machine and the sampler.