旁白影片
使用者根據分鏡表錄製一段旁白影片。AI 會編輯該段錄製內容，並將真實的產品截圖動畫化對應到旁白：每個場景開始、每次點擊、每次搜尋輸入，都會發生在語音提及該動作的那個詞上。整部影片都用程式碼（HyperFrames 組合腳本加上編輯清單）定義，因此更換新錄製、修改畫面或調整順序都只是重新執行，不需要重新編輯。
影片會配合旁白，而不是反過來。使用者決定風格；AI 負責剪輯、顯示畫面，並提出問題。
設定
- 環境中需有
ffmpeg、uv、Node 20+ 搭配npx（HyperFrames 0.8.62 透過 npx 執行），以及 Playwright 搭配 Chromium 來進行擷取。可在 macOS、Linux 和 Windows 上運作。 - Whisper 會在本地執行：Apple Silicon 使用 mlx-whisper，其他平台使用 faster-whisper。
uv run會自動安裝正確版本。 SK=<此技能目錄>/scripts。每個工具都以uv run $SK/<tool>.py執行；各工具會自行宣告其依賴。- 請在儲存庫追蹤檔案之外的資料夾（例如 git 忽略的
.logs/<video>/或暫存資料夾）中工作：
<work>/
assets/ 擷取畫面、背景、結尾卡片
storyboard.json 場景 -> storyboard/index.html
takes/<name>/ 每個錄製取樣的資料夾：探測結果、逐字稿、編輯設定、剪輯後的旁白與網路攝影機
video.py 組合腳本 -> comp/ (index.html, renders/)
NOTES.md 所有決策：剪輯原因、場景起始時間、重建指令
1. 簡報
在一次簡短的交換中確認，並提供預設值：
- 格式：發表影片、功能示範或教學（references/formats.md）。發表影片（含結尾卡片）應控制在 2:00 以內。
- 目標觀眾、影片必須傳達的三到四個重點、以及行動呼籲。
- 適合示範的範例資料：一個能讓目標觀眾一眼看懂的範例商業或搜尋案例。
- 品牌：背景圖片（或預設漸層）、結尾卡片（產品的 OG 圖片通常效果不錯）、以及視窗標題列顯示的 URL。
2. 擷取
使用基於 $SK/capture.mjs 的 Playwright 腳本，以 1440x900、2x 解析度擷取執行中產品的真實螢幕截圖：針對螢幕上打字內容的逐字幀、點擊前後的狀態、滾動內容的長截圖、以及滑鼠指標的點擊目標。如果應用程式需要登入，請傳入 login 參數，第一次執行時會開啟瀏覽器讓使用者登入一次。絕不繪製 UI 或編輯像素。使用每一張截圖前都必須仔細檢查。詳細說明與隱私保障請參閱：references/capture.md。
3. 分鏡表
撰寫 storyboard.json，每個場景一張卡片：截圖、螢幕上顯示的內容、三到六點要說的要點（簡短筆記，非完整句子）、以及大概秒數。建置並展示：
uv run $SK/storyboard.py storyboard.json storyboard/
這是一個單純的頁面，每個場景一個區段。如果平台支援發布頁面，就發布 storyboard/（index.html 加上 frames/）；否則就在本機開啟。反覆迭代直到使用者準備好開始錄製，然後提供 references/storyboard-and-recording.md 中的錄製指南。一旦使用者開始根據分鏡表錄製，未經詢問不得更改分鏡表。
4. 錄製
使用者錄製單次取樣，網路攝影機和音訊合併在一個檔案中（任何網路攝影機錄製軟體：QuickTime、Photo Booth、Windows Camera、OBS），一邊看著分鏡表一邊說話。口誤沒關係：他們可以重新開始句子並繼續。多次錄製也可以，每次錄製都會得到一個取樣資料夾。
5. 編輯錄製內容
uv run $SK/probe.py <recording> takes/<name> # take.wav, cam.mp4, take.json；檢查 still.jpg，必要時加上 --crop 重新執行
uv run $SK/transcribe.py takes/<name> # 兩次處理：一次純文字，一次寫入填充詞
uv run $SK/analyze.py takes/<name> # 候選片段：長停頓（含剪輯點）、填充詞、重新開始、雜音
uv run $SK/trace.py takes/<name> <a>:<b> # 在能量軌跡上標記每個剪輯點（--fine 使用 5 毫秒間距）
uv run $SK/splicetest.py takes/<name> c1=<a>:<cut start>,<cut end>:<b> # 試聽剪輯效果：必須聽起來像原本的句子
uv run $SK/jump.py takes/<name> <cut start>:<cut end> --slide 0.3 # 檢查網路攝影機泡泡中的剪輯跳動幅度
# 撰寫 takes/<name>/edit.json，然後：
uv run $SK/edit.py takes/<name> # edl.json；輸出編輯後的旁白及保留的填充詞：全部讀過一遍
uv run $SK/build.py takes/<name> # narration-edit.wav, cam-edit.mp4（在每個剪輯點進行交叉淡化與網路攝影機溶解）
uv run $SK/master.py takes/<name> # narration.wav 標準化至 -16 LUFS
兩種編輯層級（references/editing.md）：
- 輕度編輯（預設）：剪掉重新開始和錯誤開頭，並修剪空白片段（停頓超過約 1.1 秒保留 0.7 秒，場景切換時保留 0.9 秒）。所有「嗯」和短暫猶豫都保留。
- 減少填充詞（經要求）：也移除大部分獨立於詞組之間的「嗯」，並將超過約 0.8 秒的停頓修剪至約 0.55 秒。保留任何黏在相鄰詞上的填充詞。
- 每個剪輯點都必須在能量軌跡中處於室內背景音之上，並通過拼接測試才能納入。重新開始的剪輯點盡量放在場景變換處，這樣畫面剪輯可以掩蓋網路攝影機泡泡中的跳動。
6. 配合旁白進行組合
uv run $SK/cues.py takes/<name> # words.json，提示表（最終旁白的片段級逐字稿）
NV_SCRIPTS=$SK ASSETS=assets uv run --with numpy python video.py # 組合腳本 -> comp/；輸出每個提示的上下文
uv run $SK/render.py comp lint
uv run $SK/render.py comp snapshot 1,14.2,22.5,40.1
根據範例腳本 examples/openseo-launch/video.py 撰寫 video.py：場景起始時間和提示時間來自信號表，攝影機圖層疊在擷取畫面上，以及一個與詞彙同步的編排。範例中的提示位置只適用於其自身的編輯版本：請重新定位每個提示，並在每次編輯變更後閱讀輸出的提示表。時間規則在 references/composition.md 中；最重要的有以下幾點：
- 場景在其第一個詞彙前 0.3 秒開始，或正好在該詞彙前的停頓剪輯點開始。
- 每個動作在命名該動作的詞彙上發生：點擊在「複製」這個詞上，打字在說出搜尋詞時，縮放在說出數字時，指標在命名每個項目時。
- 第一幀是海報：顯示完整應用程式，無淡入效果。每一幀都必須有動畫。
- 每個重點一個簡短標籤。拍攝每個場景開始、點擊和標籤的快照，並在渲染前仔細檢查。
7. 渲染與驗證
uv run $SK/render.py comp render
uv run $SK/composite.py comp takes/<name> comp/renders/<video>-1080p.mp4
uv run $SK/check.py comp/renders/<video>-1080p.mp4 comp takes/<name>
uv run $SK/filmstrip.py comp/renders/<video>-1080p.mp4 comp/renders/filmstrip.png
在檢查結果顯示每一幀都有視窗、每個網路攝影機點位於幀偏移 0、音訊中位數為 0 毫秒、音量大約 -16 LUFS，且你已閱讀逐字稿並檢查過底片條（references/verification.md）之前，不得將影片交給使用者。
8. 審查與迭代
- 向使用者提供 MP4 檔案路徑、剪掉了哪些部分，以及需要注意聽的地方。
- 保持
NOTES.md更新：每個剪輯及其原因、場景起始時間、重建指令。預計會有好幾輪修改。 - 變體版本成本很低：另一個錄製取樣、輕度編輯和減少填充詞的版本、不同的場景順序。每個變體就是一個取樣資料夾或一個組合腳本；使用子代理時，請以不同的檔案名稱並行建置，避免衝突。
嚴格規則
- 僅使用真實螢幕畫面。隱藏不屬於故事內容的部分（例如橫幅、Cookie 通知）；絕對不要覆蓋像素。
- 在渲染前檢查截圖和錄製內容是否包含機密或個人資料（API 金鑰、他人的電子郵件和姓名、客戶資料、localhost URL）；在周圍加框或重新擷取，並撤銷任何在螢幕上出現的金鑰。使用者在應用程式中的姓名或電子郵件，在他們確認後可以保留。
- 使用者的錄製內容和登入工作階段保留在他們的機器上。未經要求不得發布任何內容。
常見問題：請參閱 references/gotchas.md。