video-to-llm

你的 LLM 无法看完一个 40 小时的课程。上传视频很慢，通常很贵，而且常常不被允许。自己抽取帧会消耗数百万 token，同时还丢掉了音频。

video-to-llm 把每段视频变成一份按时间顺序整理的文档——语音、被标记的静默片段、章节标题，以及可选的画面内容——全部按实际发生顺序排列，每一行都带时间戳，可回溯到它来自的准确帧。

只做一次。之后你想问多少问题就问多少，想用多少模型就用多少模型，只要你保留这个文件夹。

快速开始

uvx video-to-llm process lecture.mp4 --transcribe-model tiny

这就是能最快看到效果的方式：tiny 语音模型下载量只有 75 MB，而不是默认模型的 1.4 GB。这样你大约一分钟后就能得到真实文档，而不是先花时间下载，再发现是否喜欢输出。等确定之后，去掉这个参数即可：

uvx video-to-llm process lecture.mp4

还不能从 PyPI 安装。 名字已经被注册，但索引上还没有值得安装的东西：发布的唯一版本 1.0.0rc1 发布时缺少 collections 模块，后来已被撤回。在 1.0.0 正式发布之前，请克隆仓库并运行 uv sync，然后运行 uv run video-to-llm process lecture.mp4 --transcribe-model tiny。

你需要把 FFmpeg 放到 PATH 里——版本 4 到 9 都可以。语音模型只在首次时下载一次，之后就不会再有任何网络访问。

video-to-llm doctor          # check this machine is ready

tiny 很快但明显不够准确；medium 是默认值，因为它是默认最小的能保留一份可用的转录文本的模型。--transcribe-model 也支持 base、small 和 large-v3。

Related MCP server: video-reader-mcp

你会得到什么

这是真实的输出——来自 49 分钟真实录制的真实文本行，使用默认配置：

00:01:30  [nobody speaking · 11 seconds]
00:01:40  Yep, just so that you know, the first thing you'll do is you'll take everything out of
00:01:48  your chart.
00:01:49  When you're going to analyze the chart.
00:01:54  [nobody speaking · 4 seconds]
00:01:58  I think all of you know what trends are, right?
00:02:01  You're either going up or you're either coming down. Very simple, right?
00:02:05  But when you look at trends in terms of structure, what we are looking for is the basic.

这就是整个产物：纯文本、时间顺序、时间徐指向源视频，并且完全属于你。你可以把它交给任何模型。可以用 grep 搜索。可以留十年。

核对任一行的会

每个时间戳都能解析回它背后的画面：

video-to-llm show lecture 00:02:05

lecture.mp4 — 00:02:05
in job 'lecture'

  00:02:01  You're either going up or you're either coming down. Very simple, right?
> 00:02:05  But when you look at trends in terms of structure, what we are looking for is the basic.

Picture: ~/Documents/VideoToLLM/lecture/…/frames/000062_t000124.jpg

你的模型做出的断言，只有在你能够核实时才是证据。这就是核对的方法。

对比

一切都如实说明——包括在哪些情况下这是一个错误的工具。

以上已于 2026 年 8 月 21 日根据这些项目自己的文档进行核对。它们会变化；如果这里发现某一行过时了，那是一个值得报的问题。

使用

从命令行

video-to-llm process lecture.mp4                      # one video
video-to-llm process w1.mp4 w2.mp4 --name "Course"    # several, in your order
video-to-llm process talk.mp4 --interval 5            # fewer pictures, faster
video-to-llm process demo.mp4 --describe local        # add screen descriptions
video-to-llm process talk.mp4 --format jsonl          # also emit structured data
video-to-llm show "Course" 01:12:30                   # resolve a citation
video-to-llm export "Course" --format srt             # subtitles, no reprocessing
video-to-llm status                                   # what is done, what is running
video-to-llm run-next "Course"                        # jump the queue

从智能体

video-to-llm mcp        # MCP server on stdio; needs the [mcp] extra

四个工具——process_video、list_videos、get_transcript、get_segment。process_video 幂等：如果让它处理一个之前处理过的视频，它会直接返回已有文档，而不是又重新做一遍。这正是它的意义所在。 40 小时的课程一次处理完；之后的每个问题都是即时、离线、免费的。

智能体â€T hat cannot choose a paid describe service through these tools choose nothing. That decision belongs on the setup screen, where the estimate and the spending cap are visible.

还有一个技能，它可以教智能体在执行任何昂贵操作之前，先检查已经处理了哪些内容：

npx skills add navdeep-h-singh/video-to-llm -g

That works in Codex, Cursor, Copilot, Gemini CLI, and anything else that reads Agent Skills. 对于 Claude Code，这个技能和 MCP 服务器会一起注册插件：

/plugin marketplace add navdeep-h-singh/video-to-llm
/plugin install video-to-llm@video-to-llm

在浏览器中使用

video-to-llm start

一个运行在 127.0.0.1 的界面，带有实时进度、帧检查器、任务控制，以及合集构建器。关闭浏览器不会终止任务。

合集

