hold_add
Insert a gap in the voiceover after a specified word, cue an asset's picture and audio in that gap with margins, and refuse if it cannot fit.
Instructions
Splice a hold into clip_id after gap_word_index: a real gap opens
in the VO (vo_extend's own mechanism, reused) and a picture cue pins
asset's own in-point, snapped to whole words with margin and
refused, never clamped, when it cannot fit.
Addressed by (clip_id, gap_word_index), unique — a second hold_add at
the same address is refused. gap_word_index/cue_word_index/
word_index_first+word_index_last each also accept a phrase
alternative: gap_phrase binds its last word (the gap opens right
after it), cue_phrase binds its first, and asset_phrase resolves
against asset's own transcript and binds its first and last words to
word_index_first/word_index_last together.
Everything else is resolved live: elapsed (how long the VO plays
between the cue and the gap), src_start (deterministically —
phrase_start - elapsed - head_margin), and hold_length (the phrase's
own span plus both margins). Refused, with the measured numbers, when
there is no room or the asset runs out.
Mix-only fields (head_margin/tail_margin/under/fade_in/
fade_out) are re-settable on an already-spliced hold by calling again
with the same address and no change to word_index_first/
word_index_last — those two are one-way once spliced (hold_rm then
hold_add again, or proofcut undo, are the only ways to resize one).
plan=True resolves and reports without writing anything.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"clip_id": "<clip_id>"
},
"name": "hold_add"
}
}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. | |
| 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 the matches of `gap_phrase`/`cue_phrase`/`asset_phrase`: any match at or before this word index is skipped. -1, the default, means from the start. | |
| asset | No | The film clip whose own audio plays in the gap, and whose picture the cue pins. | |
| under | No | How far below the VO the held audio sits, in LU. Re-settable. | |
| clip_id | Yes | The VO track the gap opens in. | |
| fade_in | No | Seconds of fade as the held audio comes in. Re-settable. | |
| fade_out | No | Seconds of fade as it goes out. Re-settable. | |
| cue_phrase | No | Address the cue by wording; it binds its **first** word. | |
| gap_phrase | No | Address the gap by wording; it binds its **last** word, since the gap opens right after it. | |
| occurrence | No | Disambiguate `gap_phrase`/`cue_phrase`/`asset_phrase` by count, **1-based**. Unset, an ambiguous phrase is refused rather than guessed at. | |
| head_margin | No | Seconds kept before the line, so it does not start on the word. Re-settable on an already-spliced hold. | |
| tail_margin | No | Seconds kept after the line. Re-settable. | |
| asset_phrase | No | The line to play, resolved against `asset`'s **own** transcript, binding its first and last words together. One phrase is the source of truth for both ends; hand-typed indices drift the moment a transcript changes under them. | |
| cue_word_index | No | The word the picture cue for `asset` is placed on. | |
| gap_word_index | No | The word the gap opens right after. With `clip_id` it is the hold's address, and a second `hold_add` at the same address is refused. | |
| word_index_last | No | Last word of that line. With `word_index_first` it is one-way once spliced: resizing means `hold_rm` then `hold_add`, or `undo`. | |
| word_index_first | No | First word of the line to play, in **`asset`'s own** transcript — not the VO's. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||