Locate
media_locateFind where a word or phrase appears in local videos, audio recordings, or documents. Get matching timestamps or page numbers with context to jump to the right spot.
Instructions
Find where something appears in a local media file and return its position: a timestamp (milliseconds and seconds) for a video or recording, a page number for a document. (定位:给一段文本或关键词,返回它在视频 / 录音里的时间戳,在文档里的页码。)
Use it when you know roughly what was said but not when ("where does it mention X"), or when you need to know which page a phrase is on. Matching ignores punctuation, spacing and case, and works for both Chinese and English. Long phrases match better than single characters.
For a video or recording, each match is a time window with a match score (0..1) and the matched line. For a document, each match is a page: the page number, how many times the query appears on that page (hits), and a short snippet around the first hit — never the whole page. Pages that matched but did not fit are listed as "N more pages match: ...". Read a full page with media_overview({ path, pages }).
For DOCUMENTS, ocr: "auto" (default) searches the PDF text layer where one exists and OCRs only pages without one; ocr: "force" re-recognizes every requested page with the OCR provider first, even pages that already have a text layer, and tags those matches (ocr). Use force when media_probe says "text layer: looks unreliable". Forced results are cached separately from auto. (文档:ocr: "force" = 强制重新 OCR / 重新识别文字层)
Text only by default — no image, no pixels spent. Add includeFrame: true to also get the picture at the best match (one image, roughly 1,900 vision tokens).
A transcript is required: the embedded subtitle track, a subtitle you select explicitly, or ASR configured via MMGREP_ASR_PROVIDER. Subtitles win over ASR. If none is available this tool says so instead of guessing. Use media_overview if you only need the visuals.
Each match is tagged with its source. A match whose source is "asr" came from machine transcription, so the wording may be wrong (names, numbers, jargon) — do not present it as the speaker's exact words.
The result also carries the same single outline as media_probe / media_overview in structuredContent.outline: the bookmark sidecar first, then the file's own PDF bookmarks or chapter markers. Its entries carry the ids media_bookmark accepts (b1…bN), and structuredContent.outline.sidecarPath / sidecarError point at the bookmark sidecar when one exists. Locate is read-only: it never creates or modifies a sidecar. (定位结果也带同一份目录:sidecar 优先,其次文件自带目录;line 首 b1…bN 可用于 media_bookmark)
It also searches the ANNOTATION text: the notes written next to the media (annotation sidecar ".mmgrep.annotation.json", or the file's own PDF annotations) are searched too, and annotation hits are reported in their own "annotation matches" section. They are marked as annotations (kind "annotation" plus the id, n1, n2, …) and are NEVER counted as media content hits — the match count above them counts transcript / page matches only. An annotation hit is a note somebody wrote; it is not something the media says. (定位也搜批注文本;批注命中单独成段,不计入媒体命中数)
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"path": "<path>",
"query": "<query>"
},
"name": "media_locate"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| end | No | Window end in seconds (closed interval, both ends included). Applicable to video and audio only. Defaults to the end of the media; a value past the end is clipped and reported. (终点,秒) | |
| max | No | Maximum number of matches to return: 1-20, default 5. (最多返回几条匹配) | |
| ocr | No | Document media only: how to obtain page text. "auto" (default) uses the PDF text layer where one exists and OCR only for pages without one. "force" re-recognizes every requested page with the OCR provider even if it already has a text layer, and tags those pages (ocr); use it when media_probe says "text layer: looks unreliable" or the extracted text is garbled. Forced results are cached separately from "auto". Requires a configured OCR provider; not applicable to video or audio. (文档:ocr auto 默认;force = 强制重新 OCR / 重新识别文字层) | |
| path | Yes | Absolute path to a LOCAL file: video, audio recording, or document. URLs and relative paths are rejected — this server never downloads anything. (本地文件绝对路径) | |
| pages | No | Page range for document media: comma-separated 1-based page numbers and closed ranges, e.g. "3-10,15". Not applicable to video or audio. (页码范围) | |
| query | Yes | Text or keyword to find. Matching ignores punctuation, spacing and case; Chinese and English both work. (要找的文本 / 关键词) | |
| start | No | Window start in seconds (closed interval, both ends included). Applicable to video and audio only; document media uses "pages" instead. Default 0. (起点,秒) | |
| segment | No | Window length in seconds (30-3600, default 300), used when only "start" is given. Applicable to video and audio only. | |
| subtitle | No | Choose the subtitle source explicitly (video and audio only, one parameter for all forms). An absolute path to a local subtitle file (.srt, .vtt, .ass, .ssa); a non-negative integer = the ffprobe stream index of a text subtitle track; any other string = a language code matched against track tags.language (case-insensitive; "zh" also matches "chi"/"zho", "en" matches "eng"). An explicit choice never falls back: if it cannot be used, media_probe only reports the reason and the other tools fail with INVALID_ARGUMENT. Omit it for the automatic order (embedded text track, then a sibling subtitle file, then ASR). (显式选择字幕来源:文件路径 / 字幕轨序号 / 语言码) | |
| transcript | No | "auto" (default): use subtitles first (explicit subtitle selection, embedded track, sibling file), ASR only as a fallback. "subtitle": read subtitles only and never call ASR; if there is no subtitle source the result is empty and says why. "off": no transcription at all, neither subtitles nor ASR; visuals only. Applicable to video and audio only. | |
| includeFrame | No | Also return one picture at the best match (default false). Applicable to video and document only. (是否附带最佳匹配处的画面) |