video-perception

视频感知

你可以通过 claude-video-vision MCP 服务使用视频理解工具。

可用工具

• video_analyze — 使用 ffmpeg 滤镜分析视频结构（场景变化、静音、运动等）。在提取帧之前使用此工具，以规划策略。
• video_watch — 从视频中提取帧并处理音频。支持为不同片段设置不同的 FPS／分辨率。
• video_detail — 深入查看特定片段。将提取与查看分开——提取多帧，每次查看少量帧。
• video_info — 获取视频元数据，无需处理视频。
• video_configure — 更改设置（后端、分辨率、enable_index 等）。
• video_setup — 检查／安装依赖项。

工作流

重要：必须按顺序执行以下步骤。不得跳过第 2 步。

1. 始终先调用 video_info，获取时长、分辨率和音频是否存在。 如果用户提供的是 YouTube URL，请将该 URL 直接作为 path 传入。 MCP 服务会使用 yt-dlp 下载视频，优先使用 YouTube 字幕／自动字幕进行转录，仅当字幕缺失、为空或明显不完整时，才会回退到已配置的音频后端。

2. 视频时长超过 30 秒时，必须： 在提取任何帧之前调用 video_analyze。 这不是可选步骤——它能提供结构数据，帮助你制定合理的提取策略。 根据用户的问题选择相关滤镜：

   用户意图	要选择的滤镜
   “视频里发生了什么？”	scene_changes、silence、transcription
   “找出场景转场”	scene_changes、black_intervals
   “有没有画面冻结／卡住的部分？”	freeze、blur
   “这是一个对着镜头讲话的人，还是动作场景？”	motion
   “音乐什么时候开始？”	silence、loudness
   “分析光线”	exposure
   “总结这场讲座”	transcription、scene_changes、silence
   意图一般／不明确	scene_changes、silence、transcription

   如果视频带有音频，始终将 transcription: true 包含在内——转录内容会告诉你应该查看哪些画面。

   scene_changes: true 会报告硬切（scdet 分数 >= 8）。如果用户需要识别较柔和的转场（叠化、缓慢淡入淡出），传入 scene_changes: { threshold: 4 }；如果手持或快速移动的镜头导致列表过长，则提高阈值（例如 { threshold: 15 }）。

3. 使用分析结果和转录内容规划帧提取策略：

   • 对于静态或可预测的片段，使用较低的 FPS（0.1-0.5）
   • 仅在场景变化、运动峰值或语音提及的时刻（“看这里”“如你所见”“让我展示一下”）附近使用较高的 FPS（1-3）
   • 不要超过完成任务所需的最低 FPS
   • 优先选择较少的片段和较低的 FPS——之后始终可以进一步深入查看

4. 调用 video_watch 提取帧：

   • 对于**短视频（< 2 分钟）：**使用 fps: "auto"，不使用 view_sample——短视频需要完整覆盖，以免漏掉短暂片段。自动 FPS 已会根据时长调整。
   • 对于**长视频（> 2 分钟）：**根据分析数据使用设置了不同 FPS 的 segments，并使用 view_sample 限制初始帧数。之后始终可以通过 video_detail 进一步深入查看。

5. 使用 video_detail 深入查看特定时刻：

   • 从关注点附近的 3-5 秒窗口开始
   • 使用 view_sample: 3 进行预览（第一帧、中间帧、最后一帧）
   • 然后，如果需要更多细节，再通过 view 请求特定时间戳
   • 仅当初次查看的信息不足时才扩大窗口
   • 将查看帧的过程视作二分搜索——逐步缩小范围，聚焦关键内容
   • 切勿一次性查看所有提取的帧

6. 用户针对同一视频提出后续问题时，请查阅上下文中已有的清单。不要以相同分辨率重新提取已有帧。不要重新请求上下文中已有的帧。

参数指南

fps： 通用概览请使用 "auto"。逐帧查看细节时，请使用视频的原始 fps（来自 video_info）。分析特定的短暂片段时，请使用 5-10。处理长视频时，请使用 0.1-0.5。

resolution： 快速浏览请使用 256-512。常规分析请使用 512-768。需要读取屏幕文字或查看细节时，请使用 1024+。

segments： 有分析数据时使用。每个片段都可以有自己的 fps 和 resolution，并覆盖全局 fps/start_time/end_time。

view_sample： 从提取的帧中返回 N 张间隔均匀的帧。使用此参数可避免过多图像占满上下文。

skip_audio： 只需要视觉分析时设为 true。

YouTube URL： 将受支持的 YouTube URL 直接作为 path 传入。将 transcription_source: "youtube_subtitles" 视为比 youtube_auto_captions 更可靠的来源；自动字幕仍可能存在识别错误。

处理结果

你会收到：

• 清单（启用 enable_index 时）——按分辨率和时间戳列出所有缓存帧的索引。使用它可避免重复请求。
• 帧（以图像形式提供）——查看这些图像，了解视觉上发生的情况
• 音频转录（带时间戳）——阅读语音内容
• 音频标签——非语音事件（音乐、声音等）
• 分析数据——场景变化、静音区间、运动程度等

结合所有来源，形成完整的理解。使用分析数据和转录来指导你查看哪些画面。分析数据会告诉你事情发生的时间，帧会告诉你发生了什么。