head
Manage a project's cold open: read, set, update, reset, or plan its asset, duration, fades, and gain. Resolve and validate without writing when planning.
Instructions
Read or change the cold open this project plays before its first frame.
tail's mirror at the other end of the film — the same read/partial-
update/reset/plan shape — but its asset rule runs the other way:
asset must be a registered clip_id, never card:name. A cold open is
real footage with real dialogue by definition; tail forbids that
because verify would gain a permanent disagreement it can never
resolve, and a head is taught to account for its own words instead
(verify's head_words_trimmed) rather than being restricted to
silence. Call it with no arguments to read what is in force.
Setting asset or seconds for the first time needs both together;
either alone after that updates just that field, tail's partial-update
shape. src_start defaults to 0.0 on a first set. fade_in/fade_out
default to 0.0 and — unlike tail's fade — are drawn from day one,
the whole reason this feature exists (a hard butt-join between room tone
and digital silence is exactly the seam a missing fade produces).
gain_db defaults to 0.0, a flat non-fading level shift distinct from
the fades.
Joins the cues' picture lane, or with none the timeline's own track; a
sound-only film with no cues is refused. reset drops the
head entirely. plan resolves and validates
without writing.
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. | |
| asset | No | The footage the cold open plays, as a registered clip id — never `card:name`. A cold open is real footage with real dialogue by definition, and `verify` accounts for its words rather than forbidding them. | |
| reset | No | Drop the cold open entirely. | |
| fade_in | No | Seconds of fade at the head. Unlike `tail`'s fade this is drawn, and it is the whole reason the feature exists — a hard butt-join between room tone and digital silence is exactly the seam a missing fade produces. | |
| gain_db | No | A flat level shift for the cold open, in dB, distinct from the fades. 0.0 is unity. | |
| seconds | No | How long the cold open runs. Setting `asset` or `seconds` for the first time needs both together; either alone afterwards updates just that field. | |
| fade_out | No | Seconds of fade where the cold open hands over to the film. | |
| src_start | No | Where inside that asset the cold open reads from, in source seconds. 0.0 on a first set. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||