claude-real-video

claude-real-video

▶ 100 秒演示： ChatGPT 和 Gemini 能看视频，Claude 不能。crv 将视频转换为帧和带时间戳的转录文本后，看看 Claude 会怎么回答。

▶ 60 秒像素短片 — 请打开声音（GitHub 上的 mp4） · 一个 AI Agent 搜索“如何让大模型真正理解视频？”，找到一把钥匙，并解锁视觉能力。

60 秒真实演示 — 真实安装、真实运行、真实查看器。

让 Claude — 或任何大模型 — 真正看视频。

pip install "claude-real-video[whisper]"
npx skills add HUANGCHIHHUNGLeo/claude-real-video   # one command, installs the skill into Claude Code, Cursor, Codex, Copilot, Gemini CLI & 50+ agent hosts

Claude Code 插件市场（如果想启用自动更新，请在 /plugin → Marketplaces 中开启）：

/plugin marketplace add HUANGCHIHHUNGLeo/claude-real-video
/plugin install claude-real-video@claude-real-video

然后将视频链接粘贴到你的 Agent 中并询问相关问题。（只使用 CLI？只需通过 pip 安装，即可使用 crv "<url>"。）

命名说明： crv 是 claude-real-video（PyPI 包）的简称。付费附加产品 crv Pro 在 Capafy 上以“llm-real-video Pro”的名称销售。

▶ 新短片：40 秒短片 — 我的 AI Agent 学会了看视频（然后停止工作）

同一段 58 秒视频：固定以 1 fps 采样 = 58 帧。crv 保留了其中真正不同的 26 帧 — 而 --grid 会将它们整理成 3 张缩略图拼接表。Token 更少，一帧不漏。

这个免费版本能让你的 AI 看到 视频。 crv Pro 则能让它 理解 视频 — 包括视频的拍摄方式（剪辑节奏、镜头移动），以及一份带时间戳的时间线，记录画面帧无法呈现的内容：手势、表情、语调变化、情绪和声音事件。一次性价格 $29 — 在 Capafy 上获取，或使用银行卡通过 Lemon Squeezy 购买。

使用 Codex CLI？ ▶ 36 秒演示 · Real Video for Codex 是专为 Codex 打造的独立版本。你向 Codex 提问视频相关问题，它会运行一条命令，然后读取包含章节、带时间码的转录文本以及屏幕上显示的文字的 SUMMARY.md；免费版不包含这些内容。因此，它不仅能复述演讲者说了什么，还能引用 12:40 时幻灯片上的配置块，并以 hh:mm:ss 格式回答。下载、抽帧、转录和文字识别都在你的机器上运行，而且该工具本身无需 API 密钥或账号。附带 Codex skill 和 crv-easy doctor 自检功能。支持 Python 3.10 至 3.14，可在 macOS 或 Windows 11 上原生运行。一次性价格 $9.90：在 Capafy 上获取，或使用银行卡通过 Lemon Squeezy 购买。 大多数 AI 工具其实并不会真正“看到”视频。把 YouTube 链接粘贴到 ChatGPT 中，它读取的是文字稿，而不是画面。Claude 根本不接受视频文件。即使是能原生读取视频的 Gemini，也必须把视频发送到 Google，并按固定间隔抽取帧（默认每秒 1 帧），因此会错过快速剪辑。

claude-real-video 的做法不同，而且处理过程在本地运行：给它一个 URL 或文件，它就会提取真正重要的帧（每次场景切换时，而不是按固定配额），丢弃近似重复的帧，转录音频，并为你整理出一个任何大模型都能读取的文件夹。所有处理都在你自己的设备上完成——只有你之后选择粘贴到大模型中的帧和文字才会被发送出去。

crv "https://www.youtube.com/watch?v=..."
# → crv-out/frames/*.jpg  +  frames.json (per-frame timestamps)  +  transcript.txt/.json  +  MANIFEST.txt

然后把帧和 MANIFEST.txt 放进 Claude / ChatGPT / Gemini，随意提问。

无需终端——运行 crv-web，本地页面便会打开（支持繁体中文 / 简体中文 / 英语）：粘贴 YouTube 或 Reels 链接，或文件路径，点击 Analyze，然后打开结果查看器。视频分析和结果生成都在你的设备上运行——源视频绝不会被上传。（如果你随后将提取的帧或文字稿粘贴到云端大模型中，这些数据就会发送给相应的服务商。）

