video-digest 是做什么的?
概述
将任意视频转换为一篇可搜索的 Markdown 摘要。对于每个视频片段,该技能生成三项内容并整合到一个 digest.md 文件中:
- 转录文字 — 语音内容(使用 faster-whisper,本地处理)。
- 屏幕文本 — 视频帧中出现的所有独特文本行(OCR),并单独提取其中的 URL 和 @handles。
- 联系表拼贴 — 覆盖整个片段的帧网格,让你一目了然地阅读其视觉故事。
所有操作都在本地运行。无需网络调用,无需账号,无遥测。核心仅需 ffmpeg;转录和 OCR 是可选的,且会优雅降级。
何时使用
- “这个视频/这 200 个视频里有什么?”而无需逐个观看。
- 构建可搜索的视频目录,如短片、演讲、教程或素材。
- 恢复视频屏幕上闪现的链接和用户名。
- 快速获取长视频或大量视频的视觉概览(拼贴)。
不适用于:直播、编辑/剪辑视频或生成视频。本技能只读取视频并输出文本和图像摘要。
快速参考
scripts/check-deps.sh # 查看已安装的工具及如何安装剩余部分
scripts/video-digest.sh clip.mp4 # 处理单个视频 → ./video-digest-out/clip/digest.md
scripts/video-digest.sh --out ~/digests *.mp4 # 批量处理整个文件夹
scripts/video-digest.sh --lang en talk.mov # 指定转录语言
scripts/video-digest.sh --no-transcript reel.mp4 # 跳过音频,仅处理视觉和文字
scripts/video-digest.sh --ocr-engine tesseract x.mp4 # 强制使用特定 OCR 引擎
| 标志 | 用途 | 默认值 |
|---|---|---|
-o, --out DIR | 输出根目录 | ./video-digest-out |
--fps N | OCR 帧采样率 | 2 |
--montage-frames N | 在视频中均匀分布的帧数 | 90 |
--tile CxR | 拼贴网格 | 3x3 |
--ocr-engine E | auto|vision|tesseract|none | auto |
--whisper-model M | tiny|base|small|medium(+.en) | small |
--whisper-python P | 安装了 faster-whisper 的解释器路径 | 自动检测 |
--lang CODE | 转录语言提示 | 自动检测 |
--no-transcript / --no-ocr / --no-montage | 跳过某个阶段 | — |
--force | 即使已经缓存也重新运行阶段 | 关闭 |
运行 scripts/video-digest.sh --help 查看完整列表。
工作原理
入口脚本 scripts/video-digest.sh 协调三个独立的小工具,你也可以单独运行它们:
| 阶段 | 脚本 | 引擎 |
|---|---|---|
| 拼贴 | scripts/montage.sh | ffmpeg tile 滤镜 |
| 屏幕文本 | scripts/ocr.sh (+ ocr_vision.swift) | macOS Vision(默认)或 tesseract |
| 转录 | scripts/transcribe.py | faster-whisper |
每个阶段都是可恢复的 — 已完成的工作会被标记为 .done 并缓存,除非你传入 --force,否则重新运行时会跳过。摘要总是根据当前存在的阶段重新构建,因此部分运行仍然可以生成有用的文件。
OCR 引擎自动选择:在 macOS 上使用内置的 Vision 框架(无需安装,本地处理),否则如果安装了 tesseract 则使用它,否则会跳过 OCR 并发出警告。有关安装可选后端的信息,请参见 references/setup.md;有关确切的输出布局,请参见 references/output-format.md。
常见错误
- 转录为空 → 正在使用的解释器中未安装 faster-whisper。运行
scripts/check-deps.sh,然后执行pip install faster-whisper,或者使用--whisper-python /path/to/python指向已有的环境。 - Linux 上无屏幕文本 → 安装
tesseract(apt install tesseract-ocr);Vision 引擎仅适用于 macOS。 - 短视频上拼贴帧数过多 → 减小
--montage-frames(例如30)。 - 转录语言错误 → 传入
--lang(例如--lang sk),或使用非.en模型以支持多语言音频。
示例
examples/sample-digest/ 目录包含一个生成的小视频片段及其生成的 digest.md — 包含转录文字、一个检测到的 URL、一个 @handle 和一张拼贴表。可以通过以下命令重现(转录行需要安装 faster-whisper):
scripts/video-digest.sh --montage-frames 9 examples/sample-digest/sample.mp4