video-digest は何をしますか?
概要
任意の動画を一つの検索可能な Markdown ダイジェストに変換します。各クリップに対して以下の3つを生成し、それらを digest.md に統合します。
- 文字起こし (Transcript) — 発話のテキスト(faster-whisper、デバイス上処理)
- 画面テキスト (On-screen text) — フレームに表示されている固有のテキスト行のすべて(OCR)、さらに URL と @ハンドル を別途抽出
- コンタクトシートモンタージュ (Contact-sheet montages) — クリップ全体からフレームをグリッド状に抽出し、一目で映像のストーリーを把握可能
すべての処理はローカルで実行されます。ネットワーク呼び出し、アカウント、テレメトリは一切ありません。コア機能は ffmpeg のみ必要で、文字起こしと OCR はオプションであり、不足時は安全に動作を縮退します。
使用すべき場面
- 「この動画(200本の動画)に何が含まれているか」を視聴せずに把握したい場合
- リール、トーク、チュートリアル、フッテージの 検索可能なカタログ を構築する場合
- クリップ内で一瞬表示された リンクやハンドル を回収する場合
- 長時間または多数の録画を高速に 視覚的に概要把握(モンタージュ)したい場合
対象外: ライブ配信、動画の編集・カット、動画生成。本ツールは動画を読み取り、テキスト+画像の要約を出力します。
クイックリファレンス
scripts/check-deps.sh # インストール済みのもの+残りの入手方法を表示
scripts/video-digest.sh clip.mp4 # 1動画 → ./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 がインストールされたPythonインタプリタ | 自動検出 |
--lang CODE | 文字起こしの言語ヒント | 自動検出 |
--no-transcript / --no-ocr / --no-montage | 特定の段階をスキップ | — |
--force | キャッシュがあっても各段階を再実行 | off |
全リストは scripts/video-digest.sh --help を実行してください。
仕組み
エントリポイント scripts/video-digest.sh は、以下の3つの独立した小さなツールを統括します(それぞれ単独でも実行可能)。
| 段階 | スクリプト | エンジン |
|---|---|---|
| モンタージュ | scripts/montage.sh | ffmpeg タイルフィルター |
| 画面テキスト | scripts/ocr.sh (+ ocr_vision.swift) | macOS Vision(デフォルト)または tesseract |
| 文字起こし | scripts/transcribe.py | faster-whisper |
各段階は 再開可能 です。完了した処理は .done としてマーク/キャッシュされ、再実行時はスキップされます(--force 指定時を除く)。ダイジェストは常に存在する段階の結果から再構築されるため、部分的に実行した場合でも有用なファイルが生成されます。
OCRエンジンの自動選択: macOS では内蔵の Vision フレームワークを使用(インストール不要、デバイス上処理)、それ以外の OS では tesseract が存在すればそれを使用、なければ警告を出して OCR をスキップします。オプションバックエンドのインストール方法は references/setup.md、正確な出力レイアウトは references/output-format.md を参照してください。
よくある間違い
- 文字起こしが空 → faster-whisper が使用中のPythonインタプリタにインストールされていません。
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 が含まれています(文字起こし、1つの検出URL、1つの@ハンドル、モンタージュシート)。以下のコマンドで再現できます(文字起こし行には faster-whisper のインストールが必要です)。
scripts/video-digest.sh --montage-frames 9 examples/sample-digest/sample.mp4