Skip to main content
Glama

Locate

media_locate
Read-only

Find 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

NameRequiredDescriptionDefault
endNoWindow 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. (终点,秒)
maxNoMaximum number of matches to return: 1-20, default 5. (最多返回几条匹配)
ocrNoDocument 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 / 重新识别文字层)
pathYesAbsolute path to a LOCAL file: video, audio recording, or document. URLs and relative paths are rejected — this server never downloads anything. (本地文件绝对路径)
pagesNoPage range for document media: comma-separated 1-based page numbers and closed ranges, e.g. "3-10,15". Not applicable to video or audio. (页码范围)
queryYesText or keyword to find. Matching ignores punctuation, spacing and case; Chinese and English both work. (要找的文本 / 关键词)
startNoWindow start in seconds (closed interval, both ends included). Applicable to video and audio only; document media uses "pages" instead. Default 0. (起点,秒)
segmentNoWindow length in seconds (30-3600, default 300), used when only "start" is given. Applicable to video and audio only.
subtitleNoChoose 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). (显式选择字幕来源:文件路径 / 字幕轨序号 / 语言码)
transcriptNo"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.
includeFrameNoAlso return one picture at the best match (default false). Applicable to video and document only. (是否附带最佳匹配处的画面)

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed5 schema fields changedv0.3.0
    • addedInput schema / properties / ocr
      Added value: +{
      +  "description": "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 / 重新识别文字层)",
      +  "enum": [
      +    "auto",
      +    "force"
      +  ],
      +  "type": "string"
      +}
    • addedInput schema / properties / subtitle
      Added value: +{
      +  "description": "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). (显式选择字幕来源:文件路径 / 字幕轨序号 / 语言码)",
      +  "type": [
      +    "string",
      +    "number"
      +  ]
      +}
    • changedInput schema / properties / transcript / description
      Previous value: -"\"auto\" (default): use subtitles first, ASR only as a fallback. \"off\": no transcription at all, visuals only. Applicable to video and audio only."New value: +"\"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."
    • changedInput schema / properties / transcript / enum
      Previous value: -[
      -  "auto",
      -  "off"
      -]New value: +[
      +  "auto",
      +  "subtitle",
      +  "off"
      +]
    • removedInput schema / properties / transcriptFile
      Removed value: -{
      -  "description": "Absolute path to a local subtitle/transcript file (.srt, .vtt, .ass, .ssa). Applicable to video and audio only. (本地字幕/转写文件)",
      -  "type": "string"
      -}
  2. First observedv0.1.0

TDQS

A4.5/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations only cover readOnly/openWorld, and the description adds substantial behavior: no vision tokens by default, includeFrame costs one image (~1,900 tokens), subtitle-over-ASR precedence, explicit subtitle selection never falls back, forced OCR is cached separately, and the sidecar is never created. The ASR caveat ('do not present it as the speaker's exact words') is unusually useful. Minor gap: no statement about how many matches are scanned versus returned beyond the max parameter.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The purpose and when-to-use are front-loaded in the first two paragraphs, which is good. However, the text is long for a search tool, and the ocr and annotation behaviors are explained twice (English prose plus a parenthetical Chinese gloss that mostly repeats it), padding a description already backed by a fully documented schema.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With 11 parameters and no output schema, the description carries the burden and does: it describes the return shape per media type (time window, match score, per-page hits and snippet, 'N more pages match'), the outline in structuredContent.outline with b1…bN ids usable in media_bookmark, and the separate annotation-matches section that is never counted as media hits. An agent can interpret the response without guessing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3; the description still adds meaning the schema does not carry, notably that long phrases match better than single characters, the rationale for ocr:'force' (use when media_probe reports an unreliable text layer), and the fallback rules for subtitle/transcript modes. Some of the ocr text simply restates the schema description, which keeps it from a 5.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific verb and resource: 'Find where something appears in a local media file and return its position', then concretizes the return for each media type (timestamp in ms/s vs page number). It is clearly distinguished from media_overview ('Read a full page with media_overview') and media_probe (referenced as the thing that flags unreliable text layers), so an agent can tell it apart from every sibling.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit when-to-use ('you know roughly what was said but not when', 'which page a phrase is on') and explicit when-not/alternatives ('Use media_overview if you only need the visuals'). It also names the precondition (a transcript must exist) and routes the agent to media_probe for the OCR-force decision, leaving little to inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.