Communitygithub.com

daniel-video-annotate

將螢幕錄影轉換為解說版本:裁切靜止等待、在每個關鍵動作暫停、框選控制項並加入文字說明。當使用者呼叫 /daniel-video-annotate 或要求標註/解說影片時使用。

daniel-video-annotate 是什麼?

此技能可將螢幕錄影轉換為具有解說文字與視覺標註的影片。它會先裁切冗長的靜止片段,縮短影片總長度,然後在每個關鍵操作(如點擊按鈕、選擇數值)與展示結果處插入暫停。每個暫停畫面會模糊周圍、框出相關控制項,並在影片下方或上方顯示一句說明文字。 技能支援 Claude Code、Cursor 等基於命令列的 AI 代理工具,依賴 ffmpeg、ffprobe 與 Python 標準函式庫,無需額外套件。其工作流程包含:選擇閱讀速度、裁切等待時間、分析影片內容、選擇暫停點、撰寫說明文字、渲染輸出影片,以及自動檢查每個暫停畫面是否正確。 此外,技能會自動調整說明文字停留時間以確保可讀性,支援開發者根據需求調整暫停位置、框選範圍、文字位置與邊距。最終產出為兩份檔案:已裁切靜止片段的版本與完整解說版本,原始檔案不會被修改。

相容平台✓Claude Code~Codex CLI✓Cursor
npx skills add https://github.com/dancodes/skills-agents/tree/HEAD/skills/daniel-video-annotate

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

/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 filterffmpeg 未包含 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 endcheck 指令被給予了裁切後的影片給予它解說版影片
任何其他 ffmpeg failed未知執行 A selftest。它會裁切並標註一個產生的片段,若測試通過則表示 ffmpeg 正常,問題出在輸入影片或 spec 檔案
dvm get --help 因 scp 錯誤而失敗dvm get 將所有參數傳遞給 scp執行 dvm help

macOS 沒有 timeout 指令。一個一分鐘的 720p 影片只需幾秒即可渲染完成,因此可以直接執行指令。

相關技能