想先看看模型会看到什么？添加 --viewer——它会生成一个本地 viewer.html（视频 + 关键帧网格 + 文字稿），你可以双击打开。无需联网，也无需额外安装。

视频中只有一部分内容重要（例如 90 分钟通话中的 10 分钟屏幕共享）：使用 --from 28:00 --to 43:00。ffmpeg 会直接跳转，而不是解码整个文件；Whisper 只会处理指定时间段内的音频，帧预算也只会用在这段时间内——但 crv 报告的每个时间戳仍是源视频时间码，可以直接引用给同事。

含义藏在小字里（例如终端、电子表格、IDE）：使用 --frame-width 1600。帧的选择才是难点，crv 已经能处理好；在 1920 像素宽的屏幕录制中，如果帧宽只有 640 像素，就算找到了正确时刻，也会丢掉让这一帧值得找出来的细节。

变化缓慢的内容（动画教程、渐变形变、缓慢摇摄）：添加 --adaptive——帧会根据其滚动邻域进行选择，而不是采用固定阈值，因此即使持续 2-3 秒的挤压和拉伸从未让任何单帧的变化达到峰值，也仍会被捕获。

文本密集型内容（讲座幻灯片、屏幕录制、对镜讲解）：添加 --text-anchors——会在字幕提示时间戳处强制额外提取帧，因此每段口述内容都会有对应的画面，即使场景几乎没有变化也不例外。需要旁置的 .srt / .vtt 文件或内嵌字幕轨道——烧录在像素中的字幕无法检测。每秒最多强制提取一帧；场景检测不受影响。

多说话人内容（访谈、播客、会议）：添加 --speakers——每行转录内容都会标注说话人（[SPEAKER_00]、[SPEAKER_01]，……），让模型能够追踪是谁说了什么。此功能会运行一个本地说话人分离模型（45 MB，只需下载一次，无需账号或令牌）。使用 pip install "claude-real-video[speakers]" 安装。

不需要进行大模型处理？它也可以作为通用视频关键帧提取器使用—— 检测场景变化并去重，无需下载机器学习模型。

使用 Claude Code——或任何编码 Agent？ 只需一条命令即可安装技能 （适用于 Claude Code、Cursor、Codex、Copilot、Gemini CLI 和其他兼容 agentskills.io 的宿主）：

pip install "claude-real-video[whisper]"
npx skills add HUANGCHIHHUNGLeo/claude-real-video

然后只需把视频链接粘贴到你的 Agent 中并提问。

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/

告诉它你为什么要看这个视频，并保留它找到的内容：

crv "https://youtu.be/..." --why "find the pricing strategy" --kb ~/notes

--why 会让分析聚焦于你关心的内容，而不是生成通用摘要； --kb 会将结果保存为你自己的笔记文件夹中的一条带日期笔记，避免结果只留在 crv-out 中。

0.10.x 新增——只分析重要的部分：

crv long-meeting.mp4 --from 28:00 --to 43:00

--from / --to 可从长视频中截取一段：ffmpeg 会直接跳转，而不是解码整个文件；转录文本和帧数预算会按截取范围调整，报告的所有时间戳仍是源视频的时间码，可用于引用原视频。

实测数据

在 3 分钟、分辨率为 640x360 的视频（benchmark/jfk-rice.mp4）上实测：Mac mini M4，本地 CPU，仅处理帧并去重（--no-transcribe）。图像 token 数使用 Anthropic 的公式 (width x height) / 750 估算——640x360 每帧 307 个 token。

去重 v0.7.16——小主体的快速动作不再消失。 百分比比较器在结构上无法识别占画面 <1% 的主体（它永远无法改变 8% 的像素）。这一问题在用户批量处理 2,181 个视频时被发现，现已通过增加第三个“动作通道”修复。合成复现测试——静态的 1280x720 镜头中，一个 40x90 px 的主体（占画面 0.4%）仅在 65 帧中的最后 10 帧快速移动：

为什么不直接采样帧？

