<!-- GENERATED by starlens/site/tools/reference_pages.py from the engine's sources: do not edit; run it. -->

[[nav: reference | here=verbs]]

<div class="doc">

<!-- GENERATED by love-shared/scripts/verb_sheet.py from the app's registry (scripts/verb_inventory.lua): do not edit; run it. -->

# startune · the verbs

<p class="plain"><a href="../../verbs/startune.md">this page as plaintext</a></p>

*The DAW: the song, its tracks and clips, the transport, the terminal. 239 verbs in 31 categories: 74 undoable, 67 read-only. The app-verbs protocol (`love-shared/docs/app-verbs.md`): `staros-tap startune verbs` lists them live, `staros-tap startune verb <name> '<json>'` runs one, `activity --since N` reads the journal. Loaded headless from `startune/daw-app` by `scripts/verb_inventory.lua`.*

## app

### `app.quit` — medium

Quit startune. Refuses with unsaved changes unless force=true.

| argument | type | notes |
|---|---|---|
| `force` | boolean |  |

    staros-tap startune verb app.quit '{}'

## audio

### `audio.buffer` — low, read-only

Reopen the output with a fixed device buffer in frames (64, 128, 256, 512 ...; smaller is a shorter key-to-sound delay and a busier callback), or 0 for the device's own. Remembered on this machine; one that never chose opens at 128. Read audio.state after: buffer_frames, xruns, cb_load_pct.

| argument | type | notes |
|---|---|---|
| `frames` | integer | required; minimum 0; maximum 4096; frames per buffer; 0: the device's own |

    staros-tap startune verb audio.buffer '{"frames": 0}'

### `audio.state` — low, read-only

