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 寫入檔案,而非輸出到 stdout |
-q, --quiet | 隱藏進度訊息,僅輸出 JSON |
提取模式
| 模式 | 運作方式 | 最佳用途 |
|---|---|---|
scene | 透過 ffmpeg select='gt(scene,0.3)' 檢測場景變化 | 大多數影片,內容多變 |
keyframe | 提取 I 幀(編碼器的關鍵幀) | 具有自然關鍵幀位置的編碼影片 |
interval | 根據影片時長與最大幀數,均勻間隔抽取畫面 | 固定取樣,輸出可預測 |
若 scene 模式未偵測到場景變化,會自動降級為 interval 模式。
輸出
腳本會輸出 JSON 至 stdout(或使用 -o 輸出至檔案)。完整的 schema 請參閱 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": "Hello and welcome..."}
],
"text": "Full transcript...",
"note": "使用 Read 工具檢視幀圖片以進行視覺理解。"
}
使用 Read 工具讀取幀圖片的檔案路徑,即可視覺檢視提取的畫面。
參考資料
references/output-format.md-- 完整的 JSON 輸出 schema 文件