大多数“让大模型观看视频”的脚本（以及 Gemini 自己的处理流程）都会按固定间隔抓取帧，例如每秒一帧。这会对静态录屏过度采样，却对快速切换的短视频采样不足。claude-real-video 更智能：

你向模型提供更少但更有意义的帧——上下文成本更低，理解效果更好。

安装

pip install "claude-real-video[whisper]"   # recommended: frames + dedup + audio transcription
pip install claude-real-video              # core only (frames + dedup)

pip extras 不会自动安装——如果没有 [whisper]，就无法进行语音转文本 （自带字幕的视频仍会生成转录文本）。

系统要求：ffmpeg

ffmpeg / ffprobe 用于提取帧和处理音频，无法通过 pip 安装。安装一次即可：

确认它已位于 PATH 中：

ffmpeg -version

转录使用 whisper CLI（由 [whisper] 扩展安装，或通过 pip install openai-whisper 安装）。Whisper 也依赖 ffmpeg。

**更快且杜绝幻觉的转录（推荐）：**安装 [fast] 扩展后，crv 会自动切换到 faster-whisper — 使用相同模型、生成相同输出文件，速度快数倍，并由 Silero VAD（语音活动检测）把关：只有音乐或静音的音频会如实标注为“无语音”，而不是生成 whisper 经典的虚构字幕。无需学习新标志：

pip install 'claude-real-video[fast]'

如果两者都已安装，优先使用 faster-whisper；如果它发生故障，crv 会自行回退到 whisper CLI。

**Apple Silicon（M1–M4）：GPU 转录。**安装 [mlx] 扩展后，crv 会通过 mlx-whisper 在 Mac 的 GPU 上运行 Whisper — 一场需要 faster-whisper 耗时约 6 分钟的 21 分钟演讲，在 M4 上约 1 分钟即可完成，转录内容相同。Silero VAD 仍会先行把关，因此音乐或静音绝不会变成虚构字幕；如果把关或 mlx 无法运行，crv 会回退到 faster-whisper，然后再回退到 CLI。由 @blazejp83 贡献（#28）。

pip install 'claude-real-video[mlx]'

支持 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 的别名使用。

选项

--grid 输出示例

一张联系表包含按顺序排列的九个连续关键帧，每个单元格都标有文件名——模型读取的是序列，而不是零散的静帧：

记忆 — 跨所有看过的视频提问

每次分析都会在本地建立索引（包含带时间戳的转录文本行和屏幕文字）， 因此提问可以覆盖整个媒体库，而不只是某个输出文件夹：

crv-ask "pricing strategy"   # → which video, which second, the exact line
crv-ask 定價                  # CJK works — trigram FTS with a substring fallback
crv-ask --list               # everything you've watched, newest first
crv-ask --stats              # where the index lives, how big it is
crv-ask --prune 200          # keep the newest 200 videos, reclaim the space

使用相同选项重新处理同一来源时，不会重复处理——crv 会提示 “已看过”，并指向现有分析（实测耗时为 0.04 秒，而不是几秒）。 使用不同选项或 --overwrite，则会照常重新分析。

所有数据都保留在本地：一个位于 ~/.crv/memory.db 的 SQLite 文件（可通过 CRV_MEMORY_DB 覆盖），仅用户可访问的权限，不使用嵌入，也不连接网络。 首次为任何内容建立索引时，crv 会打印一行提示。完全不想使用？ 设置 CRV_NO_MEMORY=1。

MCP 服务（Claude Desktop / Cursor / 任意 MCP 客户端）

crv 也以 MCP 服务的形式提供，因此 MCP 客户端可以直接要求观看视频—— 使用相同的本地处理流程，完全不依赖云端。提供五种工具：watch_video、 get_frames、search_memory（跨所有看过的视频提问）、list_watched （重新观看前检查），以及 get_transcript（仅文字，不含画面，因此 观看长篇演讲不会消耗图像令牌）。

pip install 'claude-real-video[mcp]'

Claude Code：

claude mcp add crv -- crv-mcp

Claude Desktop — 添加到 claude_desktop_config.json：

{ "mcpServers": { "crv": { "command": "crv-mcp" } } }

