video-digest 是做什麼的?
概述
將任何影片轉換成單一可搜尋的 Markdown 摘要。對於每個片段,這個技能會產出三項內容,並將它們整合成一份 digest.md:
- 逐字稿 — 口語內容(使用 faster-whisper,在裝置端執行)。
- 螢幕文字 — 畫面中每一行獨特的文字(OCR),並將 URLs 和 @handles 獨立提取出來。
- 連環縮圖 — 橫跨整個片段的格狀畫面,讓您一眼就能讀取其視覺故事。
一切都在本機執行。無需網路呼叫、不需帳號、沒有遙測。核心只需要 ffmpeg;逐字稿和 OCR 為選用功能,且會優雅地降級。
使用時機
- 「這個影片 / 這兩百部影片裡有什麼?」不必觀看就能知道。
- 為短片、演講、教學或素材建立可搜尋的目錄。
- 還原影片中閃過的連結與帳號。
- 快速取得長影片或多段錄影的視覺概覽(連環圖)。
不適用於:即時串流、編輯/剪輯影片,或產生影片。這個技能是用來讀取影片並產出文字與圖像摘要。
快速參考
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 平鋪濾鏡 |
| 螢幕文字 | 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