影片分析

影片分析 — 看到的畫面，聽到的內容

你沒有直接的影片或音訊輸入。你讀取的是從影片中提取的影像以及其音訊的逐字稿。以下所有步驟都是為了將一部影片轉換成這兩種東西，然後告訴你如何在不誇大其詞的情況下讀取它們。

資料存放位置 — 使用者的嚴格規則

所有提取的資料都放在影片所在資料夾中的一個工作資料夾裡： <影片所在的資料夾>\<影片名稱>.analysis\ — 絕不放在暫存區、臨時目錄或專案中。 使用者在該影片的工作完成後會刪除它，以回收磁碟空間。 切勿自行刪除。 如果被要求清理，請使用 trash 技能處理該資料夾（丟到資源回收筒，絕不使用 rm）。你的書面分析（成品）應放在專案所需的位置，而不是 .analysis 資料夾內，這樣刪除該資料夾時不會遺失任何有價值的內容。

1. 工具（每台機器執行一次）

python ~/.claude/skills/video-analysis/scripts/setup_tools.py --check   # 驗證
python ~/.claude/skills/video-analysis/scripts/setup_tools.py           # 安裝缺少的套件

使用 pip --user 安裝：imageio-ffmpeg（內建 ffmpeg 二進位檔 — 無需系統 ffmpeg、無需管理員權限、無需 winget/choco）、Pillow、numpy、faster-whisper，並快取 Whisper small 模型（唯一一次需要網路連線；之後完全離線）。Exit 0 表示 READY。

自我測試（合成影片，9 項檢查，--full 會加入 Whisper）： python ~/.claude/skills/video-analysis/scripts/selftest.py

2. 提取

python ~/.claude/skills/video-analysis/scripts/extract_video.py "<影片路徑>" --language fr

對於長度超過幾分鐘的影片，請在背景執行：在 CPU 上，轉錄速度約為即時的 5 倍（15 分鐘的影片約需 3 分鐘）。選項：--interval 5（影格之間的間隔秒數；對於快速變動的畫面使用 2，對於談話性人物使用 10-15）、--model small（medium 更好，但慢 3 倍）、--skip-frames、--skip-transcript、--at HH:MM:SS[.mmm]（可重複，用於在精確時間點取得全解析度影格 — 在第 3d 步驟中使用）。

在 <video>.analysis\ 中產生：frames\（每個間隔的影格）、sheets\（3x3 聯絡表，每個影像以黃色標記 mm:ss 時間戳）、keyframes.txt + keysheets\（僅有明顯變化的影格 — 即投影片/畫面變更）、audio.wav、transcript.txt（[mm:ss] 文字）+ transcript.json、at\、manifest.json。重新執行會恢復並跳過已完成的階段；如果參數已變更或影片不同，則會拒絕（exit 3） 而不是混合輸出。Exit 1 = 處理失敗，2 = 輸入錯誤。

3. 讀取 — 依此順序

a. 先讀取完整的逐字稿（transcript.txt）。在課程和示範中，關鍵內容（數字、規則、例外情況、真正的方法）通常存在於語音中，而非螢幕上。 b. 讀取關鍵影格聯絡表（keysheets\），以一次查看每個不同的投影片/畫面。 c. 讀取聯絡表（sheets\）— 所有表格，按順序，以追蹤關鍵影格之間的變化（游標、繪圖、圖表更新）。 d. 放大語音所指的位置：當說話者說「這裡」、「這支蠟燭」、「看這個…」時，使用與首次執行相同的選項重新執行帶有 --at <時間戳> 的命令（否則清單檢查會拒絕並顯示 exit 3），然後讀取該全解析度影格。聯絡表每個儲存格為 640 px — 對於圖表標籤或小文字來說太小了。 e. 撰寫分析報告（步驟 4）。

4. 報告 — 區分三種資訊

對於每個段落，請引用時間戳，並將每個陳述標記為以下之一：

• ON SCREEN（螢幕上） — 影像實際顯示的內容（投影片文字、圖表、註解、UI）。
• SAID（所說） — 語音陳述的內容（直接引用或貼近原文的改寫，附上 [mm:ss]）。
• INFERENCE（推論） — 你連結兩者的詮釋。切勿將其呈現為看見或聽見的內容。

始終包含：

• 書面內容與口說內容之間的落差（例如，投影片上寫的是一回事，但語音補充了真正重要的規則，或與之矛盾）；
• 僅顯示一次的內容（單一示範範例是說明，而非證據）；
• 限制：影格每 N 秒取樣一次，可能會錯過短暫的事件；影格的時間戳是其索引 × 間隔，因此是近似值（± 半個間隔，對於可變影格率的錄影差異更大）；關鍵影格去重可能會隱藏細微的編輯；Whisper 可能拼錯名稱和專業術語（請與影像核對）；無法可靠地讀取語調、情緒、音樂、說話者身份或動作。

5. 後續處理

告知使用者工作資料夾的路徑及其大小（在提取結束時顯示）。保留該資料夾，直到他們表示該影片的工作已完成；然後使用 trash 技能將其丟棄。

已知問題（腳本已處理）

• faster_whisper 的 model.transcribe("<path>") 在搭配新版的 PyAV 時會引發 TypeError: open() got an unexpected keyword argument 'metadata_errors'。腳本使用 ffmpeg 提取 16 kHz 單聲道 PCM16 WAV，並改傳遞 float32 陣列。
• imageio-ffmpeg 附帶 ffmpeg，但不含 ffprobe：持續時間和音訊存在與否是從 ffmpeg 自身的橫幅讀取。
• 透過 select='gt(scene,N)' + showinfo 進場偵測在 -loglevel error 下不會輸出任何內容；關鍵影格改用縮圖差異。