让 Claude——或任何大语言模型——真正观看一段视频。

大多数 AI 工具并不能真正“看”视频。把 YouTube 链接粘贴到 ChatGPT 里，它读取的是文字转录稿，而不是画面。Claude 根本不接受视频文件。即便是原生支持读取视频的 Gemini，也必须把视频上传到 Google，并以固定间隔（默认每秒 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.)

---

工作原理

1. 获取——使用 yt-dlp 获取 URL（可选 cookie），或复制本地文件。
2. 提取——通过一次按时间顺序的 ffmpeg 选择通道，捕获每次场景切换，并满足密度下限（每 --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` 选项用于您个人的授权访问——切勿在代码仓库中提交凭证信息。
• 重新运行会覆盖输出目录。

许可证

关于

让 Claude（或任何大语言模型）真正“观看”视频——从 URL 或本地文件获取场景感知、去重后的帧画面与文字转录。本地运行，采用 MIT 许可证。