文档大纲

Claude-real-video：让 AI 真正看懂你给的视频

一、让人抓狂的问题：Claude 真的"会看"视频吗？

不少朋友第一次把一段视频丢给 Claude 想让它总结要点时，都会遭遇同一种"社死"现场：

  • 提问："帮我看看这段 30 分钟的产品发布会，竞品有哪些新功能？"
  • 回答："抱歉，我无法直接处理视频文件，请提供文字描述或截图。"

其实这不怪 Claude —— 它在训练时根本没学过怎么"看"视频。视频对现在的 LLM 来说，就是一堆它完全无法触及的二进制字节。

要让 AI 真正"看懂"一段视频，传统做法只有两条路：

  1. 手动截屏：把关键画面一张张截图，配文字描述喂给 AI。费力、漏帧、不精准。
  2. 上传到云端转录服务：把视频发给第三方，等他们把转写+摘要吐回来。慢、贵、隐私让人不放心。

那有没有一种"程序员式"的解法：给我一条命令，让本地机器把视频处理好，直接产出 LLM 能吃的素材？

GitHub 上 1.9k Star 的开源项目 claude-real-video 就是干这事的。它的 PyPI 包名是 crv，作者是独立开发者 Leo Huang。

二、claude-real-video 到底是个啥？一句话讲明白

如果用一句话概括，它的官方描述是：

让 Claude 或任何 LLM 真正"观看"视频 —— 通过场景感知关键帧提取、去重、Whisper 转录，把视频转换为 LLM 可读格式。

翻译成人话：它是一个本地运行的"视频预处理流水线"。给一段视频（YouTube 链接、网盘里下载好的 MP4 都行），它会自动帮你做三件事：

  1. 挑出关键画面：用场景变化检测，找出"什么时候画面变了"，而不是傻乎乎地每秒截一张。
  2. 干掉重复画面：用三通道 + 滑动窗口算法，把"镜头停了一会儿"或者"画面又切回来"这类冗余帧全部丢掉。
  3. 听清对白：用 Whisper 给音频做转录，输出带时间戳的文字稿。

最后给你吐出一份 MANIFEST.txt 总览 + 一堆帧图片 + 转录文本，扔给 Claude、Cursor、Codex、Copilot 任何一个 AI，它们都能像"看完视频"一样回答你的问题。

而这一切，只在你自己的电脑上完成，视频不用上传。

三、它是怎么做到的？三个关键技术点讲明白

很多人第一眼看到"关键帧提取"会想：不就是每隔几秒截一张图吗？这有啥技术含量？

还真有。普通截屏方案有三个典型坑，而 claude-real-video 就是为解决这些坑设计的。

1. 智能选帧：场景感知 + 密度下限

想象一部电影里，主角在房间里安静讲了 5 分钟台词，然后突然切到一个赛车追逐场景。

  • 普通等距采样：会从台词部分多出几十张几乎一样的图，浪费 token。
  • claude-real-video 的做法：通过 ffmpeg 的 select 滤镜单遍扫描，只在画面真的发生"场景变化"时才截帧；同时设置一个"每秒至少一帧"的下限，避免快切镜头漏帧。

实测数据（在 Mac mini M4 上跑一段 3 分钟的 640×360 视频）：

模式抽出的帧数耗时喂给 LLM 的 token
默认170 帧23.5 秒~52k
–max-frames 8080 帧23.4 秒~25k
–adaptive（自适应）270 帧36.8 秒~83k

可以看到，帧数和 token 用量完全可控，不会一不小心把百万 token 烧光。

2. 三通道去重：算法里的"小心思"

去重听起来简单，但要让 LLM 既不漏画面、又不被重复帧刷屏，其实是门艺术。这个项目搞了三套去重通道互相补充（不同版本逐步加入）：

  • 全局像素差异：把帧降采样到 RGB 小图，对比像素差异。粗筛"是不是同一镜头"。
  • settled-local 通道（v0.7.4 加入）：盯的是画面里的"小动作" —— 字幕滚动、鼠标点击、UI 微调，全局看着差不多但细节在动的情况它能识别。
  • action 通道（v0.7.16 加入）：专门治"小主体快速动作" —— 比如演讲者手上比划、宠物挠痒痒这类。在 v0.7.16 的更新里，小主体快速动作的保留率从 1/10 提升到了 10/10。

再叠加一个"A-B-A 滑动窗口"机制：镜头从 A 切到 B 又切回 A，它不会傻乎乎地把 A 重复两遍。整套组合拳下来，最后喂给 AI 的帧既不冗余、也不漏重要信息。

3. 诚实转录：Whisper + Silero VAD 双保险

很多人吐槽用 Whisper 转录时，遇到一段纯音乐或静音，它会"幻觉"出几句根本不存在的台词 —— 这是 Whisper 出名的老毛病。

