<!-- 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. -->

# starsaga · the verbs

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

*The story editor: clips, passes, the render. 91 verbs in 10 categories: 34 undoable, 10 read-only. The app-verbs protocol (`love-shared/docs/app-verbs.md`): `staros-tap starsaga verbs` lists them live, `staros-tap starsaga verb <name> '<json>'` runs one, `activity --since N` reads the journal. Loaded headless from `starsaga` by `scripts/verb_inventory.lua`.*

## app

### `app.quit` — medium

Quit the editor (unsaved edits are saved first; force quits even when that save is refused).

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

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

## fx

### `auto.create` — low, undoable, batchable

Automate a number param: kind ramp | lfo | follow | points | expr | random | step, with optional fields over that kind's default. replace=true swaps an existing spec.

| argument | type | notes |
|---|---|---|
| `clip` | integer | minimum 1 |
| `fields` | object |  |
| `key` | string | required |
| `kind` | string | required; one of ramp, lfo, follow, points, expr, random, step |
| `replace` | boolean |  |
| `uid` | string |  |

    staros-tap starsaga verb auto.create '{"key": "…", "kind": "ramp"}'

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

The automation spec on one param (resolved: a preset's shows too).

| argument | type | notes |
|---|---|---|
| `clip` | integer | minimum 1 |
| `key` | string | required |
| `uid` | string |  |

    staros-tap starsaga verb auto.get '{"key": "…"}'

### `auto.remove` — low, undoable, batchable

Remove the automation on one param (the static value takes over).

| argument | type | notes |
|---|---|---|
| `clip` | integer | minimum 1 |
| `key` | string | required |
| `uid` | string |  |

    staros-tap starsaga verb auto.remove '{"key": "…"}'

### `auto.set_points` — low, undoable, batchable

Write a whole points envelope on one param: pts = [{t, v, easing?}] (t in s; time = clip counts from the capture's frame 0, reset from each reset of the clock). Values outside the param's range are refused, never clamped.

| argument | type | notes |
|---|---|---|
| `clip` | integer | minimum 1 |
| `interp` | string | one of linear, step, smooth |
| `key` | string | required |
| `pts` | array | required |
| `replace` | boolean |  |
| `reset` | string | one of strobe, beat, aonset, none |
| `time` | string | one of reset, clip |
| `uid` | string |  |

    staros-tap starsaga verb auto.set_points '{"key": "…", "pts": []}'

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

Run several batchable calls as ONE edit (one undo step, one journal line): calls = [{verb, args}]. The first refusal puts everything back and is named.

| argument | type | notes |
|---|---|---|
| `calls` | array | required |
| `reason` | string |  |

    staros-tap starsaga verb edit.batch '{"calls": []}'

### `look.apply` — low, undoable, batchable

Put a whole look on a figure-fx clip: look = {preset, fx = [{uid, id, on, params, auto}], fx_v?}, and optionally sets = {plates_dir, depth_dir}. Every pass id, param key and spec is checked first.

| argument | type | notes |
|---|---|---|
| `clip` | integer | minimum 1 |
| `look` | object | required |
| `sets` | object |  |

    staros-tap starsaga verb look.apply '{"look": {}}'

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

A figure-fx clip's passes and their params: value, range, automation.

| argument | type | notes |
|---|---|---|
| `clip` | integer | minimum 1 |
| `uid` | string |  |

    staros-tap starsaga verb param.list '{}'

### `param.set` — low, undoable, batchable, palette word `set`

Set one param of a figure-fx clip (preset / plates_dir / depth_dir, or a pass param by uid+key). reset=true drops the story's override (the look's value shows through).

| argument | type | notes |
|---|---|---|
| `clip` | integer | minimum 1 |
| `key` | string | required |
| `reset` | boolean |  |
| `uid` | string |  |
| `value` | any |  |

    staros-tap starsaga verb param.set '{"key": "…"}'

### `pass.set` — low, undoable, batchable

Turn one pass of a figure-fx clip on or off.

| argument | type | notes |
|---|---|---|
| `clip` | integer | minimum 1 |
| `on` | boolean | required |
| `uid` | string | required |

    staros-tap starsaga verb pass.set '{"uid": "…", "on": true}'

## markers

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

Add a named marker (kind marker), a section start (section) or a section end (end) at at_s -- default: the playhead.

| argument | type | notes |
|---|---|---|
| `at_s` | number |  |
| `kind` | string | one of marker, section, end |
| `name` | string |  |

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

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

The story's markers and sections, and the clips' shots (from cuts.json), in story ms.

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

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

Move a marker (by name or index) to to_s.

| argument | type | notes |
|---|---|---|
| `marker` | any | required |
| `to_s` | number | required |

    staros-tap starsaga verb marker.move '{"marker": "…", "to_s": 0}'

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

Remove a marker, by name or index.

| argument | type | notes |
|---|---|---|
| `marker` | any | required |

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

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

Rename a marker (by name or index).

| argument | type | notes |
|---|---|---|
| `marker` | any | required |
| `name` | string | required |

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

## piece

### `link.open` — low

Open a piece://, board:// or story:// link wherever it belongs (shared.links): a story here, its shot's clip selected; a storyboard or a piece's document in its own app (a running one's tap, a spawn, or a soft handoff on iOS).

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

    staros-tap starsaga verb link.open '{"uri": "…"}'

### `piece.config` — medium

The phone's piece server(s), {servers = [{base, token}]} or {base, token}, into piece.json in the save dir (starlore's file and format), then a fresh media client. A desktop reads its media folder and is refused unless `force`. The token is stored and never echoed.