工具：watch_video(source, max_frames, language, transcribe) 会返回带时间戳的 转录文本，以及首批关键帧图像；get_frames(source, start_index, count) 可 分页获取其余内容。分析结果会缓存到 ~/.cache/crv-mcp，因此针对同一视频的 后续提问可即时完成。

mcp-name: io.github.HUANGCHIHHUNGLeo/claude-real-video

已在 Claude Code 上完成端到端验证（模型通过该工具正确描述了测试视频的 画面）。Claude Desktop 和 Cursor 使用相同的 MCP stdio 协议——配置见上文； 如果出现问题，请提交 issue。

在 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（可选使用 cookies），或复制本地文件。
2. 提取 — 使用一次按时间顺序执行的 ffmpeg select 遍历，抓取每个场景变化点， 并且设置密度下限（至少每隔 --fps-floor 秒提取一帧），确保既能覆盖快速切换，也能覆盖缓慢的屏幕录制。
3. 去重 — 使用三个通道，对最近保留的 --dedup-window 帧构成的滑动窗口进行检查，避免 A-B-A 插入镜头再次发送模型已经看过的画面。一个全局通道用于测量真实像素差异（缩小后的 RGB，而非感知哈希——平坦色彩和亮度相同的色相变化会让哈希失效）；--dedup-threshold 表示必须达到的变化百分比。一个局部静止通道（v0.7.4）可以捕捉全局通道看不到的变化：细小的笔画、字幕／文字卡片切换，以及平均后全局变化接近 0% 的小幅 UI 更新。它会使用更精细的特征签名，查找与所有最近保留帧都存在显著差异的区域（允许 1px 位移，因此胶片颗粒和画面抖动不会触发），并且该区域已不再变化——即进入新的静止状态，而非运动中的画面；同时还设有冷却时间，避免每秒都会暂停一下的连续运动（如飘扬的旗帜、缓缓移动的烟雾）反复触发。即使最后一帧仍在运动，也会对其进行评估（因此不会丢失视频的结束状态），但它和其他帧一样，必须通过两项对比度门槛。--report 会生成 report.html，显示每项保留／丢弃决策及差异百分比（局部静止通道保留的帧会特别标注），方便调整参数。
4. 文本 — 如果视频已有字幕（本地文件旁的 .srt／.vtt 伴随文件，或嵌入式字幕轨道），就会直接使用这些字幕作为转录文本——比重新转录更快、更准确。只有在没有字幕时，才会回退到对音频使用 Whisper（无音频时会直接跳过）。
5. 音频（可选，--keep-audio）— 保存完整的原始音轨（audio.m4a：音乐 + 语音 + 音效；可能时无损复制）。转录文本只有文字；音频文件能让具备聆听能力的模型（Gemini、GPT-4o 等）真正听到音乐和语气。
6. 时间戳 — 每个保留帧在源视频中的时间戳都会贯穿整个处理流程（提取 → 去重 → --max-frames 精简 → 重命名），并写入 frames.json（file／timestamp_sec／timestamp／selection_reason）。引用视觉证据时可使用 frame_012 @ 00:03:41，将帧与 transcript.json 中的片段对齐，或将映射提供给视频 RAG 工作流。在 viewer.html 中，点击任意关键帧 →“从这里播放视频”。
7. 清单 — MANIFEST.txt 汇总了供模型使用的全部内容。

这样，模型就能看见视频（关键帧）、阅读视频（转录文本），并且在使用 --keep-audio 时听见视频（完整音轨）。转录文本是任何模型都能读取的纯文本；该工具不会将字幕烧录到视频中——烧录是展示方式的选择，并非让 AI 能够读取视频的必要条件。

注意事项

• 只能下载你有权下载的内容。--cookies 选项用于你本人经授权的访问——不要将凭据提交到代码仓库中。
• 每个视频使用一个输出文件夹。若目标文件夹中已有分析结果，则拒绝再次写入（避免混入两个视频）；如需替换，请传入 --overwrite。

crv Pro — 了解视频是如何拍摄的

免费工具会为 AI 提供关键帧和转录文本——足以了解视频讲了什么。crv Pro 还会提供其他所有信息：视频如何拍摄、如何剪辑、如何表达，以及带给人什么感受。 所有计算都在你的机器上完成，并以任何大模型都能读取的纯文本形式写入。

