cue_add
Adds a picture cue to start showing an asset at a chosen word or phrase in a transcript, optionally pinning the source in-point. Refuses duplicates and ambiguous matches.
Instructions
Add a picture cue: from word_index of clip_id onward, show asset.
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.
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. | |
| 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. | |
| 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. | |
| word_index | No | The word the picture starts on, in `clip_id`'s transcript. Give this or `phrase`, not both. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||