开源项目：通用LLM视频理解适配器

▶ 这部 60 秒的像素短片——请打开声音（GitHub 上提供 mp4）· 一个 AI Agent 搜索“怎样才能让 LLM 真正理解视频？”，找到一把钥匙，并由此解锁视觉能力。

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

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

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 市场的安装方式（如果希望自动更新，请在 /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 package）的简称。付费附加组件 crv Pro 在 Capafy 上以“llm-real-video Pro”的名称销售。

还是同一段 58 秒的视频：固定按 1 fps 采样会得到 58 帧。crv 只保留其中真正发生变化的 26 帧，并通过 --grid 把它们排进 3 张联系表（contact sheet）。消耗的 token 更少，却不会漏掉内容。

免费版可以让你的 AI 看见视频。crv Pro 则可以让它理解视频——包括视频是如何拍摄的（剪辑节奏、镜头运动），以及一份带时间戳的时间线，记录静态帧无法呈现的信息：手势、表情、音高变化、情绪和声音事件。创始人一次性优惠价为 19 美元，有效期截至 7 月 31 日；8 月 1 日起价格为 29 美元。可在 Capafy 购买，也可通过 Lemon Squeezy 使用银行卡购买。

大多数 AI 工具其实并没有真正看见视频。把 YouTube 链接粘贴到 ChatGPT，它读取的是转录文本，而不是画面。Claude 完全不接受视频文件。即使是能够原生读取视频的 Gemini，也必须先把视频上传到 Google，并按固定间隔采样帧（默认 1 fps），因此快速剪辑的镜头很容易被漏掉。

claude-real-video 采用了不同的方法，而且处理过程在本地运行：给它一个 URL 或文件，它会提取真正重要的帧——每次场景变化，而不是固定数量——丢弃近似重复帧、转录音频，并生成一个任何 LLM 都能读取的整洁文件夹。所有处理都发生在你自己的机器上；真正可能被发送到其他地方的，只有你之后自行选择粘贴给 LLM 的帧和文本。

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，再打开结果查看器即可。视频分析和输出生成都在你的机器上运行，源视频绝不会被上传。（如果之后把提取出的帧或转录文本粘贴给云端 LLM，这些数据就会发送给对应的服务提供商。）

想先亲眼看看模型将会看到什么？添加 --viewer，它会生成本地的 viewer.html，其中包含视频、关键帧网格和转录文本，双击即可打开。不需要网络，也不需要额外安装。

对于变化缓慢的内容（动画教程、渐变变形、缓慢摇摄），添加 --adaptive。系统会根据每一帧的滚动邻域来选择帧，而不是使用固定阈值，因此即使一段持续 2～3 秒的挤压拉伸动画从未在任何单帧上产生突变，也仍然能够被捕获。

对于文字密集型内容（课程幻灯片、屏幕录制、出镜讲解视频），添加 --text-anchors。系统会强制在字幕提示的时间戳处额外取帧，因此即使场景几乎没有变化，每段口述内容也能匹配相应画面。它需要 sidecar .srt/.vtt 文件或内嵌字幕轨道；直接烧录在像素画面里的字幕无法被检测。每秒最多强制提取一帧，场景检测逻辑不受影响。

对于多人发言内容（访谈、播客、会议），添加 --speakers。转录文本中的每一行都会获得 speaker 标签（[SPEAKER_00]、[SPEAKER_01]……），让模型能够判断每句话是谁说的。该功能运行一个本地说话人分离模型，大小为 45 MB，只需下载一次，不需要账号或 token。安装命令为 pip install "claude-real-video[speakers]"。

不做 LLM 相关工作？它也可以用作通用的视频关键帧提取器——提供场景变化检测和去重，不需要下载 ML 模型。

正在使用 Claude Code 或其他 coding Agent？一条命令即可安装该 skill，支持 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/

0.3.0 版本的新功能——告诉它你为什么要看这段视频，并把找到的内容保存下来：

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

--why 会让分析聚焦于你真正关心的问题，而不是生成泛泛的摘要；--kb 会把结果保存为你自己笔记文件夹中的一篇带日期笔记，避免结果随着 crv-out 一起消失。

在一段 3 分钟、分辨率为 640×360 的视频（benchmark/jfk-rice.mp4）上进行真实测试：使用 Mac mini M4、本地 CPU，只提取帧并去重（--no-transcribe）。图像 token 按 Anthropic 的 (width x height) / 750 公式估算，640×360 的视频每帧约为 307 token。

