claude-real-video

让任意大语言模型真正"看懂"视频

你可能有过这样的经历：把一个 YouTube 视频链接丢给 ChatGPT 或 Claude，希望它帮你分析内容。结果 AI 读到的，仅仅是视频的字幕文本——画面里发生了什么，它一无所知。那些图表的细节、人物的微表情、场景的切换，全被忽略了。更有意思的是，即使是 Gemini 这样号称支持视频理解的多模态模型，背后也受限于固定间隔采样（默认 1fps），快速剪辑的镜头会悄悄溜走。

claude-real-video（简称 crv）解决了这个痛点。这个由独立开发者 HUANGCHIHHUNGLeo（GitHub ID: 24993398）创建的开源工具，能让 Claude——或任何大语言模型——真正"看"视频。它通过场景变换检测而非固定时间间隔来选取关键帧，自动去除重复画面，转录音频，最终交付一个干净的文件夹（帧图片 + 文字记录），交给任何 LLM 进行分析。整个过程在本地运行，隐私完全由你掌控。

crv 在 Hacker News 获得了 167 个 upvote，登上首页，引发了 62 条讨论。

背景故事：为什么会有这个项目？

大语言模型在自然语言处理方面已经非常强大，但在视频理解上一直存在明显短板。主流的"让 AI 看视频"方案本质上只有两条路：一是将视频上传给云端多模态模型（如 Gemini），用户必须信任服务商，且受制于固定帧采样策略；二是直接喂给 LLM 字幕文件，完全忽略视觉信息。两条路都不够优雅。

作者在 GitHub Issues 和 README 中明确指出：现有工具（包括 Gemini 自身的处理管线）采用固定间隔采样——比如每秒采一帧。这在静态内容（屏幕录制、演讲幻灯片）上浪费大量 token，在快节奏内容（运动集锦、MV）上反而漏掉了画面。该项目于 2025 年上线，当前版本 0.10.3，在 GitHub 上已获得 2000+ stars。

核心原理：场景感知 + 滑动窗口去重

crv 的工作流程分为三个阶段：

阶段一：场景检测

crv 使用 ffmpeg 的场景检测能力（基于像素差异算法），将视频切分为多个场景片段。与固定间隔采样不同，它只在场景发生实际视觉变化时才提取一帧。参数 --scene 控制灵敏度（默认 0.30，值越低越敏感），--fps-floor 确保即便画面静止也至少每隔 N 秒提取一帧，避免长静默段被完全跳过。

阶段二：滑动窗口去重

这是 crv 的核心技术亮点。对于 A-B-A 镜头（如采访节目反复切回主持人），固定采样会把同一画面重复发送给 LLM，浪费 token。crv 通过滑动窗口算法，对相邻帧进行感知哈希比对，将视觉上几乎相同的帧去重，仅保留每个镜头的第一帧。README 中的对比数据很直观：一个 58 秒的 clip，固定 1fps 采样产生 58 帧，而 crv 智能保留下 26 个真正不同的画面。

阶段三：音频转录

crv 优先使用视频自带的字幕轨道（SRT/VTT 等），若无可用字幕则调用 OpenAI Whisper 进行本地转录（需安装 pip install claude-real-video[whisper]）。转录内容与帧图片一起写入 MANIFEST.txt，LLM 可以同时看到视觉证据和文字内容。

上手体验：CLI 与 Web UI 两条路径

命令行方式（适合开发者）

pip install claude-real-video
crv "https://www.youtube.com/watch?v=..."
# 输出: crv-out/frames/*.jpg + crv-out/transcript.txt + crv-out/MANIFEST.txt

进阶用法：指定分析目的（--why "分析定价策略"）让 AI 聚焦重点；--kb ~/notes 将结果自动保存为笔记文件。

Web UI 方式（适合非技术用户）

crv-web

一条命令启动本地浏览器页面，支持简体中文、繁体中文和英文界面切换。粘贴 YouTube 链接或本地文件路径，点击 Analyze，结果在本地查看器中展示，全程无需终端操作。视频本身不会上传——所有处理在本地完成，上传的只是用户主动选择粘贴到 LLM 的帧图和文字。

Claude Code 集成

crv 可以作为 Claude Code 的 skill 安装，让 AI agent 自主处理视频分析任务。用户评价中，有人用它分析 WXM 职业摔角比赛（追踪动作、观众反应、故事线），有人用来制定视频剪辑计划。

技术架构：轻量级依赖，极简代码结构

crv 核心依赖仅两个包：yt-dlp（视频下载）和 Pillow（图片处理）。可选依赖包括 openai-whisper、faster-whisper（GPU 加速）、sherpa-onnx（说话人分离）和 mcp（Model Context Protocol）。代码结构清晰，位于 src/claude_real_video/ 下，包含 core.py（核心管线）、cli.py（命令行入口）、serve.py（Web UI）、mcp_server.py（MCP 协议服务）、memory.py（笔记集成）等模块。

源码中值得注意的设计细节：

• ffmpeg 9.0 移除了 -vsync 参数，改用 -fps_mode，crv 动态探测 ffmpeg 版本来决定使用哪个参数
• Whisper 探测使用 importlib.util.find_spec 而非真实 import，避免触发 torch 导入（数百 MB + 数秒延迟）
• Windows 控制台默认使用 cp950 等遗留编码页，无法编码 ✓/→ 等 Unicode 字符，crv 强制 reconfigure 为 UTF-8 避免崩溃

争议与局限：不完美，但方向正确

Hacker News 的讨论中，有几个值得关注的批评：

1. 关键帧≠视频：用户 october 指出，关键帧无法传达运动和物体恒常性，LLM 无法从一组静态图片中推断完整动态信息。这是对多模态 LLM 视频理解局限性的根本性批评。
2. Token 成本：用户 frb 表示，即使有了关键帧，Claude 分析大量帧图片的 token 消耗仍然不低。crv 优化了帧的质量和数量，但没有解决 LLM 端 token 计费的问题。
3. Gemini 的竞争：部分用户认为 Gemini 的原生视频理解（虽然有隐私代价）是更省事的方案。但 Gemini 也使用固定帧采样，crv 的场景检测在质量上仍有优势。
4. 依赖 ffmpeg：需要本地安装 ffmpeg，这是 macOS/Linux 用户较为熟悉的工具，但 Windows 用户有一定门槛。

行业意义：开源填补了本地多模态预处理的空白

crv 的核心价值不在于替代视频理解模型，而在于重新定义视频到 LLM 的输入管道。它解决了三个实际问题：

• 隐私：视频不上传，所有处理本地完成
• 效率：场景感知+去重显著减少发送给 LLM 的帧数
• 通用性：输出格式（帧+文本）兼容任何 LLM（Claude、GPT、Gemini、本地模型均可）

从更宏观的角度看，crv 代表了开源社区对商业 AI 视频理解工具的一种补充路径：不追求端到端多模态理解，而是专注于"让现有 LLM 能高效处理视频"的中间层工具。随着本地 LLM 和开源多模态模型的成熟，这类预处理器的重要性会持续增长。

---

本报告基于 GitHub 源码、README 文档、Hacker News 讨论及网络公开信息生成。如需体验：pip install claude-real-video，或运行 crv-web 打开浏览器界面。