多个已处理的视频，按你明确指定的顺序，合成为一份文档，或者拆分为适合放进上下文窗口的有编号分块。构建合集完全是复用已有输出——它不会重新抽取帧，不会重新转录音频，也不会重新运行描述。

顺序永远不会从文件名、日期或内容中推断出来。同一天的早间两段录音本来就没有先后顺序，所以你要自己说明顺序。

隐私即机制

这不是口头承诺，而是一组有具体可执行的特征，一旦这些特征退成测试就会失败。

• 界面绑定到 127.0.0.1，并且在应用程序构造时断言。

• 有一个中间件在每次写入时拒绝外部 Host 和跨域来源。

• 没有页面加载跨域资源。没有 CDN，没有网络字体，没有分析工具

• 你的视频永远不会被复制、移动或上传。

• 密钥由操作系统钥匙串存储——macOS Keychain、Windows Credential Manager、Linux Secret Service。永远不会创建明文降级方案，已保存的密钥也永远不会回显，甚至连前缀都不会。

• 没有账号、没有遥测、没有需要登录。

• 描述默认关闭。不启用描述的任务根本不会发出任何网络请求。

• 本地处理绝不会静默退回到云端。

可选：屏幕描述

默认关闭。启用后，你可以在自己的 Ollama 模型（帧 留在你的设备上，不花钱）和服务商之间选择。处理器会收到只有带编号的静止画面，永远不会收到视频，也不会收到音频。在外发任何内容之前，你会看到将发送什么以及大概成本，并且处理会在你设定的上限处停止。

系统要求

• Python 3.11、3.12 或 3.13

• PATH 上带 ffprobe 的 FFmpeg

• 语音模型所需空间——tiny 需要 75 MB，默认的 medium 需要 1.4 GB——另外还要存放帧的空间：2 小时的视频每 2 秒一帧大约需要 2 GB

GPU 在一切部分都是可选项。转录在所有平台上都使用 CPU 运行。

FFmpeg 9 完全没问题。 它删除了 -vsync，这是 FFmpeg 5 之前每个版本都要求的参数；提取过程在运行时读取一次版本，然后询问当前构建支持哪个标志，因此无论 4.x 到 9.x 都能工作。video-to-llm doctor 会打印它找到的版本以及今后要使用的标志。开发工作主要针对 8.1.2；其余版本由参数列表测试和 CI 矩阵覆盖。

其他安装方式

uv tool install video-to-llm            # or: pipx install video-to-llm
uv sync                                 # from a clone
docker build -t video-to-llm .          # command line only, see the Dockerfile

已知限制

这里刻意写出来留在这里，而不是留给你自己去发现。

• 屏幕描述仍处于 beta 阶段，其结构化字段只为单一领域编写。 它们是能生效的——在 49 分钟的图表录屏中，模型从屏幕上读对了品种、时间周期，也读到了真实数值——但八个字段中的五个（timeframe、currency_pair、indicators_and_states、exact_action、setup_type）描述的是交易图表，这是有意为之，而非疏漏。在任何其他视频中，这五个字段都会返回 Unknown。 模型宁可拒绝回答也不凭空编造，所以结果只是单薄，而不是错误；而且 visible_text、visual_description 和 confidence 对任何内容都仍然适用。无论哪种情况，这部分准确性都是未测的。背后的实验见 docs/DESCRIPTION_QUALITY.md。

  转录文字、时间轴和引用信息是任何视频上都适用、可靠的部分。请以这些为准来评估这个工具。

• 转录准确度未被测量，而且 Whisper 有时会在静音上写出一行文本——转录稿的开头出现“Thanks for watching!”是模型生成的，不是你的视频里原有的内容。

• 本地描述很慢：在 Apple Silicon Mac 上约 31 秒/张，这是基于 1,488 张的测量结果。请改用更粗粒度的 --interval，或使用有配额上限的服务。

• 没有任何云服务商做过真实服务的联测。 五个适配器只能根据文档中的请求和响应结构验证；本地 Ollama 已针对 0.32.6 与 qwen2.5vl:7b 做了实机验证。

• 还没有人在 Windows 或 Linux 上真正使用过，不过 CI 现在已经能在这两个系统上跑了。 开发完全是在 macOS（Apple Silicon）上完成的。测试套件已经能在这三个操作系统和三种 Python 版本上全部通过，构建出的 wheel 也在每个系统上源码检出目录之外完成安装并运行过，容器也能在无网络的情况下把流水线端到端跑完。这是真实存在的下限，但和使用不是一回事：一个全绿的矩阵只能说明那些路径、keyring 后端和符号链接回退方案在干净的 runner 上能工作，不能说明在你的机器、你的文件上都通用。无论来自这些平台中哪一边的使用报告，都是这个项目最需要的东西。

• 容器自带的是命令行，不是界面——界面要绑定回环地址（loopback），而在容器内部它对外部宿主机不可达。

• 不支持下载 URL。 仅支持本地文件。请先自己抓取到本地。

• 事件日志会无限制地增长。

文档

贡献

目前，来自真实使用的 bug 报告比其他任何东西都更有价值，尤其是在 Windows 和 Linux 上。参见 CONTRIBUTING.md。

许可证

MIT。参见 LICENSE。