video

分析给定的视频并回答用户的问题（如果没有提问，则对视频进行总结）。回答时务必引用时间戳（M:SS）。

路线 A — 可使用 video-analyzer MCP 工具（优先）

如果此会话已连接 video-analyzer MCP 服务，请直接调用其工具，不要使用 CLI：

• 一般问题或未提问 → analyze_video（detail "standard"）
• “X:XX 时发生了什么”/指定时刻 → analyze_moment（时间范围）或 get_frame_at
• 仅凭语音即可回答的问题 → get_transcript（快速，无需下载）
• 仅询问标题 / 时长 / 观看次数 / 评论 → get_metadata（无需下载）
• 动作或快速 UI 变化 → get_frame_burst

对于亚秒级动作，使用小数时间边界（例如，从 0:01.1 到 0:01.3）。 FFmpeg 连续帧提取最多返回请求数量的真实源视频帧； 当请求帧率超过源视频帧率时，不会重复帧。 如果提供了小数时间戳，请保留。浏览器回退方案使用小数定位目标， 但这些目标并非经过测量的源视频帧呈现时间戳。

密集 UI 截图（终端、仪表板、IDE、电子表格——信息通常藏在小字中）：对以上任一工具传入 maxWidth。输出帧默认限制为 800 px 宽，会将 1920×1080 的屏幕录制缩小到 800×450，使 15 px 的 UI 字体小到视觉模型无法读取。maxWidth: 0 会保留源分辨率；1568 这样的数值则是折中方案。原始尺寸的帧会消耗数倍上下文，因此只在需要仔细辨读时提高分辨率，不要用于概览。

get_frame_burst 会返回一个 JSON 文本块，其中包含 { frameCount, from, to, warnings, frames: [{ time, timingOrigin }] }，随后 按与 frames 完全相同的顺序返回图像。timingOrigin: "source-pts" 表示经测量的视频相对 FFmpeg 呈现时间；"seek-target" 表示请求的浏览器定位时间。空结果或降级结果包含 frames: []。

路线 B — 无 MCP 服务（任何带 Shell 的 Agent）

通过 Bash 运行一次性 CLI（首次运行会下载 npm 包——速度较慢不代表出错；进度会输出到 stderr）：

npx -y mcp-video-analyzer@latest analyze "<video-url-or-path>"

stdout 是单个 JSON 文档，包含 metadata、transcript（带时间戳的条目）、ocrResults（屏幕文字）、timeline、warnings 和 frames——这是一个 { time, filePath, mimeType } 数组，指向磁盘上的 JPEG 关键帧。然后：

1. 解析 stdout 中的 JSON。
2. 如果问题需要视觉信息，请读取 frames[].filePath 图像（并行读取）。
3. 根据转录内容 + OCR + 帧作答，并引用时间戳。

实用标志：--detail brief|standard|detailed（brief = 仅元数据 + 转录，不提取帧——快速且省资源的路径）、--fields metadata,transcript（仅筛选输出的 JSON；standard 详细程度下仍会计算帧）、--max-frames <1-60>、--max-width <px>（帧宽度上限，默认 800；0 保留源分辨率——适用于内容为小字且载荷较小的密集 UI 截图）、--language <code>（强制指定转录语言）、--out <dir>（帧复制到的目录）、--force-refresh。运行 npx -y mcp-video-analyzer@latest analyze --help 查看完整列表。

前置条件与降级处理

• Node.js 22.12+（必需）。已捆绑 ffmpeg，无需安装。
• 平台 URL（YouTube、Instagram、TikTok 等）需要将 yt-dlp 添加到 PATH；直接使用 .mp4/.webm/.mov URL 和本地文件则无需此工具。Loom 转录文本、元数据和评论也无需 yt-dlp。Loom 帧通常需要它——Loom 会将大多数视频作为单独的 DASH 视频流和音频流提供，只有 yt-dlp 能获取并合并这些流；对于部分视频，没有它时 CDN 回退方案也能处理。
• 工具不会因部分结果而失败：warnings 数组会提供可操作的提示（安装 yt-dlp、为 Instagram/年龄限制内容设置 YTDLP_COOKIES_FROM_BROWSER、缺少 Whisper 后端）。请将相关警告转告用户，而不要将其视为错误。
• 如果转录文本为空，同时出现“音频静音”警告，说明视频确实没有语音（静音的 Reels/Stories 很常见）——这是内容本身，并非失败。
• 仅接受指向公共地址的 http(s) URL。指向 localhost、私有/LAN 网段、.local 名称、UNC 共享路径或非 HTTP 方案的 URL 会被提前拒绝，并附带说明；这是有意拒绝，并非暂时性错误，因此请勿重试或尝试绕过限制。如果用户确实需要从自己的网络获取视频，请告知他们使用 MCP_ALLOW_PRIVATE_URLS=1 重启服务。即使如此，云元数据端点仍会被阻止。