claude-real-video
让 Claude —— 或者任意大语言模型 —— 真正看一段视频。
大部分 AI 工具并不能真正“看”视频。你把一个 YouTube 链接粘贴到 ChatGPT 里，它读的是字幕文本，而不是画面。Claude 根本不接受视频文件。即使是原生的 Gemini，能直接读取视频，也得把视频上传到谷歌，并以固定间隔（默认每秒 1 帧）采样帧，因此快速切换的镜头就会漏掉。
claude-real-video 的做法不同，而且是本地运行的：指向一个 URL 或文件，它会提取真正有意义的帧（每次场景切换，而不是固定数量），丢弃近乎重复的帧，转录音频，然后在你自己的电脑上整理出一个干净的文件夹，任何大语言模型都能读取——数据不上传。
crv "https://www.youtube.com/watch?v=..." # → crv-out/frames/*.jpg + crv-out/transcript.txt + crv-out/MANIFEST.txt
接着把帧加上 `MANIFEST.txt` 拖入 Claude / ChatGPT / Gemini，然后随便提问。
为什么不直接按固定间隔采样帧？
大多数“让大语言模型看视频”的脚本（以及 Gemini 自身的流程）都是按固定间隔抓取帧——比如每秒一帧。这样对静态屏幕录制会过度采样，而对快速切换的剪辑则采样不足。claude-real-video 更聪明：
| 固定间隔采样 | claude-real-video | |
|---|---|---|
| 帧选择 | 每 N 秒一帧 | 场景变化检测 + 密度下限 |
| 重复镜头（A-B-A 剪切） | 每次都重复发送 | 滑动窗口去重，每个镜头只发送一次 |
| 静态幻灯片（10 分钟） | 约 600 张近乎相同的帧 | 压缩为 1 帧（去重） |
| 快速切换剪辑 | 会漏掉采样间隔之间的帧 | 捕捉每一次视觉变化 |
| 音频 | 通常被忽略 | Whisper 转录，含语言检测 |
| 视频去向 | 通常上传到云端 | 留在你的机器上 |
| 输入方式 | 通常仅支持本地文件 | 支持 URL（yt-dlp）或本地文件 |
你喂给模型的帧更少，但更有意义——上下文成本更低，理解效果更好。
安装
pip install claude-real-video # core (frames + dedup) pip install "claude-real-video[whisper]" # + audio transcription
系统要求：ffmpeg
ffmpeg / ffprobe 用于帧提取和音频处理，不能通过 pip 安装。请先安装一次：
| 操作系统 | 命令 |
|---|---|
| macOS | brew install ffmpeg |
| Linux | sudo apt install ffmpeg（或使用你的发行版包管理器） |
| Windows | winget install Gyan.FFmpeg — 或 choco install ffmpeg — 或下载一个构建版本，将其 bin\ 文件夹加入 PATH |
确认它已在 PATH 中：
ffmpeg -version
转录使用 whisper CLI（通过 [whisper] 额外选项安装，或 pip install openai-whisper）。Whisper 也依赖 ffmpeg。
支持 macOS、Windows 和 Linux——Python 3.10 以上。
使用方法
# A YouTube / Instagram / TikTok / ... link crv "https://www.instagram.com/reel/XXXX/" # A local file, English transcript, output to ./out crv lecture.mp4 -o out --lang en # Frames only, no transcription crv clip.mp4 --no-transcribe # A login-gated video (your own / authorised use): pass a Netscape cookie file crv "https://..." --cookies cookies.txt
python -m claude_real_video ... 也可以简写为 crv。
选项
| 标志 | 默认值 | 含义 |
|---|---|---|
| -o, --out | crv-out | 输出目录 |
| --scene | 0.30 | 场景切换敏感度（值越低，提取的帧数越多） |
| --fps-floor | 1.0 | 每 N 秒至少提取一帧 |
| --max-frames | 150 | 总帧数的硬上限 |
| --lang | auto | Whisper 语言（en, zh, auto, ...） |
| --dedup-threshold | 8 | 像素变化比例，超过该比例才视为新帧；值越高，帧数越少 |
| --dedup-window | 4 | 与最近保留的 N 帧进行比较——模型已看过的镜头不会在切回后再次出现（1 表示仅与前一帧比较） |
| --report | off | 将丢弃的帧保存在 ./dropped 中，并写入 report.html，可视化展示每一帧的保留/丢弃决策 |
| --no-transcribe | off | 跳过音频转录 |
| --keep-audio | off | 同时保存完整音轨（audio.m4a），以便音频模型可以收听 |
| --cookies | – | 用于登录受限源的 Netscape cookie 文件 |
通过 Python 使用
from claude_real_video import process r = process("https://youtu.be/...", "out", lang="en") print(r.frame_count, r.transcript_path)
工作原理
- 获取（Fetch）——使用 yt-dlp 处理 URL（可选 cookie），或直接复制本地文件。
- 提取（Extract）——通过一次时序 ffmpeg 选择通道，捕获每个场景切换点，并确保密度下限（每 --fps-floor 秒至少一帧），从而同时覆盖快速剪辑和慢速录屏。
- 去重（Dedup）——基于真实像素差异（降采样 RGB，而非感知哈希——哈希在纯色和等亮度色相变化时会失效），与最近 --dedup-window 个保留帧构成的滑动窗口进行比较，从而避免 A-B-A 切回镜头向模型重复发送已看过的画面。启用 --report 会生成 report.html，展示每个保留/丢弃决策及其差异百分比，便于调参。
- 文本（Text）——如果视频已有字幕（本地文件旁挂载的 .srt/.vtt，或内嵌字幕轨道），则直接使用这些字幕作为转录文本——比重新转录更快、更准确。仅在没有字幕时才回退到对音频使用 Whisper（若无声轨则干净跳过）。
- 音频（可选，--keep-audio）——保存完整原始音轨（audio.m4a：音乐+语音+音效，尽可能无损复制）。转录仅包含文字部分；音频文件则允许支持听力的模型（如 Gemini、GPT-4o 等）实际听到音乐和语调。
- 清单文件（Manifest）——MANIFEST.txt 汇总所有信息，供模型使用。
因此，模型能够看到（关键帧）、读取（文字记录），并且——使用 --keep-audio 参数——听到（完整音轨）视频内容。文字记录是任何模型都能读取的纯文本；该工具不会将字幕烧录到视频中——烧录是一种呈现选择，并非让视频可被 AI 读取的必要条件。
备注
- 仅下载你有权访问的内容。--cookies 选项用于你自己的授权访问——切勿在仓库中提交凭证。
- 重新运行会覆盖输出目录。
许可证
MIT