Dedup v0.7.16——画面中占比很小的高速运动主体不再消失。按百分比比较的算法在结构上无法感知只占画面不到 1% 的主体，因为它永远不可能让 8% 的像素发生变化。这个问题是在一位用户批量处理 2,181 个视频时发现的，现已通过第三条“action channel”修复。合成复现案例：一个静态的 1280×720 镜头，其中有一个 40×90 px、仅占画面 0.4% 的主体，只在总计 65 帧中的最后 10 帧快速移动。

为什么不直接采样视频帧？

大多数“让 LLM 观看视频”的脚本——包括 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]，就没有 speech-to-text 功能；不过，如果视频自带字幕，仍然可以得到转录文本。

系统要求：ffmpeg

帧提取和音频处理会使用 ffmpeg / ffprobe，它们无法通过 pip 安装，只需单独安装一次。

确认它已经位于你的 PATH 中：

ffmpeg -version

转录功能使用 whisper CLI，它会随 [whisper] extra 一起安装，也可以通过 pip install openai-whisper 安装。Whisper 同样依赖 ffmpeg。

如果想获得速度更快、不会编造内容的转录结果（推荐），请安装 [fast] extra。crv 会自动切换到 faster-whisper——使用相同模型、生成相同输出文件，但速度快数倍，并通过 Silero VAD（voice-activity detection）进行门控：只有音乐或完全静音的音频会如实生成“没有语音”的说明，而不是像 Whisper 那样生成经典的虚构字幕。无需学习任何新参数：

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

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

支持 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 的输出是什么样的？

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

from claude_real_video import process

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

Fetch——URL 使用 yt-dlp 获取，可选 cookie；本地文件则直接复制。

Extract——通过一次按时间顺序执行的 ffmpeg select，提取每一次场景变化，同时设置密度下限，即至少每隔 --fps-floor 秒提取一帧，因此快速剪辑和缓慢变化的屏幕录制都能被覆盖。

Dedup——通过三个 channel，将当前帧与最近 --dedup-window 个已保留帧组成的滑动窗口进行比较，因此遇到 A-B-A 式的插入镜头时，不会重复发送模型已经见过的画面。global channel 衡量真实的像素差异，使用缩小后的 RGB，而不是 perceptual hash——hash 在纯色和等亮度色相变化时会失明；--dedup-threshold 表示必须发生变化的像素百分比。

settled-local channel（v0.7.4）会捕获 global channel 无法看见的变化：细小的笔画、字幕或文字卡片切换，以及全局平均变化接近 0% 的小型 UI 更新。它会使用更精细的 signature，寻找一个与最近所有已保留帧都存在明显差异、而且已经停止变化的区域——即已经稳定的新状态，而不是运动过程中的中间帧。它还具有 1 px 位移容差，避免胶片颗粒和画面抖动触发检测，并设有 cooldown，防止持续运动但每秒都会短暂停顿的内容——例如飘动的旗帜或烟雾——反复触发。

即使最后一帧仍处于运动状态，也会被纳入评估，确保视频的结束状态永远不会丢失；但和其他帧一样，它也必须通过两道对比度门槛。--report 会生成 report.html，展示每一个 keep/drop 决策及其 diff 百分比，便于调优；由 settled-local 保留的帧会被明确标注。

Text——如果视频已经包含字幕，例如本地文件旁边存在 sidecar .srt/.vtt，或视频含有内嵌字幕轨道，系统会直接使用字幕作为转录文本。这比重新转录更快，也更准确。只有在不存在字幕时，才会回退到 Whisper 处理音频；如果没有音频，则会干净地跳过。

Audio（可选，--keep-audio）——保存完整的原始声轨，即 audio.m4a，其中包括音乐、语音和音效；在可能的情况下会进行无损复制。转录文本只包含说出的文字，而音频文件能让具备听觉能力的模型——例如 Gemini、GPT-4o 等——真正听到音乐和语气。

Timestamps——每个保留帧在源视频中的时间会贯穿整个处理流程，包括 extraction、dedup、--max-frames 稀疏化和重命名，并写入 frames.json，字段包括 file、timestamp_sec、timestamp 和 selection_reason。你可以使用 frame_012 @ 00:03:41 的格式引用视觉证据，让帧与 transcript.json 中的 segment 对齐，或者把这张映射表交给 video-RAG pipeline。在 viewer.html 中点击任意关键帧，即可“从这里开始播放视频”。

Manifest——MANIFEST.txt 会为模型汇总所有内容。

