music
Set or read the background music bed under a project: place it by voice-over words or events, and control levels, fades, ducking, and additional passages.
Instructions
Read or change the A2 music bed this project mixes under its edit.
Call with no arguments to read what is in force. The bed stores word
indices and an asset, never a length: it starts where word_index_start
of clip_id (the VO transcript) lands on the timeline and runs to where
word_index_end ends — or to the end of the edit — so a cut before either
boundary moves both. Duration is derived at build time. On a recording
with no words, event/until_event (and a passage's event) address
its logged events instead.
The first set needs asset, clip_id and a start (word_index_start or
phrase_start) together; after that each field updates on its own. A
field set by phrase stores the phrase beside the index it resolved to, so
cue_reresolve can re-derive it; set by plain index, the stored phrase is
cleared. Both boundaries are echoed with their resolved words and
neighbours — check them.
Beyond one asset from its head: passages (more pieces, each from its own
word), rotate (assets in turn), crossfade, src_in; under levels the
bed below the voice, or loudness to a LUFS where there is no voice;
duck dips it while the voice speaks, keyed off the
edit's own audio, audible insets and ducks sounds at export;
over_tail plays it on under the end card. export's music field says what the render
carried. clear_* and reset undo each; plan validates without writing.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| duck | No | Pull the bed this many dB down while the voice is speaking and let it back up in the pauses. It is keyed off the timeline's own audio at export rather than the transcript's word timings, which were measured against a bed recovered from a real render and beaten: 2.72 dB off for the audio gate against a word-span duck's 3.39. It also hears audible insets and sounds placed with `ducks`. | |
| 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 `phrase_start`/`phrase_end`: any match at or before this word index is skipped. -1, the default, means from the start. | |
| asset | No | The bed's own music, as a registered clip id — never `card:name`, since a held frame has no sound. It plays from its own head; shorter than its span pads with real silence, longer is trimmed. | |
| event | No | Start the bed on this event of clip_id instead of a word: `name`, or `name#k` when the name repeats. Replaces a start word. | |
| reset | No | Drop the bed entirely. | |
| under | No | Level the whole bed this many LU below the voice, measured. It is a fixed offset; `duck` is the moving one. | |
| rotate | No | Further assets to play in turn as each one runs out, overlapping by `crossfade`. `[]` clears them. | |
| src_in | No | Where inside the bed's own asset it starts, in seconds. | |
| clip_id | No | The clip whose words (or events) the bed addresses — the VO, not the music. | |
| fade_in | No | Seconds of fade at the bed's start. The fades ride the bed's own entry, so a fade-out ends where the music audibly ends. | |
| fade_out | No | Seconds of fade at the bed's end. A fade pair the bed cannot hold refuses at build time rather than being clamped. | |
| loudness | No | Level the whole bed to this many LUFS, measured — for a film with no voice for `under` to sit below, such as a screen recording. Setting it drops `under`, and `under` drops it. The launch clip's approved bed reads -23.3. | |
| passages | No | Replace the list of passages after the bed's own asset: each `{asset, word_index_start | phrase_start | event, src_in?, crossfade?, rotate?}`. `[]` clears them. | |
| clear_end | No | Drop the end word, returning the bed to running to the end of the edit. | |
| crossfade | No | Seconds two pieces overlap by. A crossfade edge is equal-power rather than the straight dB line an ordinary fade draws — two straight fades crossing sum to a hole. | |
| over_tail | No | True runs a bed with no end boundary on under the tail's card, so the card is not silent and `fade_out` ends with it. False ends it with the edit, the default. | |
| clear_duck | No | Return the bed to one level, with no ducking. | |
| occurrence | No | Disambiguate `phrase_start`/`phrase_end` by count, **1-based**. Unset, an ambiguous phrase is refused rather than guessed at. | |
| phrase_end | No | Set the out-point by wording instead; it binds the phrase's last word. Each boundary is independent — one can be a phrase and the other an index. | |
| clear_under | No | Return every asset to its own level. | |
| until_event | No | End the bed on this event of clip_id. Replaces an end word; `clear_end` drops it. | |
| phrase_start | No | Set the in-point by wording instead; it binds the phrase's first word. The resolved phrase is stored beside the index, so `cue_reresolve` can re-derive it after a re-record. | |
| clear_loudness | No | Drop the `loudness` level. | |
| word_index_end | No | Where the bed goes out. Unset means *to the end of the edit*, so a tail holds over silence unless `over_tail`. | |
| word_index_start | No | Where the bed comes in, as a word of `clip_id`. The bed stores words and never a length, so a cut before either boundary moves it automatically. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||