HUANGCHIHHUNGLeo/claude-real-video

来源：https://github.com/HUANGCHIHHUNGLeo/claude-real-video

claude-real-video

让 Claude —— 或任何 LLM —— 真正看视频。

大多数 AI 工具并不能真正“看“视频。把 YouTube 链接粘贴到 ChatGPT，它读取的是文字稿，而不是画面。Claude 根本就不接受视频文件。即使是原生支持视频输入的 Gemini，也需要把视频上传到谷歌服务器，并且默认按固定间隔（1 fps）采样帧，因此快速的画面切换很容易被漏掉。

claude-real-video 采用了不同的方式，而且完全本地运行：指定一个 URL 或本地文件，它会提取真正有意义的帧（根据场景变化，而不是固定配额），丢弃近乎重复的帧，转录音频，然后为你生成一个任何 LLM 都能读取的干净文件夹 —— 全程在你自己机器上完成，不上传任何内容。

``bash crv “https://www.youtube.com/watch?v=…”

→ crv-out/frames/*.jpg + crv-out/transcript.txt + crv-out/MANIFEST.txt

``

然后把这些帧和 MANIFEST.txt 丢给 Claude / ChatGPT / Gemini，就可以随意提问了。

为什么不直接采样帧？

大多数“让 LLM 看视频“的脚本（以及 Gemini 自身的处理流程）都是按固定间隔抓取帧 —— 例如每秒一帧。这样对静态屏幕录制会过度采样，而对快速剪辑则采样不足。claude-real-video 更智能：

你喂给模型的是更少、更有意义的帧 —— 上下文更省，理解更准。

安装

bash pip install claude-real-video # 核心（帧提取+去重） pip install "claude-real-video[whisper]" # + 音频转录

系统依赖：ffmpeg

ffmpeg / ffprobe 用于帧提取和音频处理，不能通过 pip 安装。请安装一次：

验证是否已加入 PATH：

bash ffmpeg -version

转录功能使用 whisper 命令行工具（由 [whisper] 附加依赖安装，或通过 pip install openai-whisper）。Whisper 也依赖 ffmpeg。

支持 macOS、Windows 和 Linux —— 需要 Python 3.10+。

用法

``bash

YouTube / Instagram / TikTok / … 链接

crv “https://www.instagram.com/reel/XXXX/”

本地文件，英文转录，输出到 ./out

crv lecture.mp4 -o out –lang en

仅提取帧，不转录

crv clip.mp4 –no-transcribe

需要登录才能观看的视频（你自己的/经授权的内容）：传入 Netscape cookie 文件

crv “https://…” –cookies cookies.txt ``

python -m claude_real_video ... 也可作为 crv 的别名使用。

选项

从 Python 中使用

``python from claude_real_video import process

r = process(“https://youtu.be/…”, “out”, lang=“en”) print(r.frame_count, r.transcript_path) ``

工作原理

1. 获取 —— 对 URL 使用 yt-dlp（支持可选 cookie），或直接复制本地文件。
2. 提取 —— 一次按时间顺序的 ffmpeg select 传递，抓取每个场景变化，同时保证最低帧密度（至少每 --fps-floor 秒一帧），这样快速剪辑和慢速屏幕录制都能覆盖。
3. 去重 —— 使用真实的像素差异（降低分辨率的 RGB 直方图，而非感知哈希 —— 哈希在平坦颜色和等亮度色相变化时会失效），与最近保留的 --dedup-window 帧进行滑动窗口比较，这样 A-B-A 切镜头后不会重新发送模型已经见过的镜头。使用 --report 会生成 report.html，显示每个保留/丢弃的决定及其差异百分比，便于调参。
4. 文本 —— 如果视频已有字幕（本地文件旁边的 .srt / .vtt 文件，或内置字幕轨道），则直接使用这些字幕作为转录 —— 比重新转录更快更准。只有在找不到字幕时，才回退到对音频使用 Whisper（如果没有音频，则干净地跳过）。
5. 音频 (可选，--keep-audio) —— 保存完整的原始音轨（audio.m4a：音乐+语音+音效，尽可能无损复制）。转录只保留了文字；音频文件则让能听音的模型（Gemini、GPT-4o……）实际听到音乐和语气。
6. 清单 —— MANIFEST.txt 总结所有内容供模型使用。

因此，模型可以看（关键帧）、读（转录）以及（使用 --keep-audio）听（完整音轨）视频。转录是纯文本，任何模型都能读取；此工具不会把字幕烧录到视频中 —— 烧录是呈现方式的选择，不是让视频可被 AI 读取的必要条件。

注意事项

• 只下载你有权访问的内容。--cookies 选项仅供你自己或经授权的访问使用 —— 不要把凭据放在仓库里。
• 重新运行会覆盖输出目录。

许可证

MIT