starsaga · the verbs

this page as plaintext

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

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~. 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 :<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:; 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/.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": "…"}'

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 '{}'

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 dc4002b verbs: starsaga's sheet regenerated (render.start: a draft is NVENC where the machine has it, else libx264)

  • love-shared 687dea3 text_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 27797b4 docs/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 418eb44 the 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 720fa5f the 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.

  • FAILlint/web-reference 12 Nov on tower
  • NOT RUNlint/verb-sheets 12 Nov on tower

Generated by tools/reference_pages.py from love-shared/docs/verbs/starsaga.md; the twin bfaad079a7ce (434093 bytes). The words are a draft.