cue_add
Places a visual asset at a chosen word or event in a transcript, starting the shot exactly there. Handles phrase lookup, source in-point, and cut effects like dissolve or punch.
Instructions
Add a picture cue: from word_index of clip_id onward, show asset.
Or from an event of clip_id, for a recording with no words.
Source-addressed like a word range — asset is an opaque key or path,
not checked against disk here; build_shots resolves it, the same way
assemble_scream.py's CUES table did by hand. Refused if a cue already
sits at that exact word; cue_rm it first to replace it. Echoes the
resolved word plus three either side, the same convention every
word-indexed tool follows.
Addressed by word_index or phrase (exactly one) — a phrase binds
to its first word ("from this word onward"). after/occurrence
disambiguate a phrase matching more than once; a resolved phrase is
stored alongside the word index, additive metadata cue_reresolve can
re-derive after a re-record.
src_start pins where inside asset the shot reads from: seconds in
that asset's own source time, which is exactly the number describe_ls
reports for a window. This is how a moment you found with describe gets
placed — without it the shot reads from wherever the per-asset cursor
had got to, which is right for re-using a clip and wrong for showing the
thing you searched for.
It is an in-point and never a range: the out-point stays derived from the
next cue through the edit, so a later cut still renumbers the shot
correctly. The cost is a refusal instead of a rewind — if the shot's
length runs past the end of the asset from that in-point, build_shots
and the picture lane report it rather than quietly showing the asset's
opening seconds instead. Shorten the shot with another cue, or pin
earlier. A card takes no src_start; a held frame has no playhead.
dissolve and punch are the cut's effects, as cue_set sets them.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| path | No | The project directory to act on. Omit it — the usual case — when this server is bound to a project (started as `proofcut -C DIR mcp`, or inside a project; `ping` says which): it then resolves to that one bound project, a relative path resolves against it, and a path outside it is refused by name. Unbound, `path` is the whole address and omitting it refuses rather than guessing. | |
| after | No | A forward cursor over a phrase's matches: any match at or before this word index is skipped. -1, the default, means from the start. | |
| asset | No | What to show from that word onward: a registered clip id, or `card:<name>` for a card. An opaque key here, resolved by `build_shots` rather than checked against disk now. | |
| event | No | Start the picture on this event of clip_id instead of a word: `name`, or `name#k` when the name repeats — a screen recording's logged moments, for a clip with no transcript. Not with word_index or phrase. | |
| punch | No | A scale punch from the cut, about the canvas centre: 1.1 zooms in 10%. Not with a dissolve on the same cue. | |
| phrase | No | Address the cue by what is said instead of by index. It binds to the phrase's **first** word — "from this word onward". | |
| clip_id | Yes | The transcript the cue is addressed against — the VO on a voiceover project, not the footage being shown. `asset` is what gets seen. | |
| dissolve | No | Crossfade into this cue over this many seconds: the incoming shot's frames before its in-point fade in, reaching the shot on the cue's word. Where the clip has none (an unpinned first use), the outgoing shot fades out from the word instead. | |
| src_start | No | Where inside `asset` the shot reads from, in that asset's own source seconds — the number `describe_ls` reports for a window. An in-point and never a range: unpinned, the shot reads from wherever the per-asset cursor had got to, which is right for re-using a clip and wrong for showing the thing you searched for. A card takes none. | |
| occurrence | No | Disambiguate a phrase by count when it matches more than once, **1-based** in transcript order among the matches after `after`: 1 is the first, 2 the second. Unset, an ambiguous phrase is refused — listing every candidate's range and text — rather than guessed at. | |
| punch_ease | No | The punch's curve. Default ease-out. | |
| punch_mode | No | `in` (default) zooms to `punch` and holds for the shot; `settle` starts there and eases back. | |
| word_index | No | The word the picture starts on, in `clip_id`'s transcript. Give this or `phrase`, not both. | |
| dissolve_ease | No | The crossfade's curve: linear (the default), ease, ease-in or ease-out. | |
| punch_seconds | No | How long the punch moves. Default 0.2. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||