影片理解
使用 ffmpeg 進行畫格擷取與 Whisper 語音轉寫,在本地端理解影片內容。完全離線,無需 API 金鑰。
前提條件
ffmpeg+ffprobe(必要):brew install ffmpegopenai-whisper(選用,用於轉寫):pip install openai-whisper
指令
# 場景偵測 + 轉寫(預設)
python3 skills/video-understand/scripts/understand_video.py video.mp4
# 關鍵畫格擷取
python3 skills/video-understand/scripts/understand_video.py video.mp4 -m keyframe
# 固定間隔擷取
python3 skills/video-understand/scripts/understand_video.py video.mp4 -m interval
# 限制擷取畫格數量
python3 skills/video-understand/scripts/understand_video.py video.mp4 --max-frames 10
# 使用較大的 Whisper 模型
python3 skills/video-understand/scripts/understand_video.py video.mp4 --whisper-model small
# 僅擷取畫格,跳過語音轉寫
python3 skills/video-understand/scripts/understand_video.py video.mp4 --no-transcribe
# 安靜模式(僅輸出 JSON,無進度訊息)
python3 skills/video-understand/scripts/understand_video.py video.mp4 -q
# 輸出到檔案
python3 skills/video-understand/scripts/understand_video.py video.mp4 -o result.json
CLI 選項
| 標記 | 說明 |
|---|---|
video | 輸入影片檔(位置參數,必要) |
-m, --mode | 擷取模式:scene(預設)、keyframe、interval |
--max-frames | 最大保留畫格數(預設:20) |
--whisper-model | Whisper 模型大小:tiny、base、small、medium、large(預設:base) |
--no-transcribe | 跳過語音轉寫,僅擷取畫格 |
-o, --output | 將結果 JSON 寫入檔案而非 stdout |
-q, --quiet | 隱藏進度訊息,僅輸出 JSON |
擷取模式
| 模式 | 運作方式 | 最佳適用場景 |
|---|---|---|
scene | 透過 ffmpeg select='gt(scene,0.3)' 偵測場景變化 | 多數影片、內容多變 |
keyframe | 擷取 I-frame(編碼器關鍵畫格) | 具有自然關鍵畫格位置的編碼影片 |
interval | 根據影片時長與最大畫格數均勻取樣 | 固定取樣,可預測的輸出 |
若 scene 模式未偵測到場景變化,會自動降級為 interval 模式。
輸出
腳本輸出 JSON 到 stdout(或使用 -o 寫入檔案)。請參閱 references/output-format.md 取得完整結構。
{
"video": "video.mp4",
"duration": 18.076,
"resolution": {"width": 1224, "height": 1080},
"mode": "scene",
"frames": [
{"path": "/abs/path/frame_0001.jpg", "timestamp": 0.0, "timestamp_formatted": "00:00"}
],
"frame_count": 12,
"transcript": [
{"start": 0.0, "end": 2.5, "text": "大家好,歡迎..."}
],
"text": "完整轉寫內容...",
"note": "使用 Read 工具檢視畫格影像以進行視覺理解。"
}
使用 Read 工具開啟畫格影像路徑,以視覺方式檢查擷取的畫格。
參考資料
references/output-format.md-- 完整 JSON 輸出結構說明