claude-real-video 的解法：

  • 配上 Silero VAD（语音活动检测），先告诉 Whisper"这段没人在说话"。
  • Whisper 在静音段不会硬编台词，而是老老实实输出"no speech"。
  • 这种诚实的转录对后续 LLM 总结尤其重要 —— AI 不会再把幻觉台词当成"视频内容"复述给你。

音频处理的可选包还有两个分支：

  • [whisper]：默认的 openai-whisper，转录 + 翻译都行。
  • [fast]：换用 faster-whisper，速度更快、内存占用更低，自带 Silero VAD。
  • [speakers]：装上 pyannote 类模型，能区分说话人（A 说/B 说），但要额外下载 45 MB 模型。

四、它适合谁？六个典型场景

聊完技术，估计你想问：这玩意儿到底能干啥？我整理了 6 个真实可用的场景：

  1. 课程笔记自动化：把 B 站/Coursera 的讲座 URL 扔给 crv，让 Claude 总结成结构化笔记，甚至追问"第 12 分钟讲的是什么公式"。
  2. 竞品视频分析：下载竞品的产品发布会视频，让 AI 自动抽取每一页 PPT 的关键信息和定价策略。
  3. 会议录像归档：录好的腾讯会议/Zoom 本地视频，跑一遍后存进知识库（通过 --kb 参数指定路径），下次想查"上次会议谁说了什么"直接问 AI。
  4. 社交媒体素材复盘：把 Instagram Reel、TikTok、YouTube Shorts 的链接丢进去，自动产出摘要。
  5. 多语言字幕校对：有 .srt/.vtt 字幕时优先用字幕，否则用 Whisper 转录，对翻译人员特别友好。
  6. AI Agent 工作流前置：配合 Claude Code、Cursor、Codex、Copilot、Gemini CLI 这 50 多个支持 skill 的 agent，让它们具备"读视频"的工具能力。

一句话总结它的目标用户：任何需要让大模型"看"视频、但又不想或不能把视频传到云端的人。

五、怎么装？五步搞定本地部署

部署并不复杂，下面是完整步骤。

步骤 1：装系统依赖 ffmpeg

这一项必须手动装，pip 帮不了你。ffmpeg 是整个流水线干活的"瑞士军刀"。

# macOS
brew install ffmpeg

# Ubuntu / Debian
sudo apt install ffmpeg

# Windows（用 winget 或 choco）
winget install Gyan.FFmpeg
# 或
choco install ffmpeg

装完用 ffmpeg -version 验证一下。

步骤 2：装 Python 包

推荐用虚拟环境，Python 3.10+ 是硬要求。

# 最常用组合：关键帧 + 去重 + Whisper 转录
pip install "claude-real-video[whisper]"

# 只要核心（帧提取 + 去重，不要音频转录）
pip install claude-real-video

# 想要更快 + 防幻觉的转录
pip install "claude-real-video[fast]"

# 想要说话人分离
pip install "claude-real-video[speakers]"

装好后命令行里会多一个 crv 命令。

步骤 3：（可选）让 Claude Code 等 Agent 集成它

这个项目设计了 Skill 安装方式，一行命令就能装到 50+ AI 编辑器：

# 通用方式（Claude Code, Cursor, Codex, Copilot, Gemini CLI 等）
npx skills add HUANGCHIHHUNGLeo/claude-real-video

# Claude Code 插件市场方式
/plugin marketplace add HUANGCHIHHUNGLeo/claude-real-video
/plugin install claude-real-video@claude-real-video

# 手动复制 skill 目录
git clone https://github.com/HUANGCHIHHUNGLeo/claude-real-video.git
mkdir -p ~/.claude/skills
cp -r claude-real-video/skills/claude-real-video ~/.claude/skills/

装完后，你可以在 Claude Code 里直接说"分析这段视频 /path/to/video.mp4″，它就自动调用 crv。

步骤 4：（可选）确认 yt-dlp 能下载你要的视频

如果是 YouTube、Instagram、TikTok 等公开视频，yt-dlp 默认就能下。如果是需要登录的视频（比如私人 YouTube 视频、会员专享内容），可以用 --cookies cookies.txt 指定 Netscape 格式的 cookie 文件，或者 --cookies-from-browser chrome 从浏览器直接读。

注意：cookies 是你自己的账号凭据，使用范围仅限你自己有权观看的视频，请遵守各平台的服务条款。

步骤 5：跑个 Hello World 验证

最简单的验证方式：随便找一个 YouTube 短视频链接跑一下：

crv "https://www.youtube.com/watch?v=xxxxx" -o out --lang en

跑完后看下 out/ 目录：

out/
├── frames/                 # 一堆 jpg 关键帧
├── frames.json             # 帧时间戳映射
├── transcript.txt          # 转录文本（纯文本）
├── transcript.json         # 转录（含时间戳，结构化）
├── MANIFEST.txt            # 给 LLM 看的总览
└── viewer.html             # --viewer 时生成的可视化页面