这样一来，模型可以看见视频的关键帧、阅读转录文本，并在使用 --keep-audio 时听见完整声轨。转录文本是任何模型都能读取的纯文本；这个工具不会把字幕烧录进视频——烧录字幕是一种展示选择，并不是让 AI 能够读取视频所必需的步骤。

只能下载你有权获取的内容。--cookies 选项仅适用于你本人获得授权的访问，不要把凭据提交到代码仓库。

每个视频应使用一个独立的输出文件夹。如果目标文件夹中已经存在一份分析结果，再次运行时会被拒绝，从而确保两个视频永远不会混在一起；如需替换，请传入 --overwrite。

crv Pro——理解视频是怎样拍出来的

免费工具会向 AI 提供关键帧和转录文本，这足以让它理解视频讲了什么。crv Pro 则补充了其他所有信息：它是怎样拍摄的、怎样剪辑的、怎样表达的，以及它带给人的感受。所有内容都在你的机器上计算，并写成任何 LLM 都能读取的纯文本。

Camera & pacing（--motion）——自动标记每一个镜头：static、pan、tilt、zoom、handheld。生成完整的镜头表，包括每个镜头的时长、每分钟剪辑次数，以及开头、中段、结尾的节奏变化。高运动镜头还会得到间隔 0.2 秒的 burst frames。

Sound & emotion（--senses）——逐段记录带时间戳的声音情绪、语调曲线和音频事件，包括笑声、SFX 和环境声。系统会自动分离人声和音乐：从干净的人声中分析情绪，同时为音乐生成单独的 BPM 与能量轨迹。对于没有对白的画面，例如 MV 或电影，则会回退为通过色彩和光线判断氛围。

Interactive viewer（--viewer）——每份分析对应一个独立、完整的网页，其中包含视频、点击后可跳转到对应秒数的事件时间线，以及会随播放进度高亮的转录文本。支持 EN、繁中和简中。

Two reports, one flag（--ai-report）——使用你自己的 API key，一份报告分析视频怎样拍摄，另一份报告分析视频说了什么。

Breakdown report（--breakdown）——提供 hook 分析、节奏曲线、镜头语言，以及一套可由你自己的 LLM 补全为完整拆解报告的 rubric。

创始人一次性优惠价为 19 美元，有效期截至 7 月 31 日；8 月 1 日起价格为 29 美元。

可通过 Capafy 购买，购买后可立即下载并获得 license key。

也可通过 Lemon Squeezy 使用信用卡购买，购买后立即下载。

另有产品页面和演示。

想继续关注产品开发过程？我正在公开记录自己如何把一个开源工具做成拥有首位付费客户的产品——可在 X 上关注 @LeoAidoAI。

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

这取决于你所说的“观看”是什么意思。如果你只想针对一段视频得到一个答案，而且不介意上传视频，那么 hosted multimodal model——例如 Gemini——是最短路径。如果你希望任何 LLM——Claude、GPT、Gemini 或本地模型——都能以可复现、完全本地的方式分析视频，你需要的是一套预处理 pipeline：提取能够感知场景变化的关键帧，生成带时间戳的转录文本，再把它们作为模型可以引用的证据交给模型。

这正是 claude-real-video 通过一条命令完成的工作，而且任何内容都不会离开你的机器。均匀帧采样（1 fps）要么会漏掉剪辑点，要么会淹没 context window；场景感知提取只保留真正承载信息的帧。

怎样让 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。该 skill 会提取能够感知场景变化的关键帧、带时间戳的转录文本（transcript.json）、帧到时间戳的映射（frames.json），以及一份告诉模型如何读取该文件夹的 MANIFEST.txt。这样，Claude 就可以引用 frame_012 @ 00:03:41，而不是凭空猜测。

什么是 claude-real-video？

它是一个采用 MIT license 的 Python CLI（crv），可以把视频转换成 LLM 真正能够读取的形式：根据场景变化提取关键帧，并保留能够贯穿去重和重命名过程的真实源时间戳；通过 sliding-window deduplication 避免误删小主体的运动；使用本地 Whisper 转录，还可以选择添加 speaker 标签。

它既支持 YouTube URL，也支持本地文件，并且 100% 在本地运行。这个项目之所以存在，是因为只读字幕并不等于观看视频——只读转录文本的模型，会凭空编造所有视觉内容。

由 Leo Huang 开发——这是一家由 AI 驱动的一人公司。我会持续分享开发这类工具时，哪些地方真的会出问题、哪些方法确实有效。