weeeha/video-notes

影片筆記 (Video Notes)

使用者以螢幕錄影方式記錄反饋，一邊操作一邊口頭說明：一次錄完，長度數分鐘，當游標遲緩時經常重複同一重點。預期產出是一份待辦清單，讓其他工作階段無需觀看影片即可執行。Whisper 與 ffmpeg 在本機執行；不會將影片或音訊傳送至任何雲端語音或視覺 API。

步驟

1. 執行輔助腳本（與此檔案位於同一資料夾）。

   python3 "<此技能所在資料夾>/video-notes.py" "<影片檔路徑>"
   

   若 <影片檔>.srt 已存在於同目錄則直接使用，否則以 CPU 執行 whisper --model base.en（在 Apple Silicon 筆電上約每 5 分鐘影片需 2.5 分鐘處理）。輸出存放於 <主檔名>.notes/：transcript.md（每合併片段一行，附圖片名稱）與 1600px 寬的靜態圖片。當 <主檔名>.notes/ 比影片檔更新時會直接沿用；--force 強制重建，--model turbo 處理逐字稿錯亂的情況，--every 10 用於無旁白的示範，--sheet 產生 2×2 縮圖索引，--max-row 5 在說話與畫面變動快速時增加影格數量（每行最長 8 秒，每行一張影格），--max-frames 40 為預設值。
2. 先閱讀 transcript.md，再查看影格。 若使用 --sheet，先瀏覽 sheet_NN.jpg（每張索引包含四個影格，由左至右、上至下依序排列，因此編號 01 的索引包含影格 1 至 4，其左上角為最早影格），然後針對每一行中口頭指示指向畫面的情況（例如「這個區域」「這裡」「這兩個圖示」）或必須閱讀的文字，再查看單張影格。索引用於定位；只有單張影格才能作為標籤或尺寸的證據。
3. 在影片檔旁寫入 <主檔名>.notes.md，使用絕對路徑，無論工作目錄為何。格式如下：

   # <影片名稱> · <錄製日期> · <長度> · <畫面中可見的應用程式或網址>
   
   ## 待辦清單
   ### <畫面區域名稱，依畫面上顯示的名稱命名：左側欄、標題列、設定面板>
   1. [mm:ss] <一句話說明必須修正的項目>。口述：「<簡短引述>」。影格：frame_mmss.jpg
   2. ...
   
   ## 暫緩
   <標記為「之後再說」「總有一天」「現在不做」的項目，使用相同格式>
   
   ## 待確認
   <每個需要使用者回答的項目佔一行>
   

   編號貫穿整個清單，以便使用者回覆「第 3 和第 7 項」。區塊依照被提及的順序排列。重複的筆記只記錄一次，若重複為重點則附加「口述 3 次」。
4. 回覆檔案路徑、區塊標題及項目數量，以及前三項內容。除非「待確認」區塊有內容，否則無需提問。
5. 當產生畫面的程式碼儲存庫已開啟時，新增 ## 對應程式碼：項目編號對應檔案路徑，透過搜尋影格中的元件名稱與標籤找到。若無程式碼儲存庫則跳過此區塊；絕不猜測路徑。

規則

• 靜態圖片中無法辨識的文字必須重新截取，不可推測：使用 --width 2400，或使用 ffmpeg 裁剪該區域。
• .notes/ 資料夾與 .notes.md 檔案須與影片檔存放在同一目錄。在程式碼儲存庫中，該資料夾必須被忽略（git/info/exclude），以免大型錄影檔被提交至 git。
• 競爭對手或產品示範：步驟相同，但清單改為「他們做了什麼」而非「修正什麼」。
• 轉錄使用本機 Whisper 模型，存放於 ~/.cache/whisper。不使用任何雲端語音 API 或視覺 API；工作階段的模型僅讀取靜態圖片。

完成檢查

• 已產生 transcript.md，且在撰寫任何項目前已閱讀所有影格
• 已寫入 <主檔名>.notes.md：全清單統一編號、區塊依造訪順序排列、每個項目皆附時間戳與影格名稱
• 重複項目已合併，「暫緩」與「待確認」已與待辦清單分開
• 未將任何影片或音訊傳送出本機