| argument | type | notes |
|---|---|---|
| `base` | string |  |
| `force` | boolean |  |
| `servers` | array |  |
| `token` | string |  |

    staros-tap starsaga verb piece.config '{}'

### `piece.media` — low

The media client: its source (network, local or none), media.json's state and commit, and how many renders, images and fetches it holds.

    staros-tap starsaga verb piece.media '{}'

### `piece.open` — low

Open a piece's story from the piece snapshot (a phone's synced cache, or a desktop's): `doc` is story (the default) or story~<short id>. Refused over a story this device has of its own.

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

    staros-tap starsaga verb piece.open '{"slug": "…"}'

### `piece.send` — medium

Send the open piece story, saved, as a draft against the base it was opened from: the tower's applier replays its order, trims and caption texts.

    staros-tap starsaga verb piece.send '{}'

### `piece.state` — low

The open story's piece link (piece, doc, base), whether the tower has moved past it, and its draft's state.

    staros-tap starsaga verb piece.state '{}'

### `piece.sync` — low

Ask the phone's piece session for a sync of the snapshot now (after a draft applies the session syncs once, and then every five minutes); the session's status. Never a token.

    staros-tap starsaga verb piece.sync '{}'

## read

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

The editor's compact state: story, clips, selection, playhead, loop, render, undo, busy.

    staros-tap starsaga verb state.get '{}'

## render

### `frame.export` — low, palette word `frame`

Write the frame at the playhead (or `at`: a time in any form the readout takes, which moves the playhead there) as a PNG, as the preview composes it at the story's size with its captions: `stories/<slug>-f<frame>.png` in the save dir unless `path` (relative to the save dir). It is written at the end of the next frame; `activity` carries frame.exported.

| argument | type | notes |
|---|---|---|
| `at` | string |  |
| `path` | string |  |

    staros-tap starsaga verb frame.export '{}'

### `render.start` — medium, palette word `render`

