/daniel-video-annotate
輸入:一個影片檔案,以及說明每一步為何如此操作的原因(例如工單、合併請求、使用者的訊息)。輸出(位於輸入檔案旁):<name>-trimmed.mp4 與 <name>-explained.mp4。輸入檔案絕不會被修改。
解說版影片會播放錄影內容,並在每個暫停處停留一段時間,將畫面其餘部分變暗,只框出一個控制項,同時在錄影畫面下方或上方的黑色區域中顯示一句說明文字。該黑色區域會增加影片高度,因此不會遮蓋到錄影內容。
annotate.py 與此檔案位於同一目錄。在下列指令中,A 代表 python3 "${CLAUDE_CONFIG_DIR:-$HOME/.claude}/skills/daniel-video-annotate/annotate.py"。它只需要 ffmpeg、ffprobe 與 Python 標準函式庫。<work> 是暫存資料夾:如果 session 有暫存區則使用該區,否則使用 ${TMPDIR:-/tmp}/video-annotate/<name>/。
如果影片位於開發 VM 上,請先用 dvm get <remote path> <local dir> 將其複製到本機。
0. 選擇閱讀速度
停留時間是指每個說明文字在螢幕上保持可閱讀狀態的時間長度。每個暫停的停留時間為 1.5 秒加上閱讀該說明文字所需的時間(根據閱讀速度計算),且至少為 2.5 秒。使用使用者提供的速度(字/分鐘),若未提供則使用 350 字/分鐘。不要詢問。如果使用者給定固定的停留秒數,則對每個暫停都使用該數值。
完成條件:已獲得閱讀速度或固定停留時間。
1. 裁切等待時間
A trim <video> <name>-trimmed.mp4
它會找出畫面靜止超過 1.5 秒的每個片段,保留每個片段的第一秒,並裁切其餘部分。它會輸出片段數量以及裁切前後的影片長度。如果使用者希望保留等待時間,則跳過此步驟,並在後續步驟中使用原始影片作為 <trimmed>。
後續步驟中的所有時間點均為 <trimmed> 中的時間。重新裁切會使所有時間點偏移,因此在任何新的裁切之後,都需要重做步驟 2 至 6。
2. 了解故事
A sheets <trimmed> <work>/sheets
它會產生聯絡表(contact sheets),每張包含六個畫面,每秒一個畫面,並在每個畫面上標註精確時間。閱讀每一張聯絡表。閱讀工單或其他來源以了解每個步驟背後的原因。
完成條件:你能夠依序說出使用者在畫面上做了什麼、每個動作設定了什麼數值,以及哪個結果證明了錄影的重點。
3. 選擇暫停點
針對每個選擇(選取數值、按下按鈕、故意開啟頁面)暫停一次,並針對每個證明了重點的結果暫停一次。跳過不含決策的導航動作。
針對每個暫停點,找出畫面與框選區域:
A frames <trimmed> <work>/frames 23.0 23.2 23.4 23.6
它會為每個時間點產生一張全尺寸 PNG 圖片,以精確時間命名,並帶有每 100 像素一個的紅色格線,以及沿著頂端與左緣標示的像素座標。
- 選擇一個穩定的畫面。錄影中可能包含半渲染的畫面,例如點擊後有幾幀畫面是空白的面板。以 0.2 秒為間隔逐步檢查,直到控制項及其周圍完全繪製完成。
- 對於從清單中選擇,優先選擇清單已開啟且游標位於選項上的畫面。如果該畫面是半渲染的,則使用緊接其後的畫面,即欄位顯示新數值的畫面。
- 從格線標籤讀取框選區域,格式為
[x, y, width, height](單位為原始像素)。閱讀工具會縮小大圖片,因此在顯示的圖片上測量的位置是錯誤的;但標籤仍然是正確的。 - 框選說明文字所指的單一控制項,並留幾像素的邊距。暫停點可以省略
box,此時不會變暗任何區域。
完成條件:每個暫停點都有一個時間點(你已看過該時間點的畫面),以及從同一畫面讀取的框選區域。
4. 撰寫說明文字
每個暫停點一句話。說明我們做了什麼以及為什麼,或螢幕現在顯示了什麼以及為什麼。要指名具體的內容:資料列、欄位、舊值與新值。
「為什麼」的資訊來自來源。當來源未提供某個步驟的原因時,只寫出可見的內容,並在報告中將該說明標記為推測。對說明文字套用 writing-tics 技能。每句話保持在約 180 個字元以內,因為黑色區域的高度取決於最長的說明文字。
5. 渲染
寫入 <work>/spec.json,一個按時間順序排列的清單:
[
{"at": 12.0, "box": [399, 569, 180, 29], "caption": "我們將表格中項目 1 的尺寸從 M 改為 L,這會將 L 儲存到伺服器。"},
{"at": 23.6, "box": [659, 500, 192, 24], "caption": "..."}
]
at 是 <trimmed> 中的秒數。然後在每個暫停點上設定 hold:
A holds <work>/spec.json [--wpm <speed>]
它會將每個暫停點的停留時間寫入 spec 檔案,並在旁邊顯示字數。如果使用固定的停留時間,請自行在每個暫停點上設定 hold。沒有 hold 的暫停點會停留 6 秒。
A annotate <trimmed> <work>/spec.json <name>-explained.mp4 [--position top|bottom] [--clearance <lines>]
說明文字區域會放在使用者指定的位置。若無要求,則放在底部。
--position bottom是預設值。影片播放器會將其控制項繪製在底部邊緣,因此在說明文字下方會留出空白區域:--clearance行,預設為 3 行,足以避開小型嵌入播放器的控制項。--position top將說明文字區域放在錄影畫面上方,此處沒有播放器控制項。此模式不需要清除區域。
兩種位置的框選座標均以 <trimmed> 為準。
6. 檢查每個暫停點
A check <name>-explained.mp4 <work>/spec.json <work>/check
它會從每個暫停點的中間擷取一個畫面。閱讀每個畫面。框選區域必須準確落在控制項上,說明文字必須完整且未被右緣截斷,畫面必須是你選擇的穩定畫面。修正 spec 檔案並重新渲染,直到每個暫停點都通過檢查。
7. 報告
提供解說版影片的路徑、大小與長度,然後依序列出每個說明文字及其框選的控制項。標註哪些說明文字是推測的。說明你已檢查每個暫停點的一個畫面,但未觀看完整播放。
限制
- 輸出不含音訊。如果輸入含有語音軌道,請告知使用者。
- 幀率為輸入的平均幀率(四捨五入),並限制在 5 至 30 幀/秒之間。
trim僅裁切完全靜止的畫面。旋轉動畫、進度列、閃爍的游標或時鐘會使畫面保持變動,因此這些等待時間會保留。被一個小變動中斷的等待時間會保留為數個一秒片段。trim僅裁切靜止片段內的畫面,並保留每次變動的第一個畫面。小於--noise容忍度(預設值 0.003)的變動(例如一個小字元)會被視為靜止而可能被裁切。步驟 2 是檢查點:每個動作都必須出現在聯絡表中。如果缺少某個動作,請將--noise降低至 0.001。
錯誤
| 你看到的內容 | 原因 | 修正方式 |
|---|---|---|
this ffmpeg build has no drawtext filter | ffmpeg 未包含 libfreetype 建置 | 安裝完整建置版本,例如 brew install ffmpeg |
no font file found | 找不到任何已知的 macOS 或 Linux 字型路徑 | 在 sheets、frames 與 annotate 指令中傳入 --font /path/to/font.ttf |
Unrecognized option 'fps_mode' | ffmpeg 版本低於 5.1 | 升級 ffmpeg |
no still stretches found, nothing written | 畫面從未靜止超過 1.5 秒 | 使用原始影片作為 <trimmed>,或降低 --min-freeze 數值 |
| 裁切後的影片仍然感覺很慢 | 保留了動態等待時間,或每個靜止片段保留的一秒累積過多 | 將 --keep 降低至 0.5 |
| 裁切後的影片跳太快無法跟上 | 對於此錄影,每個畫面保留一秒太短 | 將 --keep 提高至 2,並將 --min-freeze 提高至 3 |
pause N at Ts is past the end of the video | 時間點來自原始影片而非 <trimmed> | 重新從 <trimmed> 的 sheets 與 frames 讀取時間點 |
pause N box ... is outside the frame,或 check 中框選區域未對準控制項 | 框選區域是從縮小的圖片上測量的 | 從 frames PNG 的格線標籤讀取座標 |
| 說明文字被右緣截斷 | 字型比腳本假設的寬度還大 | 在 annotate 中傳入 --wrap 80 或更低的數值 |
| 播放器的控制項遮蓋了說明文字 | 說明文字下方的空間小於控制項高度 | 將 --clearance 提高至 5,或使用 --position top |
pause N would sit at ..., past the end | check 指令被給予了裁切後的影片 | 給予它解說版影片 |
任何其他 ffmpeg failed | 未知 | 執行 A selftest。它會裁切並標註一個產生的片段,若測試通過則表示 ffmpeg 正常,問題出在輸入影片或 spec 檔案 |
dvm get --help 因 scp 錯誤而失敗 | dvm get 將所有參數傳遞給 scp | 執行 dvm help |
macOS 沒有 timeout 指令。一個一分鐘的 720p 影片只需幾秒即可渲染完成,因此可以直接執行指令。