inset_add
Overlay a clip into a rectangular preview area of a recording, tracking its camera motion, with configurable fades and audio control.
Instructions
Draw a clip into a rectangle of the recording, following its camera — a render inside the app's preview.
rect is where the recording shows what the inset replaces, in the
recording's own pixels, and must be the clip's shape. The inset moves and
zooms with the recording's reframe windows, so a push into the preview
fills the frame with the clip itself, at full sharpness. The span starts
at a word, phrase or event of clip_id and ends at one, at a length, or
at the clip's end; it plays at 1x and must lie inside one continuous, 1x
stretch of the recording (no cut, no retimed span under it).
It fades in and out by default, can dim the recording around it, and plays
its own audio with the music bed out underneath (dipped, with a duck)
unless mute; level="speech" measures it and sets gain_db. The reply
echoes where it plays and dest, where its rect lands in the canvas;
plan=true writes nothing. Any inset routes export through the MLT
writer, and export's reply gives each inset's rect at its first and last
frame.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| dim | No | Darken the recording around the inset, 0 (none, the default) to 1 (black); 0.55 reads well. | |
| mute | No | Play none of the asset's audio (and leave the bed alone). | |
| 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. | |
| rect | Yes | [x0, y0, x1, y1] in the recording's OWN pixels: where the recording shows the thing the inset replaces (a preview pane). Must be the asset's shape, within 1%. | |
| 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 | Yes | The clip to draw, by clip_id: the render an agent made, in a launch clip. Needs picture. | |
| enter | No | How it appears: `fade` or `none` (a cut). Default fade. | |
| event | No | Start on this event of clip_id: `name`, or `name#k` when the name repeats. Usually the moment the recording's own preview starts playing, which locks the two. | |
| leave | No | How it goes: `fade` or `none`. Default fade. | |
| level | No | 'speech' measures the span the inset plays, once, and records the gain_db that brings its speech to -18 dBFS RMS, the launch clip's film level. Not with gain_db. | |
| phrase | No | Start on this phrase's FIRST word, resolved against clip_id's transcript. | |
| src_in | No | Seconds into the asset the inset starts from. Default 0. | |
| clip_id | Yes | The recording the inset is drawn into — its camera (reframe windows) is what the inset follows, and its words or events address the span. | |
| gain_db | No | The asset's own audio level in dB. Default 0. The music bed goes out under it, or dips under it when the bed has a duck. | |
| seconds | No | End this long after the start. | |
| position | No | Where in the stack it goes: 0 is the bottom, omitted is the top. | |
| enter_ease | No | The fade's curve: linear, ease, ease-in or ease-out. Default ease. | |
| leave_ease | No | The fade's curve: linear, ease, ease-in or ease-out. Default ease. | |
| 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 inset 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. | |
| enter_seconds | No | How long the fade in takes. Default 0.4. | |
| leave_seconds | No | How long the fade out takes. Default 0.4. | |
| until_word_index | No | End as this word ends. At most one of until_word_index, until_phrase, until_event or seconds; none runs to the asset's end. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||