video-understand
使用 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 寫入檔案,而非標準輸出 |
-q, --quiet | 隱藏進度訊息,僅輸出 JSON |
提取模式
| 模式 | 運作方式 | 最佳適用場景 |
|---|---|---|
scene | 透過 ffmpeg select='gt(scene,0.3)' 偵測場景變化 | 大多數影片,內容多變 |
keyframe | 提取 I 幀(編碼器關鍵幀) | 帶有自然關鍵幀分佈的編碼影片 |
interval | 根據影片長度與最大畫面數,等間隔取樣 | 固定取樣,輸出可預測 |
若 scene 模式未偵測到任何場景變化,會自動降級為 interval 模式。
輸出
腳本會輸出 JSON 至標準輸出(使用 -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 輸出結構說明