• 镜头与节奏（--motion） — 自动为每个镜头标注类型：静止、平移、倾斜、变焦、手持。完整镜头表：每个镜头的时长、每分钟剪辑次数，以及开场／中段／结尾的节奏。高运动镜头会生成间隔 0.2 秒的连拍帧。
• 声音与情绪（--senses） — 按片段逐一标记语音情绪、语气曲线和音频事件（笑声、音效、环境音）的时间戳。人声和音乐会自动分离：情绪分析读取干净的人声，音乐则单独生成 BPM 和能量轨迹。对于无对白影像（音乐视频、电影），则通过色彩和光线来判断情绪。
• 交互式查看器（--viewer） — 每次分析都会生成一个独立的网页：包含视频、可点击并跳转到相应秒数的事件时间线，以及随播放进度高亮的转录文本。支持 EN / 繁中 / 简中。
• 两份报告，一个标志（--ai-report） — 使用你自己的 API 密钥，生成两份报告：一份分析拍摄方式，一份分析视频内容。
• 拆解报告（--breakdown） — 分析开场钩子、节奏曲线、镜头语言，并提供一套评估标准，由你自己的大模型补全为完整拆解报告。
• 跨媒体库记忆（crv-pro-ask） — 根据镜头和语音的表现，搜索 Pro 看过的所有内容：--camera zoom（看过的所有变焦镜头）、--track emotion --label angry、--rhythm（按每分钟剪辑次数排序）。免费版 crv-ask 搜索文字；这些功能则搜索免费版从未采集的测量数据。

一次性付费 $29：

• 在 Capafy 购买（立即下载，包含许可证密钥）：https://capafy.ai/agent/llm-real-video-pro-let-any-llm-watch-videos/5451082151
• 使用信用卡购买（Lemon Squeezy 结账，立即下载）：https://leoaido.lemonsqueezy.com/checkout/buy/ff552000-adc0-49f1-8eec-5e8ada1905a1
• 产品页面与演示：https://leoaido.com/crv-pro/

关注开发进展？ 我正在公开记录从开源工具到首位付费客户的历程——@LeoAidoAI on X。

常见问题

让大模型观看或分析视频，最好的工具是什么？

这取决于你所说的“观看”是什么意思。如果你只想了解一个片段，并且不介意上传它，托管式多模态模型（例如 Gemini）是最直接的选择。如果你想让任何大模型——Claude、GPT、Gemini 或本地模型——可重复地在本地分析视频，就需要一个预处理流程：提取能感知场景的关键帧，并生成带时间戳的转录文本，再将它们作为模型可以引用的证据。claude-real-video 正是通过一个命令完成这一流程，而且不会有任何内容离开你的机器。均匀抽帧（每秒 1 帧）要么会漏掉剪辑点，要么会塞满上下文窗口；感知场景的提取方式则能保留承载信息的帧。

如何让 Claude 理解视频？

Claude 无法直接读取视频文件。可行的方法如下：

pip install "claude-real-video[fast]"
npx skills add HUANGCHIHHUNGLeo/claude-real-video   # or install via the Claude Code plugin marketplace

然后在 Claude Code 中运行：Analyze this video: /path/to/video.mp4。该技能会提取能感知场景的关键帧、带时间戳的转录文本（transcript.json）、帧→时间戳映射（frames.json），以及用于告知模型如何读取文件夹的 MANIFEST.txt——这样 Claude 就能引用 frame_012 @ 00:03:41，而不是靠猜测。

什么是 claude-real-video？

这是一个采用 MIT 许可证的 Python 命令行工具（crv），可将视频转换为大模型实际能读取的内容：能感知场景的关键帧（附带经过重复帧去重和重命名后仍有效的真实源时间戳）、滑动窗口去重（避免丢弃小主体的运动），以及支持可选说话人标签的本地 Whisper 转录。支持 YouTube URL 和本地文件，100% 在本地运行。开发它的原因是：字幕不等于观看——只读取转录文本的模型会对所有视觉内容产生幻觉。

制作团队

由 Leo Huang 打造——一家由 AI 驱动的单人公司。 我会分享构建这类工具时实际遇到的问题和有效的方法： https://x.com/LeoAidoAI

许可证

MIT