speech_overlap
Check if placing a clip at a proposed timeline position would overlap voice-over speech, before designing audio ducking. Identifies clean gaps wide enough for the clip to speak without touching the VO, using transcript or energy evidence.
Instructions
Does a proposed placement of clip_id overlap the VO's speech?
The prerequisite check behind "can this clip speak here?" — answer it
before designing any ducking. at/clip_in/clip_out describe where
clip_id would sit on the timeline (defaults: unplaced at 0, its whole
duration) — the clip need not be on the timeline yet, and usually isn't,
since the current model is single-track. VO's own words map through the
existing edit (Edit.timeline_span); clip_id's map by offsetting into
the proposed window instead. Both sides are trimmed with
energy.believable first — an inflated word duration can hide a real
seam — then merged into speech runs with max_gap tolerance, since a
0.05s gap is not a usable seam.
Read overlaps first: any entry means placing clip_id there would step
on VO speech, not empty air — this caught exactly that on Billy/Stu,
where the clip's speech nearly fully covered a VO thesis line with no
clean seam to duck into. clean_seams (>= min_seam wide) are the
windows where clip_id could speak without touching the VO. Read-only —
nothing is written, and there is no plan=.
clip_id need not have a transcript. Without one the clip side is its
energy envelope — runs of sound, reported as sound rather than speech (a
sting or a swell counts too) — and clip_evidence in the result says
"energy" so the reading is not mistaken for a word-level one. Pass
clip_evidence="transcript" to refuse instead, or "energy" to force the
envelope on a clip that has a transcript. The VO always needs its
transcript.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| at | No | Where the clip would sit on the timeline, in seconds. | |
| cap | No | How far a word's claimed duration is trusted, as a multiple of the median. Whisper inflates the word after a collapsed retake until it covers the second take, so believing the claim masks exactly the hole being looked for — 3x is the same multiple a suspect duration is flagged at. | |
| 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. | |
| clip_id | Yes | The clip whose placement is being proposed. It need not be on the timeline yet, and usually is not. | |
| clip_in | No | Where inside the clip the proposed placement starts, in its own source seconds. Unset, its head. | |
| max_gap | No | How short a silence may be and still be swallowed into one speech run, in seconds — a 0.05s gap is not a usable seam. | |
| clip_out | No | Where it ends, in the clip's own source seconds. Unset, its end. | |
| min_seam | No | How wide a gap has to be to be reported as a `clean_seam`, in seconds. | |
| vo_clip_id | No | Which transcript is the VO. Unset, the project's own. The VO always needs a transcript; the placed clip does not. | |
| clip_evidence | No | `auto` (the default) uses the clip's transcript if it has one and its energy envelope otherwise, saying which in the result. `transcript` refuses a clip with none; `energy` forces the envelope even on a clip that has one — sound rather than speech, which counts a sting or a swell too. | auto |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||