sound_add
Sync one-shot sounds to specific words, events, or repeated event names in a timeline. Handle cuts, trim sources, vary gain, and preview with plan mode before writing.
Instructions
Play a one-shot sound at a word, an event, or every event of one name.
Import the sound first (import_media), or call sound_generate for a ready
UI set: eight key ticks, send, land, strike. every="key" puts a tick on
each keystroke event; pass all eight keys as assets so the run does not
repeat one sample, and a jitter_db of 2-3 to vary them. Hits land to the
millisecond, between frames, and are resolved through the timeline on
every build: a cut moves them, an every hit a cut removed is skipped,
and a single hit whose word or event is cut makes export refuse until it
is moved. The picks and jitter repeat on every build. src_in/src_out
trim what plays. The music's duck hears a sound only with ducks. The reply counts the hits and echoes the first few; plan=true
writes nothing. Export's reply lists the sounds it placed.
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 a phrase's matches: any match at or before this word index is skipped. -1, the default, means from the start. | |
| ducks | No | The music bed's duck hears this sound as it hears the voice: set it for a narrator take or a line of dialogue placed as a sound, never for clicks. Only matters when the bed has a duck. | |
| event | No | Play at this event of clip_id: `name`, or `name#k` when the name repeats. | |
| every | No | Play at every event of clip_id with this name (e.g. every keystroke). Events a cut removed are skipped and counted. | |
| assets | Yes | The imported clips to play, by clip_id. With several, each hit draws one, so a typed run does not repeat one sample. sound_generate registers a ready set (sfx-*). | |
| phrase | No | Play as this phrase's FIRST word starts, resolved against clip_id's transcript. | |
| src_in | No | Seconds into each asset where the sound starts. With src_out, plays one line of a long take, and the 30 s cap is on the trimmed part. | |
| clip_id | Yes | The clip whose words or events say where — the transcript the word index indexes, or the recording the events belong to. | |
| gain_db | No | The level in dB; 0 plays the file as it is. The generated set peaks at -3 dBFS. | |
| min_gap | No | With every: drop a hit closer than this many seconds to the last one kept. Default 0.045. | |
| src_out | No | Seconds into each asset where the sound stops. Unset plays to the file's end. | |
| jitter_db | No | Vary each hit's level by up to this many dB either way. Default 0. | |
| 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 | Play as this word starts. One of word_index, phrase, event or every. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||