打开 viewer.html 是个 HTML 浏览器版的时间线 —— 滚动鼠标就能像看视频一样核对 AI 的总结是否对得上。

六、硬件要什么门槛

这个项目的硬件要求相当平易近人，作者主要在 Mac mini M4（Apple Silicon，本地 CPU） 上做基准测试。

资源最低推荐
操作系统macOS / Linux / Windows 任一macOS 或 Linux（脚本支持最好）
Python3.10+3.11+
运行内存8 GB16 GB
硬盘5 GB 可用（含 Whisper 模型）20 GB+
GPU不需要（Whisper CPU 也能跑）Apple Silicon 体验最佳

关于 Whisper 模型：默认用的是 base 模型（约 150 MB），速度快但精度一般。如果想要更高的转录精度，可以手动指定 --whisper-model turbo，但是一次性下载约 1.6 GB，运行时要约 6 GB 内存。

不打算本地转录音频、只用 Claude/Gemini 这种云端模型自带的多模态能力？只需要帧提取 + 去重功能的话，几乎不挑机器，几年前的笔记本都能跑。

七、怎么用？常用命令与 Python API 速查

7.1 常用 CLI 场景

# 1. 公开 YouTube/Ins/TikTok 链接
crv "https://www.instagram.com/reel/XXXXX/"

# 2. 本地视频文件
crv lecture.mp4 -o out --lang en

# 3. 只要帧、不要转录（节省时间和磁盘）
crv clip.mp4 --no-transcribe

# 4. 需要登录的视频（自用授权）
crv "https://..." --cookies cookies.txt

# 5. 限制最大帧数 + 网格化预览（节省 token）
crv video.mp4 --max-frames 80 --grid

# 6. 专注模式 v0.3.0+：明确告诉 AI 你想从视频里找什么
crv "https://youtu.be/..." --why "find the pricing strategy" --kb ~/notes

# 7. 启动 Web 界面
crv-web

7.2 Python API（适合嵌入自动化流水线）

from claude_real_video import process

r = process("https://youtu.be/...", "out", lang="en")

print(f"抽出了 {r.frame_count} 帧")
print(f"转录文件：{r.transcript_path}")

返回的对象上有 frame_count、transcript_path 等字段，方便你后续接 LangChain、LlamaIndex 或者自己的 RAG 流水线。

7.3 几个超实用的 flag

  • --adaptive：自适应采样，画面变化剧烈的视频用它能多抓帧。
  • --text-anchors：把字幕强制对应的画面也带上帧（适合双语字幕校对）。
  • --report：生成 report.html，一个可视化报告页。
  • --speakers：开启说话人分离（A 说 / B 说）。
  • --why "<你的目标>"：把分析目的直接告知处理流程，影响帧选择策略。
  • --dedup-threshold 8：去重阈值（百分比），调小更激进去重、调大更宽松。

第一次用建议先跑默认参数，对比 --report 生成的可视化页调整阈值。

八、番外篇：crv Pro 付费扩展

如果你用上瘾了，作者还提供了一个 crv Pro 付费扩展（通过 Capafy 或 Lemon Squeezy 购买）：

  • 限时价格：2026 年 7 月 31 日前 $19，之后恢复 $29。
  • 额外能力：
  • --motion：相机运动分析（识别静态/平移/倾斜/缩放/手持）。
  • --senses：声音情感分析（识别紧张、欢快、悲伤等）。
  • --ai-report：让两个 AI 分别写报告，做交叉验证。
  • --breakdown：镜头语言拆解报告（适合影视分析）。

免费版已经能覆盖 90% 的需求，Pro 更像是给重度视频分析用户的"专业级瑞士军刀"。

九、最后说两句：值不值得入手？

值不值得，取决于你的工作流里"AI 看视频"是不是高频动作。

如果你只是个偶尔看视频的人，截几张图 + 让 Claude 总结确实够用。但如果你：

  • 每周要批量处理十几个视频；
  • 视频里有大量不变化的演讲/会议/PPT 镜头；
  • 对上传到第三方服务的隐私有顾虑；
  • 想让 Claude Code、Cursor 这类 Agent 自动化"看视频再写代码/总结"的工作流；

—— 那 claude-real-video 几乎是现成的最佳选择。MIT 许可、纯本地、跟主流 AI 编辑器集成度高，还持续在迭代（0.7.x 系列最近还在加新通道），社区活跃度也在线（1.9k Star、154 Fork）。

给它一条视频链接，一杯咖啡的时间，你就拥有了一个"看得见画面、听得清台词、记得住时间戳"的 AI 视频秘书。

阅读量： 339

网站备案号：沪ICP备2025137870号