Render the story FILE (saved first): draft = true (default) is the fast draft (NVENC where the machine has it, else libx264 at its fast end), false the full render (`<slug>.mp4`; the operator's names, 2026-10-07: a render is full or a -draft). The export's options (starsaga-production F4): `range` "loop" (the loop's in and out) or `from_ms` / `to_ms` (a `-sel` render); `captions` burn / sidecar / both / none; `size` "WxH"; `audio_only` with `audio_format` m4a / wav; `keep_versions` (the replaced file moves to stories/renders/); `bitc` (a burned-in timecode, drafts only); `open_after` (reveal the folder). Completion arrives in `activity` as render.done / render.failed, naming the file the CLI wrote.

| argument | type | notes |
|---|---|---|
| `audio_format` | string | one of m4a, wav |
| `audio_only` | boolean |  |
| `bitc` | boolean |  |
| `captions` | string | one of burn, sidecar, both, none |
| `draft` | boolean |  |
| `force` | boolean |  |
| `from_ms` | integer | minimum 0 |
| `keep_versions` | boolean |  |
| `open_after` | boolean |  |
| `range` | string |  |
| `size` | string |  |
| `to_ms` | integer | minimum 0 |

    staros-tap starsaga verb render.start '{}'

## stardraw

### `stardraw.close` — low

Hide the StarDraw overlay (its figure stays loaded; stardraw.open or the key brings it back).

    staros-tap starsaga verb stardraw.close '{}'

### `stardraw.open` — low

Open a figure file (a Lua figure, such as one studies' brushwork.py --figure wrote) in StarDraw over the preview. The file runs with no globals and must validate.

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

    staros-tap starsaga verb stardraw.open '{"path": "…"}'

### `stardraw.save` — medium

Save StarDraw's figure to the file it was opened from, or to `path`: the same format, byte for byte when nothing changed.

| argument | type | notes |
|---|---|---|
| `path` | string |  |

    staros-tap starsaga verb stardraw.save '{}'

### `stardraw.state` — low

Whether StarDraw is open; its figure's file, slug, cels, strokes, clips and ledger digest; and whether it changed since it was opened or saved.

    staros-tap starsaga verb stardraw.state '{}'

### `stardraw.trace` — low

Trace the frame at the playhead (a figure clip's plate, its matte and its depth) into strokes on top of StarDraw's active cel, or `cel`: depth plateaus far to near, as one step of StarDraw's undo (Ctrl+R over the canvas). `bands` (4, at most 8) and `eps` (1.2 px of the trace) shape it.

| argument | type | notes |
|---|---|---|
| `bands` | integer | minimum 1 |
| `cel` | string |  |
| `eps` | number |  |

    staros-tap starsaga verb stardraw.trace '{}'

### `stardraw.undo` — low

Undo StarDraw's last edit, from its own history (Ctrl+Z over the canvas). The story's undo is `undo`.

    staros-tap starsaga verb stardraw.undo '{}'

## story

### `audio.add` — low, undoable, batchable, palette word `audio`

Add an audio clip at story time `start_ms` (default 0): `src` an absolute path or a vault:// URI that resolves to a file (the render refuses an entry whose src is not a file), `duration_ms` (default 5000), `volume` 0..1, `label`.

| argument | type | notes |
|---|---|---|
| `duration_ms` | integer | minimum 1 |
| `label` | string |  |
| `src` | string | required |
| `start_ms` | integer | minimum 0 |
| `volume` | number | minimum 0; maximum 1 |

    staros-tap starsaga verb audio.add '{"src": "…"}'

### `audio.move` — low, undoable, batchable, palette word `audiomove`

Place an audio clip (its index, else the selected one, else the only one): `start_ms` in story time and / or `duration_ms` (at least 100 ms). It starts inside the story.

| argument | type | notes |
|---|---|---|
| `audio` | integer | minimum 1 |
| `duration_ms` | integer | minimum 0 |
| `start_ms` | integer | minimum 0 |

    staros-tap starsaga verb audio.move '{}'

### `audio.place` — low, undoable, batchable, palette word `place`

Place a sound from the device's sound store (docs/sound.md): `sound` its sha16; `at` story ms, {shot = "F2"} (that shot's clip's start) or {marker = "name"}, default the playhead; `role` voice|bed|room|cue (default voice); `key` (default <role>:<shot|marker|sound>); `volume` 0..2; `label`. Placing under a key that is there replaces that entry: a take over a scratch line.

| argument | type | notes |
|---|---|---|
| `at` | any | story ms, {shot}, or {marker} |
| `key` | string |  |
| `label` | string |  |
| `role` | string |  |
| `sound` | string | required |
| `volume` | number | minimum 0; maximum 2 |

    staros-tap starsaga verb audio.place '{"sound": "…"}'

### `audio.remove` — low, undoable, batchable, palette word `unaudio`

Remove an audio clip by index (1-based) or by its placement `key` (audio.place's), else the selected one.

| argument | type | notes |
|---|---|---|
| `audio` | integer | minimum 1 |
| `key` | string |  |

    staros-tap starsaga verb audio.remove '{}'

### `audio.voice` — low, undoable, batchable, palette word `voice`

Place a shot's voice line from the device's sound store (docs/sound.md): its newest take, else its scratch line (a synthesized stand-in a final refuses), at the shot's start under voice:<shot>; again, it replaces what is there (a take over its scratch line). `piece` defaults to the piece the story was opened from.

| argument | type | notes |
|---|---|---|
| `piece` | string |  |
| `shot` | string | required |

    staros-tap starsaga verb audio.voice '{"shot": "…"}'

### `camera.clear` — low, undoable, batchable, palette word `uncamera`

Clear a video clip's camera: the cover framing again.

| argument | type | notes |
|---|---|---|
| `clip` | integer | minimum 1 |

    staros-tap starsaga verb camera.clear '{}'

### `camera.key` — low, undoable, batchable, palette word `key`

Add a camera key at clip-local `t_ms` (or replace the key there): `cx`, `cy` 0..1 of the source (default the view's centre there), `zoom` >= 1 (default the zoom there), `ease` into it, `at` the board's voice anchor. Keys stay sorted.

| argument | type | notes |
|---|---|---|
| `at` | string |  |
| `clip` | integer | minimum 1 |
| `cx` | number |  |
| `cy` | number |  |
| `ease` | any |  |
| `t_ms` | integer | required; minimum 0 |
| `zoom` | number |  |

    staros-tap starsaga verb camera.key '{"t_ms": 0}'

### `camera.remove` — low, undoable, batchable, palette word `unkey`

Remove the camera key at clip-local `t_ms`; the last key removed clears the camera.

| argument | type | notes |
|---|---|---|
| `clip` | integer | minimum 1 |
| `t_ms` | integer | required; minimum 0 |

    staros-tap starsaga verb camera.remove '{"t_ms": 0}'

### `camera.set` — low, undoable, batchable, palette word `camera`

Set a video clip's whole camera: `keys` [{t_ms, cx, cy, zoom, ease?, at?}] (t_ms clip-local, cx/cy 0..1 of the source, zoom >= 1, ease a curve name or {kind="bezier", cp1, cp2}), `against` the mp4 sha the keys were authored over. An empty `keys` clears it.

| argument | type | notes |
|---|---|---|
| `against` | string |  |
| `clip` | integer | minimum 1 |
| `keys` | array | required |

    staros-tap starsaga verb camera.set '{"keys": []}'

### `caption.add` — low, undoable, batchable, palette word `card`

Add a caption: `text` over [start_ms, end_ms), or over clip `clip`'s span when the times are left out; `align` bottom/top/center; `style` a named preset; `anchor` {clip, x, y} a point in that clip's source frame; `speaker`.

| argument | type | notes |
|---|---|---|
| `align` | string | one of bottom, top, center |
| `anchor` | object |  |
| `clip` | integer | minimum 1 |
| `end_ms` | integer | minimum 0 |
| `speaker` | string |  |
| `start_ms` | integer | minimum 0 |
| `style` | string |  |
| `text` | string | required |

    staros-tap starsaga verb caption.add '{"text": "…"}'

### `caption.import` — low, undoable, batchable, palette word `subs`

Read an SRT or WebVTT file into the story's captions (love-shared text_fx/srt_read: tags stripped, cue settings dropped), shifted by `offset_ms`; `replace` empties the captions first. One undo step. A cue past the story's end is kept and counted.

| argument | type | notes |
|---|---|---|
| `offset_ms` | integer |  |
| `path` | string | required |
| `replace` | boolean |  |

    staros-tap starsaga verb caption.import '{"path": "…"}'

### `caption.retime` — low, undoable, batchable, palette word `retime`

Move a caption (its index, as the timeline numbers them, else the selected one): `start_ms` and / or `end_ms`, or `shift_ms` for the whole cue (with `ripple`, the cues after it in the same clip move too). A caption stays inside the story and at least a frame long.

| argument | type | notes |
|---|---|---|
| `caption` | integer | minimum 1 |
| `end_ms` | integer | minimum 0 |
| `ripple` | boolean |  |
| `shift_ms` | integer |  |
| `start_ms` | integer | minimum 0 |

    staros-tap starsaga verb caption.retime '{}'

### `caption.set` — low, undoable, batchable, palette word `caption`

Set the caption a clip owns (its shot's, else the first laid inside it), creating one over the clip when it has none; or, with `caption` (its index, as the timeline numbers them), that caption's text.

| argument | type | notes |
|---|---|---|
| `caption` | integer | minimum 1 |
| `clip` | integer | minimum 1 |
| `text` | string | required |

    staros-tap starsaga verb caption.set '{"text": "…"}'

### `caption.words` — low, undoable, batchable, palette word `words`

Fill captions' karaoke words from the voice placed under them (docs/sound.md): each caption (`caption` its index, else every one) takes the words of the placed sound covering its start, timed from the cue and found in its text in order. A caption that has words keeps them unless `force`; a voice whose words are not here yet is asked of the device's sync.

| argument | type | notes |
|---|---|---|
| `caption` | integer | minimum 1 |
| `force` | boolean |  |

    staros-tap starsaga verb caption.words '{}'

### `clip.add` — low, undoable, batchable, palette word `add`

Add a clip: `kind` video, screenshot or tape (with `src`), or motion (with `template` and an optional `capture` table). `duration_ms` defaults by kind (video 5000, screenshot 2500, motion the template's); `at` places it (1-based, default the end); `fit` cover, contain or blur-fill; `label`.

| argument | type | notes |
|---|---|---|
| `at` | integer | minimum 1 |
| `capture` | object |  |
| `duration_ms` | integer | minimum 1 |
| `fit` | string | one of cover, contain, blur-fill |
| `kind` | string | required |
| `label` | string |  |
| `src` | string |  |
| `start_ms` | integer | minimum 0 |
| `template` | string |  |
| `template_params` | object |  |

    staros-tap starsaga verb clip.add '{"kind": "…"}'

### `clip.move` — low, undoable, batchable, palette word `move`

Move a clip to position `to` (1-based). Its own captions (its shot's, and any laid inside it) and its markers move with it; a caption across clips stays where it is. Transitions follow their clips, or drop when the two are no longer neighbours.

| argument | type | notes |
|---|---|---|
| `clip` | integer | minimum 1 |
| `to` | integer | required; minimum 1 |

    staros-tap starsaga verb clip.move '{"to": 0}'

### `clip.remove` — low, undoable, batchable, palette word `remove`

Remove a clip. A transition it dressed goes with it; captions keep their story time (a shot's caption is reported).

| argument | type | notes |
|---|---|---|
| `clip` | integer | minimum 1 |

    staros-tap starsaga verb clip.remove '{}'

### `clip.set` — low, undoable, batchable, palette word `clipset`

Set a clip's times: `duration_ms`, or, for a clip with a source range (tape, video, a motion with plates), `src_in_ms` and / or `src_out_ms` (the in point alone keeps the out point; the out point alone keeps the in point; the in point with duration_ms sets both). A clip is never shorter than 100 ms nor longer than its source.

| argument | type | notes |
|---|---|---|
| `clip` | integer | minimum 1 |
| `duration_ms` | integer | minimum 0 |
| `src_in_ms` | integer | minimum 0 |
| `src_out_ms` | integer | minimum 0 |

    staros-tap starsaga verb clip.set '{}'

### `clip.trim` — low, undoable, batchable, palette word `trim`

Lengthen (+) or shorten (-) a clip: `ms` milliseconds, or `frames` at the story's fps. A clip is never shorter than 100 ms, nor lengthened past its source's end (a board clip's source is its shot's render).

| argument | type | notes |
|---|---|---|
| `clip` | integer | minimum 1 |
| `frames` | integer |  |
| `ms` | integer |  |

    staros-tap starsaga verb clip.trim '{}'

### `figure.add` — low, undoable, batchable, palette word `figure`

Add a figure's clip to the story as a clip of its own length (a brushwork page's `reading`, by default): the `figure` motion template. `path` defaults to the figure open in StarDraw; `at` places it (1-based, default the end); `fit` is contain or cover.

| argument | type | notes |
|---|---|---|
| `at` | integer | minimum 1 |
| `clip` | string |  |
| `fit` | string | one of contain, cover |
| `path` | string |  |

    staros-tap starsaga verb figure.add '{}'

### `files.drop` — low, undoable

Files put into the story as ONE undo step (what a drop on the window does): a video (mp4/mov/webm/mkv/m4v) or an image (png/jpg/jpeg/webp) is a clip inserted at `at` (1-based; default the end; several in the order given), a .tape.json a tape clip, a sound (wav/mp3/ogg/flac) an audio clip from `start_ms` (default 0), an .srt / .vtt the captions shifted by `offset_ms`; a folder (a path ending in /) is mounted, first (a mount is not undone with the step). The first refusal puts the story back, named by file; an unknown file is refused before anything moves. A story is story.import's. A file outside every mount is kept as its absolute path.

| argument | type | notes |
|---|---|---|
| `at` | integer | minimum 1 |
| `offset_ms` | integer |  |
| `paths` | array | required |
| `start_ms` | integer | minimum 0 |

    staros-tap starsaga verb files.drop '{"paths": []}'

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

Redo the last undone edit (`expect` as for undo).

| argument | type | notes |
|---|---|---|
| `expect` | string |  |

    staros-tap starsaga verb redo '{}'

### `story.export` — low, palette word `bundle`

Write the open story as a portable folder, `<dir>/<slug>.saga` (stories/ by default): its story.json pointing at its own assets/, a vault.json mounting them, every file it uses copied once (`staros story bundle`'s layout, made by the editor itself). A folder that exists is refused (force replaces it).

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

    staros-tap starsaga verb story.export '{}'

### `story.import` — low, palette word `import`

Take a story in and open it: a story `.json` (checked as the app reads one: known clip kinds, cuts counted from 1, captions that end after they start) or a `.saga` folder (its assets mounted as `bundle-<slug>`). The slug is the file's own unless `slug`; one that exists is refused (`force` replaces it, `fresh` takes the next free `<slug>-N`: a drop on the window does), and the open story's own slug always is. The save dir's own story file is opened, not copied.

| argument | type | notes |
|---|---|---|
| `force` | boolean |  |
| `fresh` | boolean |  |
| `path` | string | required |
| `slug` | string |  |

    staros-tap starsaga verb story.import '{"path": "…"}'

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

The stories in the save dir (not -sel / -proj / backups).

    staros-tap starsaga verb story.list '{}'

### `story.new` — low, palette word `new`

Create a story and open it: `stories/<slug>.json`, empty or scaffolded from a built-in story `shape` (Ctrl+N's `slug:shape`), at a `preset` (story, reel, short, landscape, classic, square, portrait).

| argument | type | notes |
|---|---|---|
| `preset` | string |  |
| `shape` | string |  |
| `slug` | string | required |

    staros-tap starsaga verb story.new '{"slug": "…"}'

### `story.open` — low, palette word `open`

Open another story (the current one is saved first if it has unsaved edits). `sample` opens a story the app ships (stories-sample/<name>.json: `hello`), copied into stories/ first unless it is there.

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

    staros-tap starsaga verb story.open '{}'

### `story.reload` — medium

Adopt the story FILE (what a script wrote while the editor was open), as one undoable step.

    staros-tap starsaga verb story.reload '{}'

### `story.save` — medium

Save the story now. Refused when its file changed on disk (story.reload adopts the file; force overwrites it).

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

    staros-tap starsaga verb story.save '{}'

### `story.save_as` — low, palette word `saveas`

Save the open story as a new slug and go on editing the copy (its undo history with it); the old file stays as it was last saved. A slug that exists is refused (force overwrites it).

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

    staros-tap starsaga verb story.save_as '{"slug": "…"}'

### `story.set_fps` — low, undoable, batchable, palette word `fps`

Set the story's frame rate: one of 24, 25, 30, 60. Times stay in ms, so nothing moves; the frame grid, the ruler, a snap and a typed frame follow the new rate.

| argument | type | notes |
|---|---|---|
| `fps` | number | required |

    staros-tap starsaga verb story.set_fps '{"fps": 0}'

### `transition.set` — low, undoable, batchable, palette word `transition`

Set the transition on the boundary after clip `left` (1-based): `kind` from the semantic vocabulary (crossfade, moment-to-moment, action-to-action, …) or `none` to remove it; `duration_ms` (default 250, never longer than either clip); `realise` names a realisation; `dir` left/right/up/down. Without `kind`, the boundary's own transition keeps its kind and takes the rest (a typed duration).

| argument | type | notes |
|---|---|---|
| `dir` | string | one of left, right, up, down |
| `duration_ms` | integer | minimum 0 |
| `kind` | string |  |
| `left` | integer | required; minimum 1 |
| `realise` | string |  |

    staros-tap starsaga verb transition.set '{"left": 0}'

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

Undo the last edit. `expect` (the reason state.undo.next shows) refuses if another edit is on top.

| argument | type | notes |
|---|---|---|
| `expect` | string |  |

    staros-tap starsaga verb undo '{}'

## ui

### `ui.close` — low

Close the UI editor's overlay.

    staros-tap starsaga verb ui.close '{}'

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

A colour's value and its hex, a house table's ([theme.color], [base.color]) or one the app registered; or a named motion's value (motion.toast.slide ms); or a layout token's step and px ([theme.corner] button).

| argument | type | notes |
|---|---|---|
| `key` | string | required |
| `table` | string | required; one of aesthetic.panel, aesthetic.substrate, aesthetic.themed, app_accent, base.color, base.radius, base.space, launcher.color, motion.card.enter, motion.card.exit, motion.card.flash, motion.card.reveal, motion.caret.blink, motion.feed.follow, motion.list.scroll, motion.overlay.fade_in, motion.overlay.fade_out, motion.panel.slide, motion.prompt.pulse, motion.toast.fade, motion.toast.life, motion.toast.pulse, motion.toast.slide, palette, starboard.color, starlore.color, starsaga.color, startune.color, startune.phone, startune.section, theme.color, theme.corner, theme.inset, theme.pad, theme.radius |

    staros-tap starsaga verb ui.get '{"table": "aesthetic.panel", "key": "…"}'

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

The widgets the last frame drew while the overlay is open: kind, rect, and each colour role with its owner.

| argument | type | notes |
|---|---|---|
| `limit` | integer | minimum 1 |

    staros-tap starsaga verb ui.inspect '{}'

### `ui.open` — low

Open the in-app UI editor's overlay (the widgets note what they draw while it is open).

    staros-tap starsaga verb ui.open '{}'

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

The unsaved changes as the writer's ops (token ops, and the shell document when it was edited).

    staros-tap starsaga verb ui.ops '{}'

### `ui.revert` — low

Put every unsaved change back as it was.

    staros-tap starsaga verb ui.revert '{}'

### `ui.save` — medium

Write the unsaved changes through scripts/ui_edit.py: tokens.toml (the floors checked first) and the shell document (the format checked first; dry_run reports without writing).

| argument | type | notes |
|---|---|---|
| `dry_run` | boolean |  |

    staros-tap starsaga verb ui.save '{}'

### `ui.set` — low

Change a colour live, a house table's or one the app registered (hex or [r, g, b, a] in 0..1): the next frame draws it. Or a named motion's value (a number, or a name: an easing, a law, a shape): the next motion that starts takes it. Or a layout token's step ("radius.2" for [theme.corner] button): the next frame draws it. Unsaved until ui.save.

| argument | type | notes |
|---|---|---|
| `key` | string | required |
| `table` | string | required; one of aesthetic.panel, aesthetic.substrate, aesthetic.themed, app_accent, base.color, base.radius, base.space, launcher.color, motion.card.enter, motion.card.exit, motion.card.flash, motion.card.reveal, motion.caret.blink, motion.feed.follow, motion.list.scroll, motion.overlay.fade_in, motion.overlay.fade_out, motion.panel.slide, motion.prompt.pulse, motion.toast.fade, motion.toast.life, motion.toast.pulse, motion.toast.slide, palette, starboard.color, starlore.color, starsaga.color, startune.color, startune.phone, startune.section, theme.color, theme.corner, theme.inset, theme.pad, theme.radius |
| `value` | any | required |

    staros-tap starsaga verb ui.set '{"table": "aesthetic.panel", "key": "…", "value": "…"}'

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

The app's shell document as the editor holds it (docs/formats/shell.md): its file, identity, panes, toolbar rows, sheet, seed, keys, docks and rooms, and whether it is unsaved.

    staros-tap starsaga verb ui.shell '{}'

### `ui.shell_insert` — low

Insert a row before row i of a list (the path ends in [i]: toolbar[2], sheet[1], panes[17]); the value is the row. Checked first; unsaved until ui.save.

| argument | type | notes |
|---|---|---|
| `path` | string | required |
| `value` | any | required |

    staros-tap starsaga verb ui.shell_insert '{"path": "…", "value": "…"}'

### `ui.shell_move` — low

Move a row of a list (toolbar, sheet, panes, rooms.order) from one position to another. Unsaved until ui.save.

| argument | type | notes |
|---|---|---|
| `from` | integer | required; minimum 1 |
| `list` | string | one of toolbar, sheet, panes, rooms.order |
| `to` | integer | required; minimum 1 |

    staros-tap starsaga verb ui.shell_move '{"from": 0, "to": 0}'

### `ui.shell_remove` — low

Remove what a path names: a row (toolbar[3]), a key (keys.zoom), a dock or a room (docks.library, rooms.list.loop). Checked first; unsaved until ui.save.

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

    staros-tap starsaga verb ui.shell_remove '{"path": "…"}'

### `ui.shell_set` — low

Set what a path into the shell document names, live (toolbar[3].label, sheet[2].action, panes[17], keys.close, docks.terminal.ratio, rooms.active, rooms.list.loop.title, seed.first.ratio; a name on the way is made, an index is not); the format's check runs on a copy first. Unsaved until ui.save.

| argument | type | notes |
|---|---|---|
| `path` | string | required |
| `value` | any | required |

    staros-tap starsaga verb ui.shell_set '{"path": "…", "value": "…"}'

## view

### `clip.select` — low, palette word `select`

Select a clip (0 = none): its automation lanes and inspector section show.

| argument | type | notes |
|---|---|---|
| `clip` | integer | required; minimum 0 |

    staros-tap starsaga verb clip.select '{"clip": 0}'

### `loop.clear` — low

Clear the loop range.

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

### `loop.clip` — low

Loop a whole clip (default: the selected one).

| argument | type | notes |
|---|---|---|
| `clip` | integer | minimum 1 |

    staros-tap starsaga verb loop.clip '{}'

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

Set the loop range in story seconds (snapped to frames) and turn it on.

| argument | type | notes |
|---|---|---|
| `in_s` | number | required |
| `on` | boolean |  |
| `out_s` | number | required |

    staros-tap starsaga verb loop.set '{"in_s": 0, "out_s": 0}'

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

Move the playhead: exactly one of s, ms, frame or tc (a time as text: 1:02.5, 00:01:02:15, 62.5s, f1875; +15f or -2s relative to the playhead).

| argument | type | notes |
|---|---|---|
| `frame` | integer | minimum 0 |
| `ms` | number |  |
| `s` | number |  |
| `tc` | string |  |

    staros-tap starsaga verb playhead.seek '{}'

### `playhead.step` — low, palette word `step`

Move the playhead n stops (signed; default 1) by frames, edits (cuts, captions, loop, marks) or markers (marks and shots).

| argument | type | notes |
|---|---|---|
| `by` | string | one of frames, edits, markers |
| `n` | integer |  |

    staros-tap starsaga verb playhead.step '{}'

### `section.loop` — low

Loop a stored section by name (n: the n-th of that name).

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

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

### `shot.loop` — low, palette word `shot`

Loop one shot of the clip (its capture's cuts.json): n, or the shot under the playhead.

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

    staros-tap starsaga verb shot.loop '{}'

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

Move the playhead to a marker or section (by name; n: the n-th match) or to 'shot N'.

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

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

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

Join a desk's clock (loopback timecode): this playhead leads or follows the master.

| argument | type | notes |
|---|---|---|
| `desk` | string |  |

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

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

Stop playback.

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

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

Start playback (inside the loop when one is on).

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

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

Who leads the desk's clock, and how far this playhead is from the master's time.

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

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

Leave the desk's clock: this playhead is the editor's own again.

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

<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/starsaga.md | kinds=commit | days=30]]

[[work: open | src=love-shared/docs/verbs/starsaga.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/starsaga.md`; the twin `bfaad079a7ce` (434093 bytes). The words are a draft.*

</div>
