caption_span_add
Idempotent
Add a caption span to change caption style or disable captions over a specific segment of a clip, with start and end defined by word, phrase, event, or duration.
Instructions
Captions off over a stretch of the film, or a different look there.
off=True draws none (over an end card or logo). style changes
caption_style fields over the span only; {"max_words": 1, "size": 150, "position": "middle"} over one word draws it alone and large, a beat
inside ordinary lines. Addressed like overlay_add: start at a word,
phrase or event; end at a word, phrase, event or length. A line never
crosses a span's edge; later spans win where two overlap. caption_view
draws the result; add_captions writes it.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| off | No | Draw no captions over the span. Give this or `style`. | |
| 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. | |
| plan | No | Resolve the whole call and report what it would do, writing nothing. Prefer it over doing the thing and undoing it. | |
| 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. | |
| event | No | Start on this event of clip_id: `name`, or `name#k` when the name repeats. | |
| style | No | caption_style fields (any but `preset`) that differ over the span, on top of the project's look: {"max_words": 1, "size": 150, "position": "middle"} draws each word alone and large. Give this or `off`. | |
| phrase | No | Start on this phrase's FIRST word, resolved against clip_id's transcript. | |
| clip_id | Yes | The clip whose words or events address the span — the transcript the word indices index, or the recording the events belong to. | |
| seconds | No | End this long after the start. | |
| 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 span starts on. One of word_index, phrase or event. | |
| until_event | No | End on this event of clip_id. | |
| until_phrase | No | End as this phrase's LAST word ends. | |
| until_word_index | No | End as this word ends. One of until_word_index, until_phrase, until_event or seconds. |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||