locate
Map source words, phrases, or timestamps to their positions in the edited render, listing surviving placements and flagging material cut out or beyond the recording.
Instructions
Where does a SOURCE word or SOURCE time play in the current render?
cut_by_time's read-only mirror, and the tool to reach for before quoting any timestamp to a human: word indices and transcript times address the original recording, so they are NOT render times and every accumulated cut moves them further apart.
Two clocks, and this reports the Edit's. timeline_start/
timeline_end are 0 = the Edit's own first frame, unchanged whether or
not a head (a cold open) is configured. head_seconds rides along
(0.0 with none) so a caller that needs the actual render time — this
tool's own stated purpose — can add it: render time = Edit time +
head_seconds.
Address it one way per call — first/last are inclusive word indices
(last defaults to first), source_start/source_end are seconds into
the recording (omit source_end to locate an instant), or phrase — a
phrase naturally is a range, so it resolves straight to first/last
with no edge to pick (after/occurrence disambiguate a phrase matching
more than once), or event — a named instant from events.
Read present first. False means the material is not in the render, and
beyond_source distinguishes "you cut it" from "the recording never went
that far". A partially-cut range is normal: placements lists each
surviving piece in playback order with the source coordinates saying which
part of the phrase it is, covered how much survives, and contiguous
whether the survivors still play back-to-back. Word mode (and phrase
mode, which resolves into it) echoes the resolved words plus three either
side; time mode echoes the words the interval overlaps, or its nearest
neighbours if it landed in silence. Read-only: nothing is written.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| last | No | Last word index, inclusive. Defaults to `first`. | |
| 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. | |
| 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. | |
| event | No | Locate a named instant from `events`, as `name` or `name#k` (k counts that name's events from 0). Echoed with its neighbours. | |
| first | No | First word index, inclusive. Address it one way per call: `first`/`last`, `source_start`/`source_end`, or `phrase`. | |
| phrase | No | Locate by wording. A phrase is naturally a range, so it resolves straight to first and last with no edge to pick. | |
| clip_id | Yes | The transcript, or the recording, the address belongs to. | |
| 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. | |
| source_end | No | End of the source interval, in the recording's own seconds. | |
| source_start | No | Seconds into the original recording. Omit `source_end` to locate an instant. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||