The audio device as the engine runs it: sample rate, the device buffer (frames and ms), key_latency_ms (a live MIDI note's timestamp to its frame reaching the device: constant), the callback's load (% of its buffer's time), xruns, and live notes placed / late / dropped.

    staros-tap startune verb audio.state '{}'

### `click.follow` — low, read-only

The click follows the player (on; absent: toggles): it ticks the beat it hears in the live strikes (keys, pads) instead of the song's pattern, wherever the transport is. Each tick lands where a strike on that beat is heard: on the beat itself while the instrument sounds the keys (the piano's own monitor, echo), the key-to-device delay after while startune sounds them. It joins once it has locked and stops eight beats after the player does (daw-core beat_follow.rs; the phone PULSE's twin). Sounds through the monitor (click.on); a count-in still counts the song's. Remembered on this machine; never the song's. `heard`: what it hears, as of the last frame.

| argument | type | notes |
|---|---|---|
| `on` | boolean |  |

    staros-tap startune verb click.follow '{}'

### `click.join` — low, undoable

The song joins the player (the browser toy's join, in the DAW): once the click following them (click.follow) has locked, the song takes their tempo, fitted to their last strikes (`heard.fit_bpm`; daw-core FollowClick::join_at), and starts from the loop's start (or the playhead) on the frame where their next beat is heard: a silent count of exactly the frames until then, the click ticking through it. A song with audio clips keeps its tempo (they are placed in frames): it starts on the beat at its own. The tempo is one undo step; refused until the click has locked.

    staros-tap startune verb click.join '{}'

### `click.on` — low, read-only

This machine's click monitor: on (absent: toggles) and db (-60 to 12, the level; 0 by default). The click ticks the song's pattern while it plays, and its count-in before it starts. Remembered on this machine; never the song's.

| argument | type | notes |
|---|---|---|
| `db` | number | minimum -60; maximum 12 |
| `on` | boolean |  |

    staros-tap startune verb click.on '{}'

## automation

### `automation.bypass` — low, undoable

Switch a lane off (kept and drawn, not played) or back on; toggles without `off`.

| argument | type | notes |
|---|---|---|
| `off` | boolean |  |
| `target` | string | required; one of gain, volume, pan, send0, reverb, send1, delay; gain (= volume), pan, send0 (= reverb), send1 (= delay). |
| `track` | any | required; Track id (integer) or its exact name. |

    staros-tap startune verb automation.bypass '{"track": "…", "target": "gain"}'

### `automation.clear` — low, undoable

Remove a track's automation lane for one target; the fader value plays again.

| argument | type | notes |
|---|---|---|
| `target` | string | required; one of gain, volume, pan, send0, reverb, send1, delay; gain (= volume), pan, send0 (= reverb), send1 (= delay). |
| `track` | any | required; Track id (integer) or its exact name. |

    staros-tap startune verb automation.clear '{"track": "…", "target": "gain"}'

### `automation.fade` — low, undoable, palette word `fade`

Fade a track's volume (or a send) between two bars, ending at to_db (-120 = silence). It starts from from_db, or from whatever the level is at from_bar. The curve defaults to one that sounds even: ease_out_quad going down, ease_in_quad going up. Replaces what the lane did between the two bars.

| argument | type | notes |
|---|---|---|
| `curve` | string | one of linear, ease_in_quad, ease_out_quad, ease_in_cubic, ease_out_cubic, ease_in_out_cubic, ease_out_quart, ease_out_back, ease_out_elastic |
| `from_bar` | number | required; minimum 1 |
| `from_db` | number |  |
| `target` | string | one of gain, volume, send0, reverb, send1, delay |
| `to_bar` | number | required; minimum 1 |
| `to_db` | number | required |
| `track` | any | required; Track id (integer) or its exact name. |

    staros-tap startune verb automation.fade '{"track": "…", "from_bar": 0, "to_bar": 0, "to_db": 0}'

### `automation.list` — low, read-only

Every automation lane (or one track's): points in bars, gain and sends also in dB.

| argument | type | notes |
|---|---|---|
| `track` | any | Track id (integer) or its exact name. |

    staros-tap startune verb automation.list '{}'

### `automation.point` — low, undoable, palette word `auto`

Add one automation point, or change the one at exactly that bar (its easing is kept unless you give one).

| argument | type | notes |
|---|---|---|
| `at_bar` | number | required; minimum 1 |
| `db` | number |  |
| `easing` | any | Shape of the segment this point STARTS: a curve name (linear, ease_in_quad, ease_out_quad, ease_in_cubic, ease_out_cubic, ease_in_out_cubic, ease_out_quart, ease_out_back, ease_out_elastic) or {"kind":"bezier","cp1":[x,y],"cp2":[x,y]}. |
| `target` | string | required; one of gain, volume, pan, send0, reverb, send1, delay; gain (= volume), pan, send0 (= reverb), send1 (= delay). |
| `track` | any | required; Track id (integer) or its exact name. |
| `value` | number |  |

    staros-tap startune verb automation.point '{"track": "…", "target": "gain", "at_bar": 0}'

### `automation.set` — low, undoable

Draw a whole automation lane on a track -- its gain, pan or a send -- as points (bar + value or db, optional easing). While it plays, the lane overrides the fader or knob. Replaces the lane.

| argument | type | notes |
|---|---|---|
| `interp` | string | one of linear, step, smooth |
| `off` | boolean | Keep the lane switched off (drawn, not played). |
| `points` | array | required |
| `target` | string | required; one of gain, volume, pan, send0, reverb, send1, delay; gain (= volume), pan, send0 (= reverb), send1 (= delay). |
| `track` | any | required; Track id (integer) or its exact name. |

    staros-tap startune verb automation.set '{"track": "…", "target": "gain", "points": []}'

## chop

### `chop.slice` — low, undoable

Cut a media into the pads of a track (Chop's T / G): at its transients (mode transient, sensitivity sigma 0.6-4, lower = more cuts) or into n even slices (mode grid), over the whole media or from_s..to_s of it. The first 16 slices go on pads 0-15.

| argument | type | notes |
|---|---|---|
| `from_s` | number | minimum 0 |
| `media` | integer | required |
| `mode` | string | one of transient, grid |
| `n` | integer | minimum 2; maximum 64 |
| `sigma` | number | minimum 0.6; maximum 4 |
| `to_s` | number | minimum 0 |
| `track` | any | required; Track id (integer) or its exact name. |

    staros-tap startune verb chop.slice '{"track": "…", "media": 0}'

### `chop.step` — low, undoable

Toggle one step of a track's 16-step loop (Chop's step row): pad 0-15, step 0-15 (16ths of a 4-beat bar). on = true / false sets it instead of toggling.

| argument | type | notes |
|---|---|---|
| `on` | boolean |  |
| `pad` | integer | required; minimum 0; maximum 15 |
| `step` | integer | required; minimum 0; maximum 15 |
| `track` | any | required; Track id (integer) or its exact name. |

    staros-tap startune verb chop.step '{"track": "…", "pad": 0, "step": 0}'

## clip

### `clip.add` — low, undoable

Place a media item on a track; returns the new clip id. Length defaults to the whole media.

| argument | type | notes |
|---|---|---|
| `at_bar` | number | minimum 1 |
| `frame` | integer | minimum 0 |
| `gain` | number | minimum 0; maximum 4 |
| `len_bars` | number | minimum 0 |
| `len_frames` | integer | minimum 1 |
| `media` | integer | required; minimum 0; media id (see media.list) |
| `src_offset` | integer | minimum 0; media frames to skip |
| `track` | any | required; Track id (integer) or its exact name. |

    staros-tap startune verb clip.add '{"track": "…", "media": 0}'

### `clip.move` — low, undoable

Move a clip to a bar (or frame), optionally onto another track.

| argument | type | notes |
|---|---|---|
| `clip` | integer | required |
| `frame` | integer | minimum 0 |
| `to_bar` | number | minimum 1 |
| `to_track` | any | Track id (integer) or its exact name. |
| `track` | any | required; Track id (integer) or its exact name. |

    staros-tap startune verb clip.move '{"track": "…", "clip": 0}'

### `clip.remove` — low, undoable

Remove a clip.

| argument | type | notes |
|---|---|---|
| `clip` | integer | required |
| `track` | any | required; Track id (integer) or its exact name. |

    staros-tap startune verb clip.remove '{"track": "…", "clip": 0}'

### `clip.set` — low, undoable

Set a clip's gain (1 = unity), pitch in semitones, or fades in frames.

| argument | type | notes |
|---|---|---|
| `clip` | integer | required |
| `fade_in` | integer | minimum 0 |
| `fade_out` | integer | minimum 0 |
| `gain` | number | minimum 0; maximum 4 |
| `pitch_st` | number | minimum -48; maximum 48 |
| `track` | any | required; Track id (integer) or its exact name. |

    staros-tap startune verb clip.set '{"track": "…", "clip": 0}'

### `clip.split` — low, undoable, palette word `split`

Split a clip at a bar (or frame); returns the id of the right half.

| argument | type | notes |
|---|---|---|
| `at_bar` | number | minimum 1 |
| `clip` | integer | required |
| `frame` | integer | minimum 0 |
| `track` | any | required; Track id (integer) or its exact name. |

    staros-tap startune verb clip.split '{"track": "…", "clip": 0}'

### `clip.trim` — low, undoable

Set a clip's absolute start frame, source offset (media frames) and length.

| argument | type | notes |
|---|---|---|
| `clip` | integer | required |
| `len` | integer | required; minimum 1 |
| `src_offset` | integer | required; minimum 0 |
| `start_frame` | integer | required; minimum 0 |
| `track` | any | required; Track id (integer) or its exact name. |

    staros-tap startune verb clip.trim '{"track": "…", "clip": 0, "start_frame": 0, "src_offset": 0, "len": 0}'

## decks

### `deck.cue` — low

Jump a deck to its cue point, keeping its play state (Q / O); set = true sets the cue at the deck's position instead (Shift+Q / Shift+O). Playing on a sure grid, the jump waits for the next beat and is taken there to the sample (quant: beats; 0 = at once), with a 2 ms crossfade.

| argument | type | notes |
|---|---|---|
| `at_beat` | number | minimum 0; the deck's beat the press meant (its grid) |
| `deck` | string | required; one of A, B; The deck, A or B. |
| `quant` | number | minimum 0; maximum 16 |
| `set` | boolean |  |

    staros-tap startune verb deck.cue '{"deck": "A"}'

### `deck.hotcue` — low

Jump a deck to hot cue n (1-8; the view's 1-4 / 7-0 keys). set = true stores the deck's position as that hot cue (Shift), on the grid's nearest beat when the grid is sure (snap); clear = true forgets it. Playing on a sure grid, the jump waits for the next beat and is taken there to the sample (quant: beats; 0 = at once), so the beat goes on; paused, a hot cue plays from where it is.

| argument | type | notes |
|---|---|---|
| `at_beat` | number | minimum 0; the deck's beat the press meant (its grid) |
| `clear` | boolean |  |
| `deck` | string | required; one of A, B; The deck, A or B. |
| `n` | integer | required; minimum 1; maximum 8 |
| `quant` | number | minimum 0; maximum 16 |
| `set` | boolean |  |
| `snap` | boolean |  |

    staros-tap startune verb deck.hotcue '{"deck": "A", "n": 0}'

### `deck.keylock` — low

Keylock on a deck (V / N): the key stays put while the pitch fader moves the tempo (the WSOLA stretcher). With no `on`, toggles.

| argument | type | notes |
|---|---|---|
| `deck` | string | required; one of A, B; The deck, A or B. |
| `on` | boolean |  |

    staros-tap startune verb deck.keylock '{"deck": "A"}'

### `deck.load` — low

Load audio onto deck A or B (the library's D / B), at its detected BPM unless bpm says otherwise. Any source: media, hash (a take in the sample library), sound, path, crate (an entry of crate.list); one the song does not have is loaded first (the reply says importing). A long media (a minute or more: streamed) is read whole off the UI thread (loading = true; the deck's commands wait behind the load, in order). Either way deck_loaded (or deck_load_failed) lands in activity when it is more than at once.

| argument | type | notes |
|---|---|---|
| `bpm` | number | minimum 20; maximum 400 |
| `crate` | string | an entry of crate.list, by its key |
| `deck` | string | required; one of A, B |
| `hash` | string | a take in the sample library, by its content hash (crate.list) |
| `media` | integer | minimum 0; a media this song has loaded (media.list) |
| `path` | string | a file (wav, flac, mp3, ogg, m4a); never from a device |
| `sound` | string | a sound in this machine's sound store, by its sha16 |

    staros-tap startune verb deck.load '{"deck": "A"}'

### `deck.loop` — low

A deck's loop (L / K / J): op `in` marks the loop's start at the deck's position, `out` its end (and the loop runs), `exit` leaves it; or beats (1/8 to 32) loops that many beats on the grid from its beat at or before the playhead (a loop's wrap is taken to the sample, with a 2 ms crossfade).

| argument | type | notes |
|---|---|---|
| `at_beat` | number | minimum 0; the beat the loop starts on (its grid) |
| `beats` | number | minimum 0.125; maximum 32 |
| `deck` | string | required; one of A, B; The deck, A or B. |
| `op` | string | one of in, out, exit |

    staros-tap startune verb deck.loop '{"deck": "A"}'

### `deck.nudge` — low

Bend a deck's rate for a moment to line its beats up (the view's E / R): dir slower or faster (2%), or an exact ratio; ms = how long (default 250).

| argument | type | notes |
|---|---|---|
| `deck` | string | required; one of A, B; The deck, A or B. |
| `dir` | string | one of slower, faster |
| `ms` | number | minimum 1; maximum 5000 |
| `ratio` | number | minimum 0.5; maximum 2 |

    staros-tap startune verb deck.nudge '{"deck": "A"}'

### `deck.pitch` — low

The deck's pitch fader, in percent: pct sets it (0 = the track's own tempo), delta moves it from where it is (the view's T / G step 0.5). Keylock holds the key while it moves.

| argument | type | notes |
|---|---|---|
| `deck` | string | required; one of A, B; The deck, A or B. |
| `delta` | number | minimum -50; maximum 50 |
| `pct` | number | minimum -50; maximum 50 |

    staros-tap startune verb deck.pitch '{"deck": "A"}'

### `deck.play` — low

Play or pause a deck (the Decks view's W / P). With no `on`, toggles: a playing deck pauses, a paused one plays. Nothing to undo: performance state.

| argument | type | notes |
|---|---|---|
| `deck` | string | required; one of A, B; The deck, A or B. |
| `on` | boolean |  |

    staros-tap startune verb deck.play '{"deck": "A"}'

### `deck.seek` — low

Move a deck to a time in its track, in seconds.

| argument | type | notes |
|---|---|---|
| `deck` | string | required; one of A, B; The deck, A or B. |
| `sec` | number | required; minimum 0 |

    staros-tap startune verb deck.seek '{"deck": "A", "sec": 0}'

### `deck.state` — low, read-only

What the decks are doing now: loaded, playing, keylock, loop, synced, pitch_pct, bpm, position_sec, beat_phase (0-1), the loop's seconds. One deck, or both.

| argument | type | notes |
|---|---|---|
| `deck` | string | one of A, B; The deck, A or B. |

    staros-tap startune verb deck.state '{}'

### `deck.sync` — low

SYNC a deck to the other: it takes the other's tempo (its pitch set every block, at half or double tempo when that is nearer, within the fader's 50%) and, at its next beat, the other's beat phase as heard (keylock's delay counted). Both decks need a sure beat grid (force = true goes without). With no `on`, toggles. Both synced: B follows A.

| argument | type | notes |
|---|---|---|
| `deck` | string | required; one of A, B; The deck, A or B. |
| `force` | boolean |  |
| `on` | boolean |  |

    staros-tap startune verb deck.sync '{"deck": "A"}'

### `mix.set` — low

The DJ mixer: fader_a / fader_b are the decks' levels (0-1.25, 1 = unity), crossfader runs -1 (all A) through 0 (both, constant power) to 1 (all B); the Decks view's Z / X / C and its drag. Any one or more.

| argument | type | notes |
|---|---|---|
| `crossfader` | number | minimum -1; maximum 1 |
| `fader_a` | number | minimum 0; maximum 1.25 |
| `fader_b` | number | minimum 0; maximum 1.25 |

    staros-tap startune verb mix.set '{}'

## drill

### `drill.again` — low

The drill's step from the top (the keys must be played again).

    staros-tap startune verb drill.again '{}'

### `drill.back` — low

Back a step in the drill (played again; its first result kept in the record).

    staros-tap startune verb drill.back '{}'

### `drill.end` — low

End the drill: its record written to the save dir's drills/ (what was asked, what was played at each right, how long, the tally, the span of this machine's keys log). keep = true also keeps the chords played into the song as a layer (midi.keep over the drill's span); never by default.

| argument | type | notes |
|---|---|---|
| `keep` | boolean |  |

    staros-tap startune verb drill.end '{}'

### `drill.list` — low, read-only

The drills: fifths (a stack of fifths, grown a fifth a step from the bass, or walk = true: slid round the circle), circle (the roots round the circle of fifths, each chord voiced from the last by the least motion, or in an inversion), inversions (a chord rotated up the keyboard), plan (the song's chord plan, from_bar..to_bar); each with what it takes.

    staros-tap startune verb drill.list '{}'

### `drill.show` — low

Show or hide the drill's names (the targets' chord names and labels): hidden, the keys are marked and nothing is named until the hands have found it. With no names given, the other way.

| argument | type | notes |
|---|---|---|
| `names` | boolean |  |

    staros-tap startune verb drill.show '{}'

### `drill.skip` — low

Past the drill's step, counted as skipped ("next chord").

    staros-tap startune verb drill.skip '{}'

### `drill.start` — low, palette word `drill`

Start a drill at the keys (the Drill room: Ctrl/Cmd+7): its steps shown on the Piano tab, the compass and the Fretboard (in the song's tuning), each judged when the keys stand still, the next shown when it is right. fifths {root, n 2-6, grow, walk, steps}; circle {start, dir up|down, quality maj|min|7|maj7|m7, steps, voice nearest|root|first|second|third}; inversions {chord}; plan {from_bar, to_bar}. A root or start is a note's name (C, F#, Bb) or a pitch class. One drill at a time: a new one replaces it.

| argument | type | notes |
|---|---|---|
| `chord` | string | inversions: C, Am, G7, Fmaj7, Bm7... |
| `dir` | string | one of up, down |
| `drill` | string | required; one of fifths, circle, inversions, plan |
| `from_bar` | number | minimum 1 |
| `grow` | boolean |  |
| `n` | integer | minimum 2; maximum 6 |
| `quality` | string | one of maj, min, 7, maj7, m7, dim, sus2, sus4 |
| `root` | any | fifths: the stack's root |
| `start` | any | circle: the first root |
| `steps` | integer | minimum 1; maximum 24 |
| `to_bar` | number | minimum 1 |
| `voice` | string | one of nearest, root, first, second, third |
| `walk` | boolean |  |

    staros-tap startune verb drill.start '{"drill": "fifths"}'

### `drill.state` — low, read-only

The drill running: its step, what to play (the keys; its name and label unless hidden), what the hands were told (right, or what to add, what not, where the bass goes), the tally, the keys held.

    staros-tap startune verb drill.state '{}'

## edit

### `edit.redo` — low, palette word `redo`

Redo the last undone edit.

    staros-tap startune verb edit.redo '{}'

### `edit.undo` — low, palette word `undo`

Undo the last edit (the user's or an agent's).

    staros-tap startune verb edit.undo '{}'

## guide

### `guide.clear` — low

Take the guide's line away, its pointing, or both (what: line | points; both by default).

| argument | type | notes |
|---|---|---|
| `what` | string | one of line, points |

    staros-tap startune verb guide.clear '{}'

### `guide.point` — low, palette word `point`

Make something on screen pulse for a few seconds, so the person sees where to look or click. target is kind:key: room:<id> (a room chip on the strip), section:<name>[#n] (a section on the strip), bar:<n> or chord:<n> (a chord chip on the strip), checklist:<stage>:<i> (an item on the card, in that stage's room), field:<prose|nouns|verbs|sentence> (the Words card), machine:<n> (the Seed card), layer:<name> (a bench lane), remote:<prev|play|next|take|keep|notes|locked> (the phone). label: a few words beside it. Show the room first (ui.room) when the target lives in another. A target under the console puts the console away (unless the person is typing in it).

| argument | type | notes |
|---|---|---|
| `label` | string |  |
| `secs` | number | minimum 1; maximum 60 |
| `target` | string | required |

    staros-tap startune verb guide.point '{"target": "…"}'

### `guide.say` — low, palette word `say`

Say one line to the person, in the app: on the card (the writing rooms' left pane), else the status bar, and on the phone's remote. Short (at most 240 characters): what to do next, or a question. tone: info (default), ask (waiting on the person), done (a step finished). It stays until the next line, guide.clear, `secs`, or the person clicks it away. Never an undo step.

| argument | type | notes |
|---|---|---|
| `secs` | number | minimum 1; maximum 3600 |
| `text` | string | required |
| `tone` | string | one of info, ask, done |

    staros-tap startune verb guide.say '{"text": "…"}'

### `guide.state` — low, read-only

What the guide is saying and pointing at now, and whether each target was on screen.

    staros-tap startune verb guide.state '{}'

## instrument

### `instrument.info` — low, read-only

A track's instrument in full: its envelope (attack, decay, sustain, release), mono or not, and each zone (the keys and velocities it plays, its root, tune, gain, length and loop). Without track: every instrument in the song.

| argument | type | notes |
|---|---|---|
| `track` | any | Track id (integer) or its exact name. |

    staros-tap startune verb instrument.info '{}'

### `instrument.load` — low, undoable

Load an instrument file (zones over a WAV: rust-shared starlab-circuit's startune_instrument.py writes them, e.g. fixtures/instruments/ladder/instrument.json) onto a track, or onto a new track. Its notes then come from the track's pattern clips (pattern.notes.set, pattern.clip.add) and from note.play and MIDI (midi.target).

| argument | type | notes |
|---|---|---|
| `name` | string | the instrument's (and a new track's) name |
| `path` | string | required; the instrument file (absolute, or from the app's folder) |
| `track` | any | Track id (integer) or its exact name. |

    staros-tap startune verb instrument.load '{"path": "…"}'

### `instrument.remove` — low, undoable

Take a track's instrument away (its patterns and clips stay, and play nothing).

| argument | type | notes |
|---|---|---|
| `track` | any | required; Track id (integer) or its exact name. |

    staros-tap startune verb instrument.remove '{"track": "…"}'

### `instrument.set` — low, undoable

Change a track's instrument: its envelope (attack_ms, decay_ms, sustain 0-1, release_ms), mono (a new note cuts the sounding one), name, or vel_db: its velocity law, a dynamic range in dB (6-96; 40 is a piano's) from velocity 1 to 127; 0 goes back to v/127.

| argument | type | notes |
|---|---|---|
| `attack_ms` | number | minimum 0; maximum 10000 |
| `decay_ms` | number | minimum 0; maximum 60000 |
| `mono` | boolean |  |
| `name` | string |  |
| `release_ms` | number | minimum 0; maximum 60000 |
| `sustain` | number | minimum 0; maximum 1 |
| `track` | any | required; Track id (integer) or its exact name. |
| `vel_db` | number | minimum 0; maximum 96 |

    staros-tap startune verb instrument.set '{"track": "…"}'

### `midi.target` — low, read-only

The track live MIDI notes play (its instrument); without track, none. track.arm on an instrument track does the same. The keys play it in midi.local's startune mode; in piano mode (the default) the piano sounds itself.

| argument | type | notes |
|---|---|---|
| `track` | any | Track id (integer) or its exact name. |

    staros-tap startune verb midi.target '{}'

### `note.off` — low, read-only

End a held note (its envelope releases).

| argument | type | notes |
|---|---|---|
| `key` | integer | minimum 0; maximum 127; MIDI key (A4 = 69, C4 = 60) |
| `note` | string | a note name instead of key: "A1", "C#3", "Bb2" |
| `track` | any | required; Track id (integer) or its exact name. |

    staros-tap startune verb note.off '{"track": "…"}'

### `note.on` — low, read-only

Start a note on a track's instrument and hold it until note.off (live play; nothing is recorded).

| argument | type | notes |
|---|---|---|
| `key` | integer | minimum 0; maximum 127; MIDI key (A4 = 69, C4 = 60) |
| `note` | string | a note name instead of key: "A1", "C#3", "Bb2" |
| `track` | any | required; Track id (integer) or its exact name. |
| `vel` | integer | minimum 1; maximum 127 |

    staros-tap startune verb note.on '{"track": "…"}'

### `note.play` — low, read-only

Hear one note of a track's instrument now (an audition: nothing is recorded or changed): key or note, vel 1-127, len seconds (default 0.5, at most 10).

| argument | type | notes |
|---|---|---|
| `key` | integer | minimum 0; maximum 127; MIDI key (A4 = 69, C4 = 60) |
| `len` | number | minimum 0.01; maximum 10 |
| `note` | string | a note name instead of key: "A1", "C#3", "Bb2" |
| `track` | any | required; Track id (integer) or its exact name. |
| `vel` | integer | minimum 1; maximum 127 |

    staros-tap startune verb note.play '{"track": "…"}'

### `pattern.export` — low, read-only

Write a pattern as a Standard MIDI File (format 1): its notes and its pedal lane (CC 64 damper, 66 sostenuto, 67 soft) at the song's tempo, from the pattern's start, for any DAW. path: where (default: the song's exports/<track>-<pattern>.mid).

| argument | type | notes |
|---|---|---|
| `path` | string |  |
| `pattern` | integer | minimum 1 |
| `track` | any | required; Track id (integer) or its exact name. |

    staros-tap startune verb pattern.export '{"track": "…"}'

### `pattern.follow` — low, undoable

Whether and how a pattern follows the chord plan (KB10): its notes rendered over the plan's chord under them, from its own chord record (the chords the roll heard while it was kept). on: true / false; absent, a pattern follows when it has a record. voicing: voices (the default: a chord moves voice by voice to the plan's, its common tones held; a line by degree) or parallel (every note by the same degree). A pattern without a record follows nothing whatever is set. One undo step.

| argument | type | notes |
|---|---|---|
| `on` | boolean |  |
| `pattern` | integer | minimum 1 |
| `track` | any | required; Track id (integer) or its exact name. |
| `voicing` | string | one of voices, parallel |

    staros-tap startune verb pattern.follow '{"track": "…"}'

### `pattern.note.set` — low, undoable

Set one note of a pattern: key (or note) at a position, len and vel 1-127 (vel 0 removes the note on that key there). The position is tick (960 a beat, from the pattern's start) in pattern, or at_bar in pattern clip `clip`. len is in ticks (or len_beats); a note ends inside its pattern.

| argument | type | notes |
|---|---|---|
| `at_bar` | number | minimum 1 |
| `clip` | integer | a pattern clip id |
| `key` | integer | minimum 0; maximum 127; MIDI key (A4 = 69, C4 = 60) |
| `len` | integer | minimum 1 |
| `len_beats` | number | minimum 0.001 |
| `note` | string | a note name instead of key: "A1", "C#3", "Bb2" |
| `pattern` | integer |  |
| `tick` | integer | minimum 0 |
| `track` | any | required; Track id (integer) or its exact name. |
| `vel` | integer | required; minimum 0; maximum 127 |

    staros-tap startune verb pattern.note.set '{"track": "…", "vel": 0}'

### `pattern.notes.set` — low, undoable

Replace a pattern's notes whole: notes = [{tick, len, key (or note), vel}] (ticks 960 a beat). A pattern id the track lacks is made (len_beats, default 4; a name), so a track's first note clip is this, then pattern.clip.add. pedals = [{tick, pedal: damper | sostenuto | soft, value 0-127 or down}] replaces its pedal lane (the damper reads value/127: 72 is a half); without pedals the lane stays.

| argument | type | notes |
|---|---|---|
| `len_beats` | integer | minimum 1; maximum 4096 |
| `name` | string |  |
| `notes` | array | required |
| `pattern` | integer | minimum 1 |
| `pedals` | array |  |
| `track` | any | required; Track id (integer) or its exact name. |

    staros-tap startune verb pattern.notes.set '{"track": "…", "notes": []}'

## jobs

### `job.cancel` — low

Cancel a background job by its number (job.list): a queued one never starts, a running one has its worker stopped. It ends as *_cancelled in activity.

| argument | type | notes |
|---|---|---|
| `job` | integer | required; minimum 1 |

    staros-tap startune verb job.cancel '{"job": 0}'

### `job.list` — low, read-only

Background jobs, running then queued: {job, kind, key, label, state, progress}. Heavy jobs (sidecars) run one at a time and wait while recording.

    staros-tap startune verb job.list '{}'

## kit

### `kit.info` — low, read-only

A kit track in full: its pads (role, where the slice sits in the take, length, gain, pitch, choke), its patterns (steps, where they came from) and its pattern clips (bars), and what no longer matches -- a tempo changed since, an older analysis, a followed clip that moved. Without track: every kit in the song.

| argument | type | notes |
|---|---|---|
| `track` | any | Track id (integer) or its exact name. |

    staros-tap startune verb kit.info '{}'

### `kit.make` — low, undoable

Turn a take into a kit track: its own transients as pads (one per sound class, on its section 53.2 role: SUB 0, BODY 1, SNARE 2, TICK 3, MOTION 4, AUX 5, AUX2 6) and a pattern that FOLLOWS the take -- every hit on its role's pad, where the take plays it -- placed where the take plays (bar 1 for a take not in the song). Needs the take's slices: without them it queues take.slices and says so. Name the take like take.info.

| argument | type | notes |
|---|---|---|
| `clip` | integer | the take's clip on that track |
| `media` | integer | media id (media.list) |
| `name` | string | the kit track's name (default: the take's + ' kit') |
| `track` | any | Track id (integer) or its exact name. |

    staros-tap startune verb kit.make '{}'

### `pad.play` — low, read-only

Hear one pad (nothing is recorded or changed). vel 1-127. at_beat: the song's beat it is meant for (the phone's PADS say the sixteenth they meant), held by the audio thread until that beat's frame while the song plays; a beat past, or the song stopped: at once. fired lands in activity with the beat it took.

| argument | type | notes |
|---|---|---|
| `at_beat` | number | minimum 0 |
| `pad` | integer | required; minimum 0; maximum 15 |
| `track` | any | required; Track id (integer) or its exact name. |
| `vel` | integer | minimum 1; maximum 127 |

    staros-tap startune verb pad.play '{"track": "…", "pad": 0}'

### `pad.set` — low, undoable

Change one pad of a kit: gain (or db), pitch_st, choke group (0 = none), label, or region -- a different slice of the take for it (a region number of take.slices, counted from 1).

| argument | type | notes |
|---|---|---|
| `choke` | integer | minimum 0; maximum 255 |
| `db` | number | minimum -60; maximum 12 |
| `gain` | number | minimum 0; maximum 4 |
| `label` | string | at most 32 characters; "" clears it |
| `pad` | integer | required; minimum 0; maximum 15 |
| `pitch_st` | number | minimum -48; maximum 48 |
| `region` | integer | minimum 1 |
| `track` | any | required; Track id (integer) or its exact name. |

    staros-tap startune verb pad.set '{"track": "…", "pad": 0}'

### `pattern.clip.add` — low, undoable

Place a pattern on the timeline (a pattern clip); returns its id. at_bar defaults to the playhead, len_bars to the pattern's length; it loops inside the clip from offset_bars into the pattern.

| argument | type | notes |
|---|---|---|
| `at_bar` | number | minimum 1 |
| `gain` | number | minimum 0; maximum 4 |
| `len_bars` | number | minimum 0.001 |
| `offset_bars` | number | minimum 0 |
| `pattern` | integer |  |
| `track` | any | required; Track id (integer) or its exact name. |

    staros-tap startune verb pattern.clip.add '{"track": "…"}'

### `pattern.clip.remove` — low, undoable

Take a pattern clip off the timeline (its pattern stays).

| argument | type | notes |
|---|---|---|
| `clip` | integer | required |
| `track` | any | required; Track id (integer) or its exact name. |

    staros-tap startune verb pattern.clip.remove '{"track": "…", "clip": 0}'

### `pattern.clip.set` — low, undoable

Move, resize or re-gain a pattern clip: to_bar, len_bars, offset_bars, gain, or pattern (play another of the track's patterns).

| argument | type | notes |
|---|---|---|
| `clip` | integer | required |
| `gain` | number | minimum 0; maximum 4 |
| `len_bars` | number | minimum 0.001 |
| `offset_bars` | number | minimum 0 |
| `pattern` | integer |  |
| `to_bar` | number | minimum 1 |
| `track` | any | required; Track id (integer) or its exact name. |

    staros-tap startune verb pattern.clip.set '{"track": "…", "clip": 0}'

### `pattern.get` — low, read-only

A pattern's steps (a kit's: tick -- 960 a beat, from the pattern's start -- beat, pad, its role, vel), notes (an instrument's: tick, beat, len, key, note, vel) and pedals (its pedal lane: tick, beat, pedal, value), as written; its swing (pattern.swing: amount, pct, grid; false when straight) says how late the second of each pair plays. from_beat / to_beat window them; at most limit of each (default 256).

| argument | type | notes |
|---|---|---|
| `from_beat` | number | minimum 0 |
| `limit` | integer | minimum 1; maximum 4096 |
| `pattern` | integer |  |
| `to_beat` | number | minimum 0 |
| `track` | any | required; Track id (integer) or its exact name. |

    staros-tap startune verb pattern.get '{"track": "…"}'

### `pattern.step.move` — low, undoable

Move one step of a kit pattern: the step on pad at tick goes to to_tick (and to_pad, if given), keeping its velocity; a step already there is replaced. Ticks are 960 a beat from the pattern's start.

| argument | type | notes |
|---|---|---|
| `pad` | integer | required; minimum 0; maximum 15 |
| `pattern` | integer |  |
| `tick` | integer | required; minimum 0 |
| `to_pad` | integer | minimum 0; maximum 15 |
| `to_tick` | integer | required; minimum 0 |
| `track` | any | required; Track id (integer) or its exact name. |

    staros-tap startune verb pattern.step.move '{"track": "…", "tick": 0, "pad": 0, "to_tick": 0}'

### `pattern.step.set` — low, undoable

Set one step of a kit pattern: pad at a position, vel 1-127 (0 removes it). The position is tick (960 a beat, from the pattern's start) in pattern, or at_bar in pattern clip `clip` (the song bar, inside that clip).

| argument | type | notes |
|---|---|---|
| `at_bar` | number | minimum 1 |
| `clip` | integer | a pattern clip id |
| `pad` | integer | required; minimum 0; maximum 15 |
| `pattern` | integer |  |
| `tick` | integer | minimum 0 |
| `track` | any | required; Track id (integer) or its exact name. |
| `vel` | integer | required; minimum 0; maximum 127 |

    staros-tap startune verb pattern.step.set '{"track": "…", "pad": 0, "vel": 0}'

### `pattern.swing` — low, undoable

Swing a track's patterns, or with no track every pattern written on the grid (a played one -- a kept layer, a kit that follows a take -- keeps its feel unless its track is named): the second of every pair of steps plays late, its steps, notes and pedal moves alike, as a drum machine swings. amount is the delay as a fraction of a step (0 straight, 0.33 a triplet's shuffle, at most 0.75); or pct, where the second step sits in its pair as an MPC says it (50 straight, 66 a triplet, 87.5 at most). grid: the step swung, 16th (the default), 8th or 32nd. pattern names one of the track's patterns. Between steps time stretches in proportion; the bars, the beats and the loops never move. One undo step.

| argument | type | notes |
|---|---|---|
| `amount` | number | minimum 0; maximum 0.75 |
| `grid` | string | one of 16th, 8th, 32nd |
| `pattern` | integer | minimum 1 |
| `pct` | number | minimum 50; maximum 87.5 |
| `track` | any | Track id (integer) or its exact name. |

    staros-tap startune verb pattern.swing '{}'

## library

### `audition.play` — low

Listen to something outside the song: a file (path), a sample-library entry (hash) or a loaded media (media), from from_sec. It stops when the song plays; preview_ready / preview_ended land in activity.

| argument | type | notes |
|---|---|---|
| `from_sec` | number | minimum 0 |
| `gain` | number | minimum 0; maximum 2 |
| `hash` | string |  |
| `media` | integer |  |
| `path` | string |  |

    staros-tap startune verb audition.play '{}'

### `audition.seek` — low

Move what is playing to a second of it.

| argument | type | notes |
|---|---|---|
| `sec` | number | required; minimum 0 |

    staros-tap startune verb audition.seek '{"sec": 0}'

### `audition.state` — low, read-only

What is being auditioned: {state = idle | loading | playing, name, sec, seconds}.

    staros-tap startune verb audition.state '{}'

### `audition.stop` — low

Stop listening.

    staros-tap startune verb audition.stop '{}'

### `crate.list` — low, read-only

What can go on a deck, a session cell or Chop, each row with the `source` those verbs take back (deck.load, session.assign, ui.chop): the song's media, its takes, stems and imports (where = song); this machine's sound store (sounds); the Music folder (music: scanned a few folders a frame, `scanning` while it goes); a Rekordbox stick (stick, asked for by name). A row: {source, name, artist?, seconds?, bpm?, hash?, where}; no row names a path, so a device loads what it lists. query: every word must match; limit (50) and offset page the rows.

| argument | type | notes |
|---|---|---|
| `limit` | integer | minimum 1; maximum 200 |
| `offset` | integer | minimum 0 |
| `query` | string |  |
| `where` | string | one of all, song, sounds, music, stick |

    staros-tap startune verb crate.list '{}'

### `library.open_take` — medium

Open a song and go to one of its takes: the Lyrics view follows it (pinned) and the playhead moves to where it first plays. Refuses over unsaved changes unless force = true.

| argument | type | notes |
|---|---|---|
| `force` | boolean |  |
| `hash` | string | required |
| `slug` | string | required |

    staros-tap startune verb library.open_take '{"slug": "…", "hash": "…"}'

### `library.refresh` — low

Read the songs again and rescan the Music folder.

    staros-tap startune verb library.refresh '{}'

### `library.search` — low, read-only

Search the library: songs by title or first line, takes by name or what was sung in them, and the Music folder's files by artist and title (every word must match).

| argument | type | notes |
|---|---|---|
| `limit` | integer | minimum 1; maximum 500 |
| `query` | string | required |

    staros-tap startune verb library.search '{"query": "…"}'

### `library.songs` — low, read-only

Every song (project folder), most recently opened first: slug, title, the open one marked; takes = true also reads each song's takes (count, first sung line).

| argument | type | notes |
|---|---|---|
| `takes` | boolean |  |

    staros-tap startune verb library.songs '{}'

### `library.takes` — low, read-only

A song's takes (default the open song): each one's name, length, date, how often it plays in the song, and what is stored about it (pitch, transcripts, alignments, the start of its transcript).

| argument | type | notes |
|---|---|---|
| `slug` | string |  |

    staros-tap startune verb library.takes '{}'

## lyrics

### `lyrics.edit` — low, undoable

Replace one sung line (numbered as lyrics.get shows) with new text -- which may be several rows, to insert lines. Undoable.

| argument | type | notes |
|---|---|---|
| `line` | integer | required; minimum 1 |
| `text` | string | required |

    staros-tap startune verb lyrics.edit '{"line": 0, "text": "…"}'

### `lyrics.from_transcript` — low, undoable

Draft the song's lyric sheet from a take's transcript (take.transcribe first): a line where the singer pauses, a stanza at a longer pause and -- for a take placed in the song -- a [Section] header wherever the timeline's section changes. Refuses over existing lyrics unless replace = true or append = true. Undoable. Name the take like take.info.

| argument | type | notes |
|---|---|---|
| `append` | boolean |  |
| `clip` | integer |  |
| `media` | integer |  |
| `replace` | boolean |  |
| `track` | any | Track id (integer) or its exact name. |

    staros-tap startune verb lyrics.from_transcript '{}'

### `lyrics.get` — low, read-only

The song's lyric sheet: its text, its sung lines (numbered 1..n; words, alternates, repeats) and its sections with the bars each one spans on the timeline. from_line/to_line or section narrow the lines; brief=true leaves out the words.

| argument | type | notes |
|---|---|---|
| `brief` | boolean |  |
| `from_line` | integer | minimum 1 |
| `section` | string |  |
| `to_line` | integer | minimum 1 |

    staros-tap startune verb lyrics.get '{}'

### `lyrics.loop` — low, undoable

Loop a sung line (to_line: through that one) as the take the Lyrics view follows sings it, first word to last. Undoable, like loop.set.

| argument | type | notes |
|---|---|---|
| `clip` | integer |  |
| `line` | integer | required; minimum 1 |
| `occ` | integer | minimum 1 |
| `to_line` | integer | minimum 1 |
| `track` | any | Track id (integer) or its exact name. |

    staros-tap startune verb lyrics.loop '{"line": 0}'

### `lyrics.scaffold` — low, undoable

Start the sheet from the timeline's sections: one [Section] header per section, in order, to write the words under (a repeated section name becomes a repeat). Refuses over existing lyrics unless replace=true.

| argument | type | notes |
|---|---|---|
| `replace` | boolean |  |

    staros-tap startune verb lyrics.scaffold '{}'

### `lyrics.seek` — low

Move the playhead to where a sung line -- or one of its words -- starts in the take the Lyrics view follows (or the take named by track + clip). occ picks the n-th time the line is sung.

| argument | type | notes |
|---|---|---|
| `clip` | integer |  |
| `line` | integer | required; minimum 1 |
| `occ` | integer | minimum 1 |
| `track` | any | Track id (integer) or its exact name. |
| `word` | integer | minimum 1 |

    staros-tap startune verb lyrics.seek '{"line": 0}'

### `lyrics.set` — low, undoable

Write the song's lyric sheet (replacing it): plain text, [Section] headers (an empty repeated header sings that section again), one sung line per row, blank = stanza, # comments, alt: alternates, (backing words), x2 repeats -- see docs/lyrics.md. lang is the language it is sung in (default en). Undoable.

| argument | type | notes |
|---|---|---|
| `lang` | string |  |
| `text` | string |  |

    staros-tap startune verb lyrics.set '{}'

### `words.into_sheet` — low, undoable

The direct sentence (words.set's) into the lyric sheet, sung at the end of the section in focus (the one being worked; or `section`, a timeline section's name): under the sheet's header for it, or under a new one at the sheet's end. The Words card's Ctrl+Enter. One undo step.

| argument | type | notes |
|---|---|---|
| `n` | integer | minimum 1 |
| `section` | string |  |

    staros-tap startune verb words.into_sheet '{}'

## markers

### `marker.add` — low, undoable, palette word `mark`

Add a marker (or a section start, or an end mark) at a bar -- at the playhead when at_bar is left out.

| argument | type | notes |
|---|---|---|
| `at_bar` | number | minimum 1 |
| `kind` | string | one of marker, section, end; marker = a named point; section = where a section starts (it runs to the next section or end mark); end = where the section before it stops. |
| `name` | string |  |

    staros-tap startune verb marker.add '{}'

### `marker.list` — low, read-only

The song's markers in order, and its sections as spans (bars).

    staros-tap startune verb marker.list '{}'

### `marker.move` — low, undoable

Move a marker or section start to another bar.

| argument | type | notes |
|---|---|---|
| `kind` | string | one of marker, section, end; marker = a named point; section = where a section starts (it runs to the next section or end mark); end = where the section before it stops. |
| `marker` | any | required; A marker's name (exact, else the first that starts with it, else one that contains it) or its number in marker.list (1-based). |
| `to_bar` | number | required; minimum 1 |

    staros-tap startune verb marker.move '{"marker": "…", "to_bar": 0}'

### `marker.remove` — low, undoable

Remove a marker, section start or end mark.

| argument | type | notes |
|---|---|---|
| `kind` | string | one of marker, section, end; marker = a named point; section = where a section starts (it runs to the next section or end mark); end = where the section before it stops. |
| `marker` | any | required; A marker's name (exact, else the first that starts with it, else one that contains it) or its number in marker.list (1-based). |

    staros-tap startune verb marker.remove '{"marker": "…"}'

### `marker.rename` — low, undoable

Rename a marker or section.

| argument | type | notes |
|---|---|---|
| `kind` | string | one of marker, section, end; marker = a named point; section = where a section starts (it runs to the next section or end mark); end = where the section before it stops. |
| `marker` | any | required; A marker's name (exact, else the first that starts with it, else one that contains it) or its number in marker.list (1-based). |
| `name` | string | required |

    staros-tap startune verb marker.rename '{"marker": "…", "name": "…"}'

### `section.form` — low, undoable, palette word `form`

Lay a song form down as sections from start_bar (default 1): a pop template from the songwriting document -- A (hook-first), B (acoustic accumulation), C (two-state), D (false maximalism) --, `timing` (the machines' timing target), or a machine by id or number 1-6 (built on its own verse / pre / chorus / post lengths). Timed forms turn clock times into bars at the song's tempo; `phrase` rounds them to that many bars. Replaces the sections in that span; plain markers stay.

| argument | type | notes |
|---|---|---|
| `form` | string | required; One of: A, B, C, D, timing, third_reveal, bass_lattice, fixed_choir, holes, harmony_dial, question_answer |
| `phrase` | integer | minimum 1 |
| `start_bar` | number | minimum 1 |

    staros-tap startune verb section.form '{"form": "…"}'

## media

### `media.import` — medium

Import an audio file into the library (decoded and analysed in the background; the import_done line in activity carries the new media id).

| argument | type | notes |
|---|---|---|
| `path` | string | required; absolute path to wav/flac/mp3/ogg/m4a |

    staros-tap startune verb media.import '{"path": "…"}'

### `media.list` — low, read-only

List the media loaded in this project (ids, names, lengths, detected BPM, its grid's first beat in the media's frames (beat0) and confidence (grid_conf, 0-1), and what is stored about each take: pitch, transcripts, alignments).

    staros-tap startune verb media.list '{}'

### `stems.separate` — medium

Separate a take into drums, bass, other and vocals (a background job; stem_done lands in activity). Name it as any take (media, track + clip, or the selected clip) or by a source (hash: a take in the sample library; sound; crate). The take's own samples are separated (a recording or a phone's take has no file); the four stem tracks go under its clip (its start, the same instant of the take, its length; a take not in the song at bar 1); they are kept with the take (asked again with the same model, they come at once: stem_done says cached) and each is put in the sound store (take.to_sound, one a frame; stems.sounds in activity names them; sounds = false leaves them out). device: cpu, mps (the M2's GPU), cuda or auto; by default the worker's (STARTUNE_STEMS_DEVICE, else cpu); stem_done says the one used. A file by path separates as before (its stems at bar 1).

| argument | type | notes |
|---|---|---|
| `clip` | integer |  |
| `crate` | string | an entry of crate.list, by its key |
| `device` | string | one of cpu, mps, cuda, auto |
| `hash` | string | a take in the sample library, by its content hash (crate.list) |
| `media` | integer | minimum 0; a media this song has loaded (media.list) |
| `model` | string | demucs model (default htdemucs) |
| `path` | string | a file (wav, flac, mp3, ogg, m4a); never from a device |
| `sound` | string | a sound in this machine's sound store, by its sha16 |
| `sounds` | boolean | each stem into the sound store too (default true) |
| `track` | any | Track id (integer) or its exact name. |

    staros-tap startune verb stems.separate '{}'

### `take.import` — medium

Bring a take from the phone into the song (the composition flow's Stage 7): hash (a take the phone sent over the session, in its inbox) or path (a WAV, or a phone export bundle's folder). Where: at_bar; else section (+ n); else where it was played (the remote's TAKE); else its own section (a SONG capture's VERSE, PRE...); else the playhead. On the track "phone" (made if needed; "phone 2" where that one is taken), or track. It is decoded in the background and placed when ready: one undo step, take.placed in activity. The same take at the same bar is placed once.

| argument | type | notes |
|---|---|---|
| `at_bar` | number | minimum 1 |
| `hash` | string | sha256:<hex>: a take the session's inbox holds |
| `n` | integer | minimum 1; which of that section (1 = the first) |
| `path` | string | a WAV, or the folder of a phone export bundle |
| `section` | string | a section's name or kind (verse, chorus...) |
| `track` | any | Track id (integer) or its exact name. |

    staros-tap startune verb take.import '{}'

## midi

### `midi.along` — low, read-only

Play along to a track's notes (the Piano tab drops them toward the keys): `track` its id or exact name, "auto" (the first track with notes), or false (off); with no `track`, how it goes. While the song plays, a note met by a strike on its pitch class within 60 ms is a hit, within 25 ms perfect (exact: the very key), and passed with none a miss; each note once. Each pass has its tally (hits, perfect, misses), and `prev` is the pass before: a seek back or the loop's wrap starts the next. A note that began before the song started playing is never judged; a loop's downbeat struck just before the wrap counts on the pass it begins.

| argument | type | notes |
|---|---|---|
| `track` | any | Track id (integer), its exact name, "auto", or false: off. |

    staros-tap startune verb midi.along '{}'

### `midi.calibrate` — low, read-only

Calibrate a device's touch, about 45 s: start (the pp run: ~15 soft notes across the keyboard), next (mf), next (ff, as hard as you play), stop (fits the profile: the quietest to 10, the medians to 32 / 64 / 110, the loudest to 127; remembered on this machine). Each reply has a prompt; midi.state shows the counts. cancel drops it. setting: the piano's touch setting.

| argument | type | notes |
|---|---|---|
| `action` | string | required; one of start, next, stop, cancel |
| `port` | string |  |
| `setting` | string |  |

    staros-tap startune verb midi.calibrate '{"action": "start"}'

### `midi.chords` — low, read-only

The chords played over the last `secs` (default 30), oldest first: each named in the chord ribbon's spelling, its root, major or minor (the circle of fifths' ring), its bass, its keyboard (`port`), `from` keys or pedal, and how long ago it formed and ended (ended_ago_ms null: still sounding). A chord is what sounds once it stands still 60 ms: the keys held, what the sostenuto holds, and what the damper holds that was struck in the last 3 s (an arpeggio under the pedal is its chord: `from: pedal`). `port` takes one keyboard's. With the key its notes (or the keyboard played last's) lean to: startune's Krumhansl-Schmuckler. What the Piano tab draws.

| argument | type | notes |
|---|---|---|
| `port` | string |  |
| `secs` | number | minimum 1; maximum 3600 |

    staros-tap startune verb midi.chords '{}'

### `midi.devices` — low, read-only

Every MIDI port seen this session: its id, name, whether it is connected, its profile (px730, nano or generic; proposed by its name until midi.profile binds it on this machine), and what it has sent (notes, re-strikes of keys still down, ghosts, pedal mirrors dropped).

    staros-tap startune verb midi.devices '{}'

### `midi.gestures` — low, read-only

The gestures in what was just played (the latest phrase, or the last `seconds`), tagged and never applied: roll (three or more strikes in pitch order, spread out: a strum, up or down), block (three or more together), legato (a key handed over to the next, a step or two away), repeat (the same key again quickly), ghost (a key bounced before it rose). Each with its time in the phrase (ms), its span and its keys. calibrate: true sets the block-chord limit from this playing's chords (five or more), remembered on this machine; reset: true forgets it.

| argument | type | notes |
|---|---|---|
| `calibrate` | boolean |  |
| `reset` | boolean |  |
| `seconds` | number | minimum 0.5; maximum 3600 |

    staros-tap startune verb midi.gestures '{}'

### `midi.hands` — low, read-only

The hands lane: the keyboard's log of the open song (every key and pedal, raw; midi.log reads its rows) as a file: its path, its sha256 and its size. Noted on the tape after a save or a keep, the log kept beside the tape by its hash; a replay re-issuing the note reads the log as it stands.

| argument | type | notes |
|---|---|---|
| `big` | boolean |  |
| `blob` | string |  |
| `bytes` | integer |  |
| `path` | string |  |
| `sha256` | string |  |

    staros-tap startune verb midi.hands '{}'

### `midi.keep` — low, undoable

Keep what was just played: the latest phrase (after the last silence of more than 2 s; a key or pedal held counts as playing) becomes a note clip with its pedal lane, one undo step. Played while the song ran, it lands where it was heard. Otherwise its first strong note lands at at_bar (default: the playhead) in real time at the song's tempo; a tempo is suggested, and tempo: true applies it in the same step. seconds: the last so many seconds instead. source: hands (the default) or playback (the piano's own recorder). It plays back on the sound it was played with: in piano or echo mode on the piano itself, on a track that plays the piano with the phrase's tone (found by its output, or made in the same step on a part of its own: 8, 9, 11-16, then 10, so the player's own sound on part 1 is never touched; `device` names another output); in startune mode on the track the keys play (midi.target's, else the first routing row's instrument). track names one instead. The piano's tone is remembered, and so are the chords the roll heard while it was played (the phrase's own chord record). loop: true (the bench, KB10): the loop's last time round becomes a layer, its clip the loop itself (a strike just before the wrap lands on the downbeat); plan: true (the default with loop) puts the phrase's chords into the chord plan when the plan has none inside the loop, the same undo step.

| argument | type | notes |
|---|---|---|
| `at_bar` | number | minimum 1 |
| `device` | string | the MIDI output a new piano track sends to (default: the piano plugged in) |
| `loop` | boolean |  |
| `name` | string |  |
| `plan` | boolean |  |
| `port` | string |  |
| `seconds` | number | minimum 0.1; maximum 3600 |
| `source` | string | one of hands, playback |
| `tempo` | boolean |  |
| `track` | any | Track id (integer) or its exact name. |

    staros-tap startune verb midi.keep '{}'

### `midi.local` — low, read-only

The monitor mode. piano (the default): the keys play the piano's own sound and startune listens, logs and keeps. startune: the keys play startune's instruments through the routing rows (or the track midi.target names); turn the piano's Local Control off, or it doubles every note. echo: the keys play the routing rows with the piano's sound. Each instrument row's notes go back at once to `device` (default: the piano plugged in) on the row's part (midi.route's part and tone), a key no row takes plays the piano's panel tone, and kit rows still play startune's pads. Echoing a piano to itself first asks whether its Local Control is off (`question`): answer with local_off: true (false goes back to piano mode). The answer holds until the piano goes away. Leaving a sounding mode ends every held note first.

| argument | type | notes |
|---|---|---|
| `device` | string | echo: the MIDI output to send to (midi.out lists them) |
| `local_off` | boolean | echo: the piano's Local Control is off (FUNCTION + F7 on the PX-730) |
| `mode` | string | required; one of piano, startune, echo |

    staros-tap startune verb midi.local '{"mode": "piano"}'

### `midi.log` — low, read-only

The performance log: every message every port sent, oldest first, after `since` (a seq; 0 for the oldest kept), at most `limit` (default 200). Each row: seq, dev, t_us (host time, microseconds), the bytes, and what they mean. `next` is the seq to ask from next.

| argument | type | notes |
|---|---|---|
| `limit` | integer | minimum 1; maximum 5000 |
| `since` | integer | minimum 0 |

    staros-tap startune verb midi.log '{}'

### `midi.out` — low, undoable

A track plays an external instrument, the piano as a sound module: its note clips and pedal lane go out as MIDI to `device` (a MIDI output's name; default: the piano plugged in) on `channel` (1-16; default: one no other track uses there; on a piano, a part from 8 up -- 8, 9, 11-16, then 10 -- so the player's own sound on 1 and the piano's own parts are left alone), timed to sound with the speakers. tone (a PX-730 tone's name, e.g. "ELEC PIANO") or program / bank_msb / bank_lsb choose its sound where the song starts playing. off: true sounds the track here again. One undo step. With no track: the outputs there are, the tracks sent out and the tones.

| argument | type | notes |
|---|---|---|
| `bank_lsb` | integer | minimum 0; maximum 127 |
| `bank_msb` | integer | minimum 0; maximum 127 |
| `channel` | integer | minimum 1; maximum 16 |
| `device` | string |  |
| `off` | boolean |  |
| `program` | integer | minimum 0; maximum 127 |
| `tone` | string |  |
| `track` | any | Track id (integer) or its exact name. |

    staros-tap startune verb midi.out '{}'

### `midi.out.calibrate` — low, read-only

Measure the piano's latency against the speakers with the Mac's mic, so MIDI out lines them up: the speakers click, the piano plays a note half a second later (trials times, 5 by default; about 1.2 s each), and the mic hears both. The speakers must play aloud (not headphones) and the piano's volume be up. It runs in the background: out_calibrate_done (the latency, its spread, each trial) lands in activity, and the latency is applied and remembered on this machine (negative: the piano is the faster path, and its notes are held back). verify: send the notes through the correction in use instead, which should leave about 0 (residual_ms); nothing is applied. device: the piano's MIDI output (default: the piano plugged in).

| argument | type | notes |
|---|---|---|
| `device` | string |  |
| `key` | integer | minimum 0; maximum 127 |
| `trials` | integer | minimum 1; maximum 12 |
| `vel` | integer | minimum 1; maximum 127 |
| `verify` | boolean |  |

    staros-tap startune verb midi.out.calibrate '{}'

### `midi.panic` — low, read-only

Every live note ends now and every pedal lets go (a stuck note, a held damper): the engine's live voices declick, and the keys read up.

    staros-tap startune verb midi.panic '{}'

### `midi.pedal` — low, read-only

A pedal's role: piano (it plays: the damper's default), off (it does nothing), keep (the sostenuto's default; a press runs midi.keep: what was just played becomes a clip; into the loop while it is on), freeze (what sounds at its press, keys down and notes ringing, holds where it is until it lifts: a ringing note becomes a pad; the sostenuto's second life) or plan (a press runs plan.mark: the chord the keys hold goes into the chord plan at the next bar) or talk (held, startune listens for a spoken command with no wake word; let go, what was said settles at once: the voice pass's push-to-talk, for a foot at the piano; the SOFT pedal's default, from 2026-10-23: "talk pedal off" or {pedal: "soft", role: "piano"} gives it back). A pedal that is not piano never reaches the strip or a kept lane; its moves are still logged. Remembered on this machine. With no pedal, the roles as they are.

| argument | type | notes |
|---|---|---|
| `pedal` | string | one of damper, sostenuto, soft |
| `role` | string | one of piano, off, keep, freeze, plan, talk |

    staros-tap startune verb midi.pedal '{}'

### `midi.profile` — low, read-only

Bind a port (its name, as midi.devices shows it) to a profile on this machine: px730 (Casio Privia PX-730: main part on its send channel, layer on 2, split on 3, its recorder on 4-7, pedals once), nano (Korg nanoKONTROL2: its CCs drive the mixer) or generic. Without profile, the one its name proposes. main_channel is the PX-730's send channel (default 1). Remembered on this machine.

| argument | type | notes |
|---|---|---|
| `main_channel` | integer | minimum 1; maximum 16 |
| `port` | string | required |
| `profile` | string | one of px730, nano, generic |

    staros-tap startune verb midi.profile '{"port": "…"}'

### `midi.route` — low, undoable

Add a routing row: the keys from..to (or from_note..to_note, e.g. "A0" .. "B2") of a device (a port's name; absent: any) and channel (1-16; absent: any; the PX-730's BASS split is 3) play `track`. An instrument track plays notes (transpose in semitones, vel_scale); a kit track plays its pads (kit: gm puts each role's pad on its GM drum key, SUB 36 BODY 45 SNARE 38 TICK 42 MOTION 49 AUX 39 AUX2 51, and with no keys named sits on C2-D#3; chromatic puts pad n on from + n, from A0 by default). Overlapping rows layer, adjacent rows split. In echo mode an instrument row plays the piano: on `part` (default: a part of its own from 8 up when it names a tone, else part 1 with the panel's tone), with `tone` (a PX-730 tone's name) or program / bank_msb / bank_lsb. The song keeps them; one undo step.

| argument | type | notes |
|---|---|---|
| `bank_lsb` | integer | minimum 0; maximum 127 |
| `bank_msb` | integer | minimum 0; maximum 127 |
| `channel` | integer | minimum 1; maximum 16 |
| `device` | string |  |
| `from` | integer | minimum 0; maximum 127 |
| `from_note` | string |  |
| `kit` | string | one of gm, chromatic |
| `part` | integer | minimum 1; maximum 16; echo: the piano's part |
| `program` | integer | minimum 0; maximum 127 |
| `to` | integer | minimum 0; maximum 127 |
| `to_note` | string |  |
| `tone` | string | echo: a PX-730 tone's name for the row's part |
| `track` | any | required; Track id (integer) or its exact name. |
| `transpose` | integer | minimum -48; maximum 48 |
| `vel_scale` | number | minimum 0.05; maximum 8 |

    staros-tap startune verb midi.route '{"track": "…"}'

### `midi.routes` — low, read-only

The song's routing rows, numbered from 1: track, keys (and their names), device, channel, transpose, vel_scale, kit. None: midi.target's track plays every key.

    staros-tap startune verb midi.routes '{}'

### `midi.score` — low, read-only

Score what was just played along with the song (the latest phrase, or the last `seconds`; it must have been played while the song ran). against: take (the default: play the melody you sang: each sung note met by a strike on its pitch class within 25 ms is Perfect, within 60 ms Good; wrong, missed and extra counted; the mean lag) or chords (the chord ribbon under the clip: what sounded through most of each chord, hit / close / miss). track / clip name the take (default: the clip under the playing with a pitch trace, take.pitch).

| argument | type | notes |
|---|---|---|
| `against` | string | one of take, chords |
| `clip` | integer |  |
| `seconds` | number | minimum 0.5; maximum 3600 |
| `track` | any | Track id (integer) or its exact name. |

    staros-tap startune verb midi.score '{}'

### `midi.state` — low, read-only

What the keyboard is doing now: the keys held (note, velocity, strike depth), the pedals (the damper's raw value and amount 0-1: the PX-730's half-damper reads 0.5; sostenuto, soft), the tone its panel chose, the monitor mode, and the log's size.

    staros-tap startune verb midi.state '{}'

### `midi.touch` — low, read-only

A device's touch profile: how its raw velocities map onto the full range (a player's softest to their hardest). get shows it (source raw / estimated / calibrated, its points, its 128-entry table); estimate fits one to the strikes logged from the port (32 or more); reset plays raw again. port: a port's name (default: the keyboard played last); setting: the piano's touch setting it is for (the PX-730's off / 1 / 2 / 3). Remembered on this machine.

| argument | type | notes |
|---|---|---|
| `action` | string | one of get, estimate, reset |
| `port` | string |  |
| `setting` | string |  |

    staros-tap startune verb midi.touch '{}'

### `midi.unroute` — low, undoable

Remove routing row `row` (from 1, as midi.routes numbers them), or every row (all: true). One undo step.

| argument | type | notes |
|---|---|---|
| `all` | boolean |  |
| `row` | integer | minimum 1 |

    staros-tap startune verb midi.unroute '{}'

## mix

### `master.gain` — low, undoable, palette word `master`

Set the master gain (1 = unity).

| argument | type | notes |
|---|---|---|
| `gain` | number | required; minimum 0; maximum 4 |

    staros-tap startune verb master.gain '{"gain": 0}'

### `track.fx` — low, undoable

Configure one stage of a track's insert FX chain (created on first use, every stage starts bypassed): bypass=false switches the stage on; params sets named parameters, e.g. {"mix":0.3}.

| argument | type | notes |
|---|---|---|
| `bypass` | boolean |  |
| `params` | object | parameter name -> number |
| `slot` | string | required; one of denoise, pitch_shift, autotune, nam, cab, amp, transient, gate, eq, comp, tcn_comp, delay, reverb |
| `track` | any | required; Track id (integer) or its exact name. |

    staros-tap startune verb track.fx '{"track": "…", "slot": "denoise"}'

### `track.sends` — low, undoable

Set a track's post-fader send levels (0..1) to the reverb and delay buses.

| argument | type | notes |
|---|---|---|
| `delay` | number | minimum 0; maximum 1 |
| `reverb` | number | minimum 0; maximum 1 |
| `track` | any | required; Track id (integer) or its exact name. |

    staros-tap startune verb track.sends '{"track": "…"}'

## plan

### `bench.lift` — low, undoable

Lift the bench into the song: the loop's bars become a section (`name`, default the next 'section n'; an end mark closes it when nothing follows), and the loop moves on to the bars after it, the same length, so the next part can be built there. The layers stay where they were, now a section of the song; the plan stays. One undo step.

| argument | type | notes |
|---|---|---|
| `name` | string |  |

    staros-tap startune verb bench.lift '{}'

### `bench.state` — low, read-only

The bench (KB10): the loop as it stands (bars), each layer inside it -- every kept phrase sounding there, on whatever track (each tone of the piano has its own) -- with its track, clip, name, bars, notes, chord record, whether it follows the plan and where it plays out, and the plan's changes inside the loop.

    staros-tap startune verb bench.state '{}'

### `plan.clear` — low, undoable

Forget the plan's changes: all of them, or those from from_bar up to to_bar (exclusive).

| argument | type | notes |
|---|---|---|
| `from_bar` | number | minimum 1 |
| `to_bar` | number | minimum 1 |

    staros-tap startune verb plan.clear '{}'

### `plan.list` — low, read-only

The plan's changes in order (those from from_bar up to to_bar when given): each its number, bar, the bar it holds until, its name, root and function in the plan's key; and the key the plan leans to (startune's Krumhansl-Schmuckler over its chords).

| argument | type | notes |
|---|---|---|
| `from_bar` | number | minimum 1 |
| `to_bar` | number | minimum 1 |

    staros-tap startune verb plan.list '{}'

### `plan.mark` — low, undoable

The chord the keys hold now (the roll's newest) goes into the plan: at `at_bar`, else at the next bar while the song plays (the change lands on the downbeat coming), or the bar the playhead is in when it is stopped. What the plan pedal and Arrange's Shift+K do.

| argument | type | notes |
|---|---|---|
| `at_bar` | number | minimum 1 |

    staros-tap startune verb plan.mark '{}'

### `plan.move` — low, undoable

Move a change (by n or at_bar) to another bar; one there already is replaced.

| argument | type | notes |
|---|---|---|
| `at_bar` | number | minimum 1 |
| `n` | integer | minimum 1 |
| `to_bar` | number | required; minimum 1 |

    staros-tap startune verb plan.move '{"to_bar": 0}'

### `plan.remove` — low, undoable

Remove a change: by its number (plan.list's n) or the bar it is at.

| argument | type | notes |
|---|---|---|
| `at_bar` | number | minimum 1 |
| `n` | integer | minimum 1 |

    staros-tap startune verb plan.remove '{}'

### `plan.set` — low, undoable, palette word `chord`

A chord change in the plan at a bar (default: the bar the playhead is in), holding until the next change; one at that bar already is replaced. Name it as `chord` (C, Am7, F#dim, Bb, C/E), as `root` + `quality`, or as `pcs` + `bass`. The plan is the song's harmonic spine: the compass, the chord lane, Arrange's ruler and play-along read it, and a kept phrase that follows it plays over the chord under it. One undo step.

| argument | type | notes |
|---|---|---|
| `at_bar` | number | minimum 1 |
| `bass` | any | The bass's pitch class or note name |
| `chord` | string | A chord's name: C, Am7, F#dim, Bb, C/E |
| `pcs` | any | Pitch classes (a list, or bits 1 << pc), with bass |
| `quality` | string | major (the default), minor, or a suffix (7, maj7, sus4...) |
| `root` | any | A pitch class 0-11 or a note's name, with quality |

    staros-tap startune verb plan.set '{}'

### `plan.suggest` — low, read-only

Chords that may come next (the melodic wheel, KB10): from the plan's change at at_bar (default: the bar the playhead is in), or from `chord` named, in the plan's key. Ranked by the songwriting document's eight progression families (each family that takes the step), one place round the circle (a fifth either way, or the relative), notes in common, and being in the key; each with its name, function, score and reasons. n: how many (default 3, at most 12).

| argument | type | notes |
|---|---|---|
| `at_bar` | number | minimum 1 |
| `chord` | string | A chord's name: C, Am7, F#dim, Bb, C/E |
| `n` | integer | minimum 1; maximum 12 |

    staros-tap startune verb plan.suggest '{}'

## project

### `project.info` — low, read-only

The current song: title, slug, folder, task, unsaved changes.

    staros-tap startune verb project.info '{}'

### `project.list` — low, read-only

Every song folder under the projects root.

    staros-tap startune verb project.list '{}'

### `project.new` — medium, palette word `new`

Start a new, empty song (its own folder and task). Refuses over the open song's unsaved changes unless force = true.

| argument | type | notes |
|---|---|---|
| `force` | boolean |  |
| `title` | string | required |

    staros-tap startune verb project.new '{"title": "…"}'

### `project.open` — medium, palette word `open`

Open a song by slug (see project.list) or folder path. Refuses over the open song's unsaved changes unless force = true.

| argument | type | notes |
|---|---|---|
| `dir` | string |  |
| `force` | boolean |  |
| `slug` | string |  |

    staros-tap startune verb project.open '{}'

### `project.save` — low, palette word `save`

Save the song to its project.json.

    staros-tap startune verb project.save '{}'

## record

### `record.start` — low, palette word `rec`

Start recording from the default input at the playhead (the take lands on the armed track -- track.arm -- else the selected one, when recording stops).

    staros-tap startune verb record.start '{}'

### `record.stop` — low, palette word `recstop`

Stop recording; the take is stored and placed on the timeline.

    staros-tap startune verb record.stop '{}'

### `track.arm` — low, palette word `arm`

Arm a track for recording: the next take lands on it (one track at a time). Toggles without `on`. Arming an instrument track also routes live MIDI to it (midi.target).

| argument | type | notes |
|---|---|---|
| `on` | boolean |  |
| `track` | any | required; Track id (integer) or its exact name. |

    staros-tap startune verb track.arm '{"track": "…"}'

## session

### `session.assign` — low

Put audio into a cell of the session grid: track + slot (1-8), else the Session view's cursor cell (the library's S). Any source: media, hash (a take in the sample library), sound, path, crate (an entry of crate.list); one the song does not have is loaded first (the reply says importing; session.assigned, or session.assign_failed, lands in activity).

| argument | type | notes |
|---|---|---|
| `crate` | string | an entry of crate.list, by its key |
| `gain` | number | minimum 0; maximum 4 |
| `hash` | string | a take in the sample library, by its content hash (crate.list) |
| `media` | integer | minimum 0; a media this song has loaded (media.list) |
| `path` | string | a file (wav, flac, mp3, ogg, m4a); never from a device |
| `slot` | integer | minimum 1; maximum 8 |
| `sound` | string | a sound in this machine's sound store, by its sha16 |
| `track` | any | Track id (integer) or its exact name. |

    staros-tap startune verb session.assign '{}'

### `session.kick` — low

Drop a device's connection (it may come back).

| argument | type | notes |
|---|---|---|
| `device` | string | required |

    staros-tap startune verb session.kick '{"device": "…"}'

### `session.launch` — low

Launch a track's session slot (the Session view's click): it starts at the next quant beats (default 4, the bar) and loops; the engine's slot state reads queued, then playing.

| argument | type | notes |
|---|---|---|
| `quant` | number | minimum 0; maximum 64; Quantize the launch to this many beats (default 4 = the next bar; 0 = now). |
| `slot` | integer | required; minimum 1; maximum 8; The slot, 1-8. |
| `track` | any | required; Track id (integer) or its exact name. |

    staros-tap startune verb session.launch '{"track": "…", "slot": 0}'

### `session.pair` — high

Pair a device with this startune's session (the phone's remote at the piano; the tower): a secret made for it alone, kept in ~/.staros/startune-session/peers.json (0600) and shown ONCE here, to copy into the device's settings. role: remote (the phone: play, the walk, the peg, the keep, the stage) or desk (the tower: any verb that is not high risk and names no path). Never over the session.

| argument | type | notes |
|---|---|---|
| `name` | string | required |
| `role` | string | one of remote, desk |

    staros-tap startune verb session.pair '{"name": "…"}'

### `session.peers` — low, read-only

The devices paired with the session: name, role, when, revoked (never their secrets).

    staros-tap startune verb session.peers '{}'

### `session.revoke` — high

Revoke a device: its secret no longer opens the session, and its connection is dropped.

| argument | type | notes |
|---|---|---|
| `device` | string | required |

    staros-tap startune verb session.revoke '{"device": "…"}'

### `session.status` — low, read-only

The session: each address it listens on (bound, or why not), the devices connected, how many are paired, and the inbox (the takes it holds, what is arriving).

    staros-tap startune verb session.status '{}'

### `session.stop` — low

Stop a track's session slot at the next quant beats (default 4; 0 = now).

| argument | type | notes |
|---|---|---|
| `quant` | number | minimum 0; maximum 64; Quantize the launch to this many beats (default 4 = the next bar; 0 = now). |
| `slot` | integer | required; minimum 1; maximum 8; The slot, 1-8. |
| `track` | any | required; Track id (integer) or its exact name. |

    staros-tap startune verb session.stop '{"track": "…", "slot": 0}'

## song

### `click.set` — low, undoable, palette word `click`

The song's click: pattern, one bar of 1-16 steps (X an accent, x a beat, o a soft tick, . a rest; "Xxxx" by default, a machine's accents like "X..X..X."), and count_in, bars of it before the song starts (0-4). Saved with the song; one undo step. Whether it sounds is click.on's.

| argument | type | notes |
|---|---|---|
| `count_in` | integer | minimum 0; maximum 4 |
| `pattern` | string |  |

    staros-tap startune verb click.set '{}'

### `flow.answer` — low, undoable

Answer one of Session F's questions (the Form room's checklist, §57): q 1-5 in the order the card asks them; answer "yes", "no", a note, or "" to take it back. Saved with the song; one undo step.

| argument | type | notes |
|---|---|---|
| `answer` | string | required |
| `q` | integer | required; minimum 1; maximum 16 |

    staros-tap startune verb flow.answer '{"q": 0, "answer": "…"}'

### `flow.keep` — low, undoable, palette word `keep`

The one keep (K; the keep pedal): with the song playing a loop, the loop's last time round as a layer (midi.keep {loop: true}); stopped, play first (loop.capture); playing without a loop, the phrase where it was heard (midi.keep). The result says which (`routed`).

    staros-tap startune verb flow.keep '{}'

### `flow.stage` — low, palette word `stage`

Move the song to a stage of writing: seed, loop, melody, words, form or derive (the composition flow's rooms; all always reachable). With no stage, to the next one flow.state suggests (staying, with the hint, while this stage's work is not there yet). done: true marks the stage it leaves done, false not done (moving on to the suggestion marks it). Saved with the song and journaled, never an undo step: an undo never moves the song between stages.

| argument | type | notes |
|---|---|---|
| `done` | boolean |  |
| `stage` | string | one of seed, loop, melody, words, form, derive |

    staros-tap startune verb flow.stage '{}'

### `flow.state` — low, read-only

Where the song is in the composition flow (docs/compose-2026-10.md): its stage (seed, loop, melody, words, form, derive) and the next step suggested, each stage's session, prompt and checklist from the songwriting document, the machine it was seeded from (its card), the sections (bars, the machine's job, layers, takes, chord changes each), the section under the playhead with its chords (named as the document names the machine's shapes), the loop, a pegged bar, the click and the words.

    staros-tap startune verb flow.state '{}'

### `loop.capture` — low, undoable, palette word `capture`

Play first: what was just played, with nothing set up, becomes the loop and its first layer. Bar 1 is the phrase's downbeat; strike it again a whole number of bars on and the loop closes there, its tempo the bars' own (C Am F G, then C: four bars). Unclosed, its bars run to the last strike's. An empty song takes the player's tempo; a song with something in it (clips, a plan, sections) keeps its own and the loop is framed at it; bpm and bars ask for them. The layer is the last whole time round, on the sound it was played with (as midi.keep); its chords go into the plan when the plan has none there. at_bar: where the loop goes (default: bar 1 in an empty song, else the playhead's bar). play (default true): the loop starts at once, in phase with the hands when they are still playing. One undo step.

| argument | type | notes |
|---|---|---|
| `at_bar` | integer | minimum 1 |
| `bars` | integer | minimum 1; maximum 16 |
| `bpm` | number | minimum 40; maximum 240 |
| `device` | string |  |
| `name` | string |  |
| `plan` | boolean |  |
| `play` | boolean |  |
| `port` | string |  |
| `track` | any | Track id (integer) or its exact name. |

    staros-tap startune verb loop.capture '{}'

### `loop.clear` — low, undoable

Forget the loop range and stop looping (alt+L in Arrange).

    staros-tap startune verb loop.clear '{}'

### `loop.off` — low, undoable, palette word `unloop`

Turn looping off (the loop range is kept).

    staros-tap startune verb loop.off '{}'

### `loop.peg` — low, undoable, palette word `peg`

Hold one bar: the loop on bar `bar` (default: the playhead's), a chord of the plan to stay on. Again on the same bar, with no bar, or on: false gives the loop it replaced back. While the song plays, at the loop's wrap. One undo step.

| argument | type | notes |
|---|---|---|
| `bar` | number | minimum 1 |
| `on` | boolean |  |

    staros-tap startune verb loop.peg '{}'

### `loop.section` — low, undoable, palette word `loopsec`

Loop one section by name ("loop the chorus"; the second chorus: n=2).

| argument | type | notes |
|---|---|---|
| `n` | integer | minimum 1 |
| `name` | string | required |

    staros-tap startune verb loop.section '{"name": "…"}'

### `loop.set` — low, undoable, palette word `loop`

Loop a bar range and turn looping on. end_bar is inclusive: start_bar=5, end_bar=8 loops bars 5, 6, 7 and 8. Or give until_bar, where the loop stops (exclusive, any fraction: 5 .. 5.5 loops half a bar). on=false sets the range without looping.

| argument | type | notes |
|---|---|---|
| `end_bar` | number | minimum 1 |
| `on` | boolean |  |
| `start_bar` | number | required; minimum 1 |
| `until_bar` | number | minimum 1 |

    staros-tap startune verb loop.set '{"start_bar": 0}'

### `loop.toggle` — low, undoable

Turn looping on or off, keeping the range (shift+L in Arrange).

    staros-tap startune verb loop.toggle '{}'

### `section.walk` — low, undoable, palette word `walk`

Move the loop (the bench) to a section: to = next (the default), prev, or a section's name (n: which of that name, 1 the first). From the section worked, else the one the loop or the playhead is in. While the song plays the loop plays out and the walk lands at its wrap; stopped, at once, the playhead with it. A pegged bar is let go. One undo step.

| argument | type | notes |
|---|---|---|
| `n` | integer | minimum 1 |
| `to` | string |  |

    staros-tap startune verb section.walk '{}'

### `song.board` — low

The song on StarBoard's open board (its tap: port, else its announced one): the song's card (tune://<song>: StarBoard pins its newest bounce and offers a newer one when it comes), and, with takes (the default), every audio take the song plays as a track card (what take.to_sound puts in the sound store), each linked from the song's card; sheet = true adds the song's StarLore sheet (note:sheet-<song>, what song.sheet sends) as a note card, linked too. A card already on the board is kept, never added twice (StarBoard's card.find). Answers each card, added or found.

| argument | type | notes |
|---|---|---|
| `port` | integer | minimum 1; maximum 65535 |
| `sheet` | boolean |  |
| `slug` | string | the sheet's StarLore slug (default sheet-<song>) |
| `takes` | boolean |  |

    staros-tap startune verb song.board '{}'

### `song.bounce` — low

Bounce the song into the device's sound store (docs/sound.md): the song saved, then rendered offline by startune's CLI (daw-render --pcm16), 16-bit stereo at the song's rate, a sound of kind bounce naming the song, its revision, bars, tempo and meter: the bed starsaga places under a cut (audio.place, role bed), what tune://<song> plays on a StarLore page or a StarBoard board. section (+ n): that section's bars alone, a section bed (tune://<song>#<section>). song: another saved song by its folder's name, as saved (never opened). background: answer at once with a job; bounce_done (or bounce_failed) lands in activity.

| argument | type | notes |
|---|---|---|
| `background` | boolean | render on a thread; bounce_done lands in activity |
| `label` | string |  |
| `n` | integer | minimum 1; which of that section (the second chorus: 2) |
| `section` | string | a section's name: its bars alone (a section bed) |
| `song` | string | another saved song's folder name (never opened) |

    staros-tap startune verb song.bounce '{}'

### `song.seed` — low, undoable, palette word `seed`

Seed the song from a songwriting machine (docs/2026-08-songwriting.md §47-52): §54.1's form on the machine's own section lengths as sections from start_bar (default 1), its chords bar by bar as the chord plan (named where the document names them; capo transposes), its accents as the click (count-in 1 bar unless the song has one), the loop on the first verse, and the song at the Loop stage. bpm defaults to the song's when it is a machine's (80-110), else 92; a song with audio clips keeps its tempo (they are placed in frames). Refuses bars that already have chords or sections unless replace. One undo step (the stage stays where it is moved to).

| argument | type | notes |
|---|---|---|
| `bpm` | number | minimum 40; maximum 240 |
| `capo` | integer | minimum 0; maximum 12 |
| `machine` | any | required; A machine's id (third_reveal, bass_lattice, fixed_choir, holes, harmony_dial, question_answer) or its number 1-6 |
| `replace` | boolean |  |
| `start_bar` | integer | minimum 1 |

    staros-tap startune verb song.seed '{"machine": "…"}'

### `song.sheet` — low

The song as a sheet you play in StarLore: a page a section in the song's order, each with its chords bar by bar (the chord plan), its words (the lyric sheet) and its section's bed as its music (tune://<song>#<section>). bounce = true bounces every section's bed first; send = true makes it a new StarLore note (a script) in a running StarLore (port, else its announced tap), never over one of that name. Answers the sheet's text and pages.

| argument | type | notes |
|---|---|---|
| `bounce` | boolean |  |
| `port` | integer | minimum 1; maximum 65535 |
| `send` | boolean |  |
| `slug` | string | the StarLore note's slug (default sheet-<song>) |
| `title` | string |  |

    staros-tap startune verb song.sheet '{}'

### `song.story` — low

The song as a story in StarSaga, a lyric cut: a card a section in the song's order (its name, its chords bar by bar with the bar sounding lit, its words with the line being sung lit), each as long as the section plays, over the song's newest bounce as the bed (bounced now when it has none, or bounce = true). Each line lights when it was sung where a take placed in the song is timed to the sheet (take.align), else the lines share the section's time. section (+ n): that section alone, over its own bed. Made in a running StarSaga (port, else its announced tap) as a new story (default lyrics-<song>, the 9:16 reel preset), the cards one edit; never over a story of that name.

| argument | type | notes |
|---|---|---|
| `bounce` | boolean |  |
| `n` | integer | minimum 1 |
| `port` | integer | minimum 1; maximum 65535 |
| `preset` | string |  |
| `section` | string |  |
| `slug` | string | the StarSaga story's slug (default lyrics-<song>[-<section>]) |
| `title` | string |  |

    staros-tap startune verb song.story '{}'

### `song.to_saga` — low

The song under StarSaga's open cut as its bed: the song's newest bounce (bounced now when it has none, or with bounce = true) placed by StarSaga's own audio.place over its tap (port, else its announced one), role bed under the key bed:<song>, so placing it again replaces it. section: that section's bed instead; at: where on the cut (ms, default its start).

| argument | type | notes |
|---|---|---|
| `at` | integer | minimum 0 |
| `bounce` | boolean |  |
| `port` | integer | minimum 1; maximum 65535 |
| `section` | string |  |

    staros-tap startune verb song.to_saga '{}'

### `tempo.set` — low, undoable, palette word `tempo`

Set the song tempo in BPM.

| argument | type | notes |
|---|---|---|
| `bpm` | number | required; minimum 20; maximum 400 |

    staros-tap startune verb tempo.set '{"bpm": 0}'

### `words.set` — low, undoable, palette word `words`

The words workbench (§57's Session C): prose (fifteen minutes of it), nouns and verbs (five each; a list, or one string with commas) and one direct sentence. A field given replaces that field ("" clears it); the others stay. Saved with the song; one undo step.

| argument | type | notes |
|---|---|---|
| `nouns` | any | A list of words, or one string with commas |
| `prose` | string |  |
| `sentence` | string |  |
| `verbs` | any | A list of words, or one string with commas |

    staros-tap startune verb words.set '{}'

## takes

### `take.align` — low

Time the song's lyric sheet to a take, word by word, in the background (the lyrics sidecar; a Mac without it times the words it heard: coarser, and a sung line it cannot make out stays untimed); lyrics_done lands in activity and take.lyrics reads it. A take placed in the song is aligned against the sections it plays under, anything else against the whole sheet (span = all forces that); lines the take does not sing are skipped. from_line/to_line or section (+ n) align a span -- spans add up. separate = true splits the vocal out of a full mix first. Name the take like take.info; with none named or chosen, the take just recorded ("time the words").

| argument | type | notes |
|---|---|---|
| `clip` | integer | clip id on that track |
| `from_line` | integer | minimum 1 |
| `media` | integer | media id (media.list) |
| `model` | string |  |
| `n` | integer | minimum 1 |
| `section` | string |  |
| `separate` | boolean |  |
| `span` | string | one of auto, all |
| `to_line` | integer | minimum 1 |
| `track` | any | Track id (integer) or its exact name. |

    staros-tap startune verb take.align '{}'

### `take.chords` — low, undoable

What a take plays, chord by chord: startune's chord detector over its audio (Arrange's K ribbon) and the key it leans to; for a clip, each chord at the song's bars where it sounds, and each bar's chord (the one sounding longest in it). plan = true writes those into the song's chord plan, a change wherever the chord changes, one undo step: a guitar played into the song teaches it its chords (bars the plan already names are refused unless replace = true). min_secs drops a chord shorter than it (0.3). Name the take like take.info; with none named or chosen, the take just recorded.

| argument | type | notes |
|---|---|---|
| `clip` | integer |  |
| `media` | integer | minimum 0 |
| `min_secs` | number | minimum 0; maximum 10 |
| `plan` | boolean |  |
| `replace` | boolean |  |
| `track` | any | Track id (integer) or its exact name. |

    staros-tap startune verb take.chords '{}'

### `take.info` — low, read-only

What the DAW knows about a take: its length, where it plays in this song, and its stored analysis -- pitch (median note and range; for a clip, over what the clip plays), transcripts, lyric alignments -- plus any job analysing it now. Name it by media, track + clip, or track (its clip under the playhead); default the selected clip.

| argument | type | notes |
|---|---|---|
| `clip` | integer | clip id on that track |
| `media` | integer | media id (media.list) |
| `track` | any | Track id (integer) or its exact name. |

    staros-tap startune verb take.info '{}'

### `take.lyrics` — low, read-only

A take's sung words, timed: the song's sheet joined to the take's alignment line by line -- each line and word with its time in the take and, for a clip, the bar it lands on in this song. A line edited since the alignment is stale until take.align runs again. words = false leaves out the words. Name the take like take.info.

| argument | type | notes |
|---|---|---|
| `clip` | integer | clip id on that track |
| `media` | integer | media id (media.list) |
| `track` | any | Track id (integer) or its exact name. |
| `words` | boolean |  |

    staros-tap startune verb take.lyrics '{}'

### `take.notes` — low, undoable

A sung take into notes (the Melody stage, Session B): its sung pitch read as notes over the clip, kept as a layer that follows the plan, on a track that plays the piano (or into). lock: free (as sung: the melody that ignores barlines; the default), pattern (snapped to the song's click pattern: the melody that locks tightly to it), grid (to `grid` beats, 0.5 = eighths). Name the take like take.info (media, track + clip, or the selection). A take with no traced pitch is traced first, and the notes are kept when pitch_done lands (melody.kept in activity). One undo step.

| argument | type | notes |
|---|---|---|
| `clip` | integer |  |
| `grid` | number | minimum 0.125; maximum 4 |
| `into` | any | Track id (integer) or its exact name. |
| `lock` | string | one of free, pattern, grid |
| `media` | integer | minimum 0 |
| `name` | string |  |
| `track` | any | Track id (integer) or its exact name. |

    staros-tap startune verb take.notes '{}'

### `take.pitch` — low

Trace a take's sung pitch (YIN, every 10 ms, voiced where the audio repeats at its period) in the background and store it with the take. Answers at once with the contour in brief when there is one (again = true re-traces it; a contour of an older method is traced again); otherwise pitch_done lands in activity and take.info shows it. Name the take like take.info.

| argument | type | notes |
|---|---|---|
| `again` | boolean | re-trace even if a contour is stored |
| `clip` | integer | clip id on that track |
| `media` | integer | media id (media.list) |
| `track` | any | Track id (integer) or its exact name. |

    staros-tap startune verb take.pitch '{}'

### `take.slices` — low

Cut a take at its attacks and sort the slices into sound classes with their section 53.2 roles -- SUB (thumb), TICK (nail), SNARE (muted strings), MOTION (slides), BODY -- in the background, with the phone's own analysis. Answers at once when the take has one (again = true cuts it again); otherwise slices_done lands in activity and take.info shows it. grid = n cuts n even slices instead of attacks. Name the take like take.info.

| argument | type | notes |
|---|---|---|
| `again` | boolean | cut it again even if it has slices |
| `bpm` | number | minimum 20; maximum 400; the take's tempo, if you know it (else it is found) |
| `clip` | integer | clip id on that track |
| `grid` | integer | minimum 2; maximum 64 |
| `media` | integer | media id (media.list) |
| `track` | any | Track id (integer) or its exact name. |

    staros-tap startune verb take.slices '{}'

### `take.to_sound` — low

Put a take in the device's sound store (docs/sound.md): a 16-bit WAV named by its bytes, which starsaga can place on a story and the tower can render. The whole take, or what a clip plays of it; its transcript's words (take.transcribe) beside it, timed into the sound, so a story's captions take them (starsaga caption.words). Name it by media, track + clip, or track; default the selected clip.

| argument | type | notes |
|---|---|---|
| `clip` | integer | clip id on that track |
| `label` | string |  |
| `media` | integer | media id (media.list) |
| `track` | any | Track id (integer) or its exact name. |
| `whole` | boolean | the whole take even when a clip names it |

    staros-tap startune verb take.to_sound '{}'

### `take.transcribe` — low

Write down what a take sings, word-timed, in the background (the lyrics sidecar: Whisper, or a Mac's own recognizer where it is not set up); lyrics_done lands in activity. Answers at once with the stored transcript when there is one (again = true runs it again). lang if you know it; separate = true splits the vocal out of a full mix first. draft = true drafts the lyric sheet from it once it is there (lyrics.from_transcript, never over a written sheet; lyrics.drafted in activity): "write down the words". Name the take like take.info; with none named or chosen, the take just recorded.

| argument | type | notes |
|---|---|---|
| `again` | boolean |  |
| `clip` | integer | clip id on that track |
| `draft` | boolean |  |
| `lang` | string |  |
| `media` | integer | media id (media.list) |
| `model` | string |  |
| `separate` | boolean |  |
| `track` | any | Track id (integer) or its exact name. |

    staros-tap startune verb take.transcribe '{}'

## task

### `task.info` — low, read-only

The song's staros task ref (startune/<slug>) and whether tasks are on.

    staros-tap startune verb task.info '{}'

### `task.item` — low, palette word `item`

One item on the song's task list, the tasks sidebar beside the rooms (Ctrl+J): what you plan (planned), are doing (doing), need the person for (needs_you: lit for them, and on the phone), finished (done) or gave up (dropped). New: text (status planned by default); the id comes back. After: id with a status and/or a new text. Say doing when you start a step and done when it is done: the sidebar lists the verbs you ran in between. Kept in the house's work log (the tower's chronicle reads the same items), in your name; not an undo step.

| argument | type | notes |
|---|---|---|
| `id` | string |  |
| `status` | string | one of planned, doing, done, needs_you, dropped |
| `task` | string | another task than the song's (project/slug) |
| `text` | string |  |

    staros-tap startune verb task.item '{}'

### `task.items` — low, read-only

The song's task list as the sidebar shows it: each item's id, text, status, agent, when made, first doing and done (unix ms), and how it was written (verb, or todo: Claude Code's own list).

| argument | type | notes |
|---|---|---|
| `task` | string |  |

    staros-tap startune verb task.items '{}'

### `task.note` — low, palette word `note`

Record one line on the song's staros task (under ## Activity): what changed and why. Call it when a request is done; it shows on the kanban, the board and starterm.

| argument | type | notes |
|---|---|---|
| `text` | string | required |

    staros-tap startune verb task.note '{"text": "…"}'

## terminal

### `terminal.focus` — low

Move keyboard focus to the song's console (dropping it down) or back to the DAW, the console staying down; with no `to`, toggle.

| argument | type | notes |
|---|---|---|
| `to` | string | one of terminal, daw |

    staros-tap startune verb terminal.focus '{}'

### `terminal.hide` — low

Put the console away. The DAW stays attached, so the session and its agent keep running and streaming, and dropping it down again is instant.

    staros-tap startune verb terminal.hide '{}'

### `terminal.open` — low, palette word `term`

Drop the song's console down and start an agent in it: claude, code (starsage — any model) or shell. It is a term-bridge session named task/startune/<song>, so starterm on the phone opens the same one by the song's task; reattaches if running.

| argument | type | notes |
|---|---|---|
| `agent` | string | one of claude, guide, code, shell, greenkeeper, warden, stoker, scribe, herald, busker, porter |

    staros-tap startune verb terminal.open '{}'

### `terminal.screen` — low, read-only

Read what the song's terminal shows now (visible lines, title) — e.g. the reply of the agent running in it.

    staros-tap startune verb terminal.screen '{}'

### `terminal.send` — high, palette word `ask`

Type a line into the song's terminal and press Enter — e.g. hand a natural-language request to the agent running there (the palette's `ask`: the console drops down with it, opening the song's session if none is open). A person's ask (the palette, the voice) goes with one line of where the song is before it (the stage, the section, the tempo, the transport, the last verbs run; daw/ask_context.lua) unless context = false; an agent's own send goes as typed. Runs whatever the terminal runs, hence high risk.

| argument | type | notes |
|---|---|---|
| `context` | boolean |  |
| `enter` | boolean |  |
| `text` | string | required |

    staros-tap startune verb terminal.send '{"text": "…"}'

### `terminal.toggle` — low

The console's one key, Ctrl+`: hidden, drop it down with the keyboard in it (opening the song's session); typing in it, put it away; down while the DAW has the keyboard, type in it.

    staros-tap startune verb terminal.toggle '{}'

## track

### `track.add` — low, undoable, palette word `addtrack`

Add a track at the bottom; returns its id.

| argument | type | notes |
|---|---|---|
| `name` | string |  |

    staros-tap startune verb track.add '{}'

### `track.meters` — low, read-only

Each track's level now (peak and rms, 0-1 with peak also in dB; peaks fall about 20 dB a second) and the voices the engine could not start (voice_starve, counted since launch).

| argument | type | notes |
|---|---|---|
| `track` | any | Track id (integer) or its exact name. |

    staros-tap startune verb track.meters '{}'

### `track.mute` — low, undoable, palette word `mute`

Toggle a track's mute, or set it with on=true/false.

| argument | type | notes |
|---|---|---|
| `on` | boolean |  |
| `track` | any | required; Track id (integer) or its exact name. |

    staros-tap startune verb track.mute '{"track": "…"}'

### `track.remove` — medium, undoable

Remove a track and its clips (undo restores it whole).

| argument | type | notes |
|---|---|---|
| `track` | any | required; Track id (integer) or its exact name. |

    staros-tap startune verb track.remove '{"track": "…"}'

### `track.rename` — low, undoable, palette word `rename`

Rename a track.

| argument | type | notes |
|---|---|---|
| `name` | string | required |
| `track` | any | required; Track id (integer) or its exact name. |

    staros-tap startune verb track.rename '{"track": "…", "name": "…"}'

### `track.set` — low, undoable

Set a track's gain (1 = unity), pan (-1..1), mute and/or solo.

| argument | type | notes |
|---|---|---|
| `gain` | number | minimum 0; maximum 4 |
| `mute` | boolean |  |
| `pan` | number | minimum -1; maximum 1 |
| `solo` | boolean |  |
| `track` | any | required; Track id (integer) or its exact name. |

    staros-tap startune verb track.set '{"track": "…"}'

### `track.solo` — low, undoable, palette word `solo`

Toggle a track's solo, or set it with on=true/false.

| argument | type | notes |
|---|---|---|
| `on` | boolean |  |
| `track` | any | required; Track id (integer) or its exact name. |

    staros-tap startune verb track.solo '{"track": "…"}'

## transport

### `transport.goto` — low, palette word `goto`

Move the playhead to a section or marker by name (the second chorus: to="chorus", n=2).

| argument | type | notes |
|---|---|---|
| `n` | integer | minimum 1 |
| `to` | string | required; A section or marker name. |

    staros-tap startune verb transport.goto '{"to": "…"}'

### `transport.link` — low

Join a desk's one clock (starsaga and the launcher join it too): startune leads it, and a seek, play or pause in any app on the desk moves them all. start_ms / in_ms place the song on the cut (it sounds from story start_ms, in_ms into itself); latency_ms is the output latency to hide.

| argument | type | notes |
|---|---|---|
| `desk` | string | The desk's name, e.g. film-<slug>. |
| `in_ms` | number | minimum 0 |
| `latency_ms` | number | minimum 0; maximum 500 |
| `start_ms` | number |  |

    staros-tap startune verb transport.link '{}'

### `transport.master` — low

Pin the desk's master to an app on it (startune, starsaga); no app unpins, and startune leads again.

| argument | type | notes |
|---|---|---|
| `app` | string |  |

    staros-tap startune verb transport.master '{}'

### `transport.pause` — low, palette word `pause`

Pause playback, keeping the playhead where it is.

    staros-tap startune verb transport.pause '{}'

### `transport.play` — low, palette word `play`

Start playback from the playhead. count_in: bars of the click first (0-4); without it, the song's count-in when this machine's click is on (click.on), else at once.

| argument | type | notes |
|---|---|---|
| `count_in` | integer | minimum 0; maximum 4 |

    staros-tap startune verb transport.play '{}'

### `transport.probe` — low, read-only

The desk's clock: who leads, the apps on it, and how far this playhead is off the master's.

    staros-tap startune verb transport.probe '{}'

### `transport.seek` — low, palette word `seek`

Move the playhead to a bar (1-based), a frame, or a time in seconds.

| argument | type | notes |
|---|---|---|
| `bar` | number | minimum 1; 1-based bar; fractions allowed |
| `frame` | integer | minimum 0 |
| `seconds` | number | minimum 0 |

    staros-tap startune verb transport.seek '{}'

### `transport.stop` — low, palette word `stop`

Stop playback and return the playhead to the start.

    staros-tap startune verb transport.stop '{}'

### `transport.toggle` — low

Play if stopped, pause if playing.

    staros-tap startune verb transport.toggle '{}'

### `transport.unlink` — low

Leave the desk's clock: startune's transport is its own again.

    staros-tap startune verb transport.unlink '{}'

## ui

### `ui.bench` — low, palette word `bench`

The bench pane (KB10): the loop's layers over its bars, each a small piano roll of where its notes will sound under the chord plan (a moved note keeps an outline where it was played), and how each follows: voices, parallel, as played. Docked under the workspace (the Piano tab's B), under every tab. show: true / false (absent: toggles; with layer alone: shows); layer: a lane by number (1 the first) or by its layer's name, chosen for V. Keeping into the loop docks it unless it was hidden.

| argument | type | notes |
|---|---|---|
| `layer` | any | A lane by number (1 the first) or by its layer's name. |
| `show` | boolean |  |

    staros-tap startune verb ui.bench '{}'

### `ui.card` — low, read-only

The card, the left pane of every writing room (Stage 5): the room's stage, the song's machine, the session's prompt, the room's workbench (Seed: the machines; Words: the four fields) and the next step it suggests (N).

    staros-tap startune verb ui.card '{}'

### `ui.chop` — low

Open a take in the Chop view to slice it (the library's C): by any source (media, hash: a take in the sample library, loaded first when the song does not have it; sound; path; crate), or by track + clip -- then Chop shows only what the clip plays, and its K makes the kit that follows that clip. A source being loaded answers importing; Chop opens when it lands.

| argument | type | notes |
|---|---|---|
| `clip` | integer |  |
| `crate` | string | an entry of crate.list, by its key |
| `hash` | string | a take in the sample library, by its content hash (crate.list) |
| `media` | integer | minimum 0; a media this song has loaded (media.list) |
| `path` | string | a file (wav, flac, mp3, ogg, m4a); never from a device |
| `sound` | string | a sound in this machine's sound store, by its sha16 |
| `track` | any | Track id (integer) or its exact name. |

    staros-tap startune verb ui.chop '{}'

### `ui.fretboard` — low, palette word `fretboard`

The Fretboard's settings (F9: the keys held, or the mic's pitch, on a guitar's neck): tuning (a name -- STANDARD, DROP D, OPEN G, DADGAD, DADGBD, CGCGCE, OPEN D, ALL 4THS -- or its number; the keys T / Shift+T step through them), capo (a fret 0-12; frets are counted from it). By default they are the song's (its machine's tuning and capo, read again as the song changes); a tuning or capo given is kept over the song's until song = true. With nothing given, what they are.

| argument | type | notes |
|---|---|---|
| `capo` | integer | minimum 0; maximum 12 |
| `song` | boolean | follow the song's tuning and capo again |
| `tuning` | any | A tuning's name, or its number |

    staros-tap startune verb ui.fretboard '{}'

### `ui.inspector` — low, palette word `inspector`

Show or hide the inspector -- the selection's values and the song's -- to the right of the workspace; toggles without `show` (Ctrl+I).

| argument | type | notes |
|---|---|---|
| `show` | boolean |  |

    staros-tap startune verb ui.inspector '{}'

### `ui.keyboard` — low, palette word `keyboard`

Show or hide the keyboard strip under the workspace: the keys held, the pedals, the routing rows, the latency and the touch (Ctrl+K); toggles without `show`.

| argument | type | notes |
|---|---|---|
| `show` | boolean |  |

    staros-tap startune verb ui.keyboard '{}'

### `ui.keys` — low

The keybindings card (hold F2, or press ?): the focused pane's keys, then the app's global ones. show = true pins it open, false closes it; view = a pane's title (Arrange, Library, Lyrics, ...) reads that pane's keys instead of the focused one's; tile = a tile's name (song) reads that printed surface's gestures from its layout file (tiles/<name>.tile.toml) by mode, with the verbs they run. Returns the keys as data.

| argument | type | notes |
|---|---|---|
| `show` | boolean |  |
| `tile` | string |  |
| `view` | string |  |

    staros-tap startune verb ui.keys '{}'

### `ui.lanes` — low, palette word `lanes`

Show or hide a track's automation lanes in Arrange (volume, pan, reverb, delay); toggles without `show`.

| argument | type | notes |
|---|---|---|
| `show` | boolean |  |
| `track` | any | required; Track id (integer) or its exact name. |

    staros-tap startune verb ui.lanes '{"track": "…"}'

### `ui.library` — low

The library, a drawer over the rooms (Ctrl+B; the composition flow's Stage 4): drawer = true opens it (it takes the keyboard; Esc or a click outside shuts it), false shuts it; tab = songs | collection, query = what its search shows, open = a song's slug to show its takes, focus = true opens the drawer too.

| argument | type | notes |
|---|---|---|
| `drawer` | boolean |  |
| `focus` | boolean |  |
| `open` | string |  |
| `query` | string |  |
| `tab` | string | one of songs, collection |

    staros-tap startune verb ui.library '{}'

### `ui.lyrics` — low

The Lyrics view. pin = true keeps it on the take it follows now (or the one named by track + clip) whatever plays; pin = false lets it choose again (armed track, selected track, best timing). transcript / pitch show or hide its panels.

| argument | type | notes |
|---|---|---|
| `clip` | integer |  |
| `pin` | boolean |  |
| `pitch` | boolean |  |
| `track` | any | Track id (integer) or its exact name. |
| `transcript` | boolean |  |

    staros-tap startune verb ui.lyrics '{}'

### `ui.lyrics_ribbon` — low

Arrange's lyric ribbon: an aligned take's words along the bottom of its clip, the word being sung amber (show, y); pitch draws the take's sung pitch through the clip too (Shift+Y). Without arguments it reports both.

| argument | type | notes |
|---|---|---|
| `pitch` | boolean |  |
| `show` | boolean |  |

    staros-tap startune verb ui.lyrics_ribbon '{}'

### `ui.machine` — low, read-only

The Machine view, the Seed room's main pane (the visual pass): the song's machine, the section in focus as the machine names it, its shapes, its bars, the bar the playhead is in, its picking pattern and its accents.

    staros-tap startune verb ui.machine '{}'

### `ui.piano` — low, palette word `piano`

The Piano tab's settings (Ctrl+P: the notes the keys played rising from a keyboard, the chords they formed, the pedals, the circle of fifths): window (the seconds the roll shows: 4, 8, 16 or 32), notation (the circle's names, or Camelot), freeze (hold the roll still to read it; false lets it run), clear (forget what has ended), follow (a keyboard's port name: the chords, the key and the circle are its; "last": the keyboard played last, the default).

| argument | type | notes |
|---|---|---|
| `clear` | boolean |  |
| `follow` | string |  |
| `freeze` | boolean |  |
| `notation` | string | one of name, camelot |
| `window` | integer | one of 4, 8, 16, 32 |

    staros-tap startune verb ui.piano '{}'

### `ui.room` — low, palette word `room`

The rooms (the composition flow's Stage 4): each stage of writing a layout of panes -- Seed, Loop, Melody, Words, Form, Derive (Ctrl/Cmd+1-6) -- and Tools (Ctrl/Cmd+0), every workspace tab. name: a room's id, title or key (0-6); none reports the room on screen. reset: true builds it from its seed again (this machine's arrangement of it forgotten). A song's stage moving shows its room; switching rooms never changes the stage.

| argument | type | notes |
|---|---|---|
| `name` | any | A room's id (tools, seed, loop, melody, words, form, derive), title or key 0-6 |
| `reset` | boolean |  |

    staros-tap startune verb ui.room '{}'

### `ui.rooms` — low, read-only

Every room: its id, title, key, the stage it shows, its main pane, whether it is on screen, and its panes; and `chrome`, the accent the panes' tabs and focus border wear (the desk's, live: the UI editor's change shows there the next frame).

    staros-tap startune verb ui.rooms '{}'

### `ui.select` — low

Select a track in Arrange, or a clip on it; with neither, clear the selection.

| argument | type | notes |
|---|---|---|
| `clip` | integer |  |
| `track` | any | Track id (integer) or its exact name. |

    staros-tap startune verb ui.select '{}'

### `ui.strip` — low, read-only

The song strip above the rooms (Stage 5): the room chips (on screen, the song's stage, the suggested next), the form, the sections and the plan's chords as it shows them, the loop. A click on a chip shows its room; on a section walks the loop to it; on a chord pegs its bar; Ctrl+[ / Ctrl+] walk. show: false hides it (true shows it).

| argument | type | notes |
|---|---|---|
| `show` | boolean |  |

    staros-tap startune verb ui.strip '{}'

### `ui.view` — low, palette word `view`

Show bars from_bar..to_bar across Arrange (zoom and scroll the timeline to them).

| argument | type | notes |
|---|---|---|
| `from_bar` | number | required; minimum 1 |
| `to_bar` | number | required; minimum 1 |

    staros-tap startune verb ui.view '{"from_bar": 0, "to_bar": 0}'

### `ui.workspace` — low, palette word `ws`

Show a workspace tab.

| argument | type | notes |
|---|---|---|
| `name` | string | required; one of arrange, session, chop, decks, mix, trainer, health, export, fretboard, starpulse, practice, lyrics, piano, terminal |

    staros-tap startune verb ui.workspace '{"name": "arrange"}'

## view

### `ui.tasks` — low

The tasks sidebar beside the rooms (Ctrl+J toggles it): show true / false, toggle, or neither for what it shows (each item's id, text, status, agent; the counts per status). It shows itself when the song's list gets its first item, unless the person put it away.

| argument | type | notes |
|---|---|---|
| `show` | boolean |  |
| `toggle` | boolean |  |

    staros-tap startune verb ui.tasks '{}'

## voice

### `voice.cancel` — low, palette word `nevermind`

Never mind: drop every command waiting for the bar, the beat, the wrap or the section (daw/verbs.lua's `when`). Says how many were dropped.

    staros-tap startune verb voice.cancel '{}'

### `voice.hear` — low, palette word `hear`

Run a phrase as if it were heard (no wake word needed): "loop the verse", "tempo 96", "guide, what next?". It shows in the trace as typed, and runs as the caller.

| argument | type | notes |
|---|---|---|
| `text` | string | required |

    staros-tap startune verb voice.hear '{"text": "…"}'

### `voice.help` — low, read-only

What can be said: each command's phrases, its verb and where it lands while the song plays. Spoken ("startune, what can I say"), it also puts a few of them on the guide's line.

    staros-tap startune verb voice.help '{}'

### `voice.hold` — low, palette word `hold`

The talk pedal by hand (midi.pedal {role: "talk"} is the foot): down opens the ear with no wake word (the microphone too, on the person's own go), up settles what was said at once and closes a microphone the hold opened. Refused to an agent or a device.

| argument | type | notes |
|---|---|---|
| `down` | boolean | required |

    staros-tap startune verb voice.hold '{"down": true}'

### `voice.interpret` — low, read-only, palette word `what`

What a line would do, without doing it: the verb and its arguments, where it lands (when), and whether it read as a phrase of the grammar or a verb line ("loop the verse", "tempo 96", "transport seek 5"). The palette shows this on its first row as you type. Nothing when it is not a command.

| argument | type | notes |
|---|---|---|
| `text` | string | required |

    staros-tap startune verb voice.interpret '{"text": "…"}'

### `voice.listen` — low, palette word `listen`

Listen for spoken commands (a tap of the right Option / right Ctrl key; held, that key is the talk pedal): what is heard shows as a fading trace under the song strip, and a phrase that starts with "startune" runs as a command ("startune, loop the verse"; "startune, guide, ..." hands the rest to the console's agent). on: true / false (none: the other way). wake: false lets commands run without the wake word. The microphone opens only on the person's own go (a key, the palette): an agent or a device may stop listening, never start it.

| argument | type | notes |
|---|---|---|
| `on` | boolean |  |
| `quantize` | boolean |  |
| `wake` | boolean |  |

    staros-tap startune verb voice.listen '{}'

### `voice.model` — low, palette word `model`

The open grammar: words that are no phrase and no verb line are read by a model as a verb of the registry (low-risk verbs only; checked against the registry; asked before a verb undo could not save). tier: device (the Mac's own model, Apple Intelligence on), hosted (a model over the network, opted in), off. Remembered on this machine. With nothing given, the state: the tier, whether its helper is ready, why not, how many proposals.

| argument | type | notes |
|---|---|---|
| `tier` | string | one of device, hosted, off |

    staros-tap startune verb voice.model '{}'

### `voice.profile` — low, palette word `voices`

How a speaker sounds: the DAW (startune), the guide, or any agent (agent:<name>). voice (a name from voice.voices), rate (0.1..0.9), volume (dB), pitch (semitones: its register), style (natural; center: the line shifted onto the nearest note of the chord now; chant: flattened onto it by strength; scale: every syllable snapped to the chord's notes by strength), strength (0..1), follow (what the key is: chord, the chord sounding now, the hands' first, then the plan's; key, its tonic triad; scale, any note of the key; off), speak (none, asks: asks refusals and answers, all: every line). reset drops a speaker's changes. With no field, the speaker's profile; with no speaker, every one. Changed only by the person; remembered on this machine.

| argument | type | notes |
|---|---|---|
| `follow` | string | one of chord, key, scale, off |
| `pitch` | number |  |
| `rate` | number |  |
| `reset` | boolean |  |
| `speak` | string | one of none, asks, all |
| `speaker` | string |  |
| `strength` | number |  |
| `style` | string | one of natural, center, chant, scale |
| `voice` | string |  |
| `volume` | number |  |

    staros-tap startune verb voice.profile '{}'

### `voice.said` — low

A chosen command's words, as the tape records them (text, words with their times, the command and its arguments, when, from: phrase / line / model). Run, it runs that command as the voice did, asking no grammar and no model again: a replay's op. Nothing to say without a command.

| argument | type | notes |
|---|---|---|
| `alt` | string |  |
| `args` | object |  |
| `asked` | boolean |  |
| `command` | string |  |
| `from` | string |  |
| `text` | string | required |
| `tier` | string |  |
| `typed` | boolean |  |
| `when` | string |  |
| `words` | array |  |

    staros-tap startune verb voice.said '{"text": "…"}'

### `voice.say` — low

Hear a speaker as it sounds now: a line spoken through its profile (voice.profile: its voice, and put in the song's key by its style and follow), whatever its speak setting (a preview). speaker: startune (default), guide or agent:<name>. The person's own (the palette, a key, their voice); never while recording or counting in.

| argument | type | notes |
|---|---|---|
| `speaker` | string |  |
| `text` | string | required |

    staros-tap startune verb voice.say '{"text": "…"}'

### `voice.sound` — low, palette word `sound`

How this machine answers a spoken command: short sounds (heard, ran, refused, queued, and the guide's ask), and a spoken line for a refusal or an ask (`speak`; never while recording or counting in; the recognizer is deaf to it unless echo cancellation is on). on: the sounds; db: their level (-40..6). Remembered on this machine. With nothing given, the settings as they are.

| argument | type | notes |
|---|---|---|
| `db` | number |  |
| `gate` | boolean |  |
| `key` | boolean |  |
| `on` | boolean |  |
| `speak` | boolean |  |

    staros-tap startune verb voice.sound '{}'

### `voice.state` — low, read-only

Whether it is listening, to what (mic, or a test's files), the wake word on or off, how much was heard and run, the last words heard, and why it stopped.

    staros-tap startune verb voice.state '{}'

### `voice.trace` — low, read-only

The trace as data: the utterances still showing (their words, each with its time from now), and the command marked in each (ran, refused, heard, typed; what it did).

    staros-tap startune verb voice.trace '{}'

### `voice.voices` — low, read-only

The Mac's voices a speaker may use (voice.profile {voice}): each one's name, language, quality (default, enhanced, premium) and identifier. lang: a prefix (en, en-GB, fr); default en; all for every language.

| argument | type | notes |
|---|---|---|
| `lang` | string |  |

    staros-tap startune verb voice.voices '{}'

### `voice.where` — low, palette word `where`

Where the song is, in one line: the stage, the section worked, the bar, and the next step suggested; on the guide's line and spoken ("startune, where are we" / "what's next"). next: true says only the next step.

| argument | type | notes |
|---|---|---|
| `next` | boolean |  |

    staros-tap startune verb voice.where '{}'

<details class="changes">
<summary>The work on this page: the commits of the last 30 days on its sources, the work open against them, its checks</summary>

[[timeline: src=love-shared/docs/verbs/startune.md | kinds=commit | days=30]]

[[work: open | src=love-shared/docs/verbs/startune.md]]

[[work: checks | rows=lint/web-reference,lint/verb-sheets]]

</details>

<nav class="pager"><span></span><a href="../../">The reference</a><span></span></nav>

*Generated by `tools/reference_pages.py` from `love-shared/docs/verbs/startune.md`; the twin `bfaad079a7ce` (434093 bytes). The words are a draft.*

</div>
