starsaga · the verbs
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~
| 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 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: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/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 '{}'
The work on this page: the commits of the last 30 days on its sources, the work open against them, its checks
love-shared dc4002bverbs: starsaga's sheet regenerated (render.start: a draft is NVENC where the machine has it, else libx264)
love-shared 687dea3text_fx/srt_read: an SRT or WebVTT read in; story: square and portrait; spawn: env on POSIX; starsaga's verb sheet with its ui verbs (starsaga-production F3, F6, T11)
love-shared 27797b4docs/verbs: startune song.story (the song as a lyric cut in StarSaga, 228 verbs) and starsaga story.new, regenerated (2026-11-03, the M2; startune 88091f2, starsaga 06d56b6)
love-shared 418eb44the shell as data (D5): the UI editor's shell tab — the app's shell document edited in place (the toolbar's rows moved, a label typed, a button put on the phone, the seed's ratio nudged), every change checked against the format on a copy before it lands; ui.shell / ui.shell_set / ui.shell_move; ui.save writes it through ui_edit.py's one shell op (the file under the root, the cart reader's check run by luajit from starterm/, the format's key order, a reformat no change, launcher/wall.json regenerates unit D7); the tests (87 Lua, 21 Python); the launcher's verb sheet
love-shared 720fa5fthe verbs as content: scripts/verb_inventory.lua (an app's registry loaded headless, as JSON) and scripts/verb_sheet.py (docs/verbs/<app>.md and .html in the catalog's look, index.md; --check holds them to the registries: launcher 16, startune 161, starsaga 60 verbs); the UI editor's verbs tab (the editor's ops as journaled registry verbs, the tap's ui.* kinds through the registry, every verb listed, a run line, the journal's tail; textinput hooked); _ui_edit_test +20; docs/app-verbs.md, ui_conventions §14, the crib
The work record as of , from the fold on tower.
Nothing open against these sources.
- FAIL
lint/web-reference - NOT RUN
lint/verb-sheets
Generated by tools/reference_pages.py from love-shared/docs/verbs/starsaga.md; the twin bfaad079a7ce (434093 bytes). The words are a draft.