剪輯建立工具
從三個部分建立短影片：一個呈現畫面的 HTML 頁面（場景）、一份 clip.json 中的劇本行列表（提示），以及一個逐格擷取頁面並編碼為 MP4 的命令列工具。
場景頁面定義了 draw(s)，它會僅根據時間 s 計算頁面在該秒的狀態。擷取工具會為每個影格（第 0 秒，然後是 1/30 秒，依此類推）呼叫它並截取螢幕截圖。因此，輸出不依賴於機器速度，任何影格都可以獨立渲染以供審閱，並且可以使用 --from 和 --to 重新擷取剪輯的某個部分。
CLI 是此技能目錄中的 scripts/clip.mjs。在本文檔中，clip 表示 node "<技能目錄>/scripts/clip.mjs"，其中 <技能目錄> 是包含此檔案的目錄的絕對路徑（Claude Code 會在此處替換該路徑：${CLAUDE_SKILL_DIR}。在其他代理中，請使用讀取此檔案的目錄）。從包含 clip.json 的剪輯專案目錄執行命令。clip help 會列出每個命令和選項。
需求
Node 20 或更高版本、ffmpeg 以及帶有 Chromium 的 Playwright。clip doctor 會檢查它們並列印任何缺失項目的安裝命令。在建立剪輯的目錄中安裝 Playwright（npm install --save-dev playwright，然後執行 npx playwright install chromium），而不是在此技能目錄中。旁白和生成的音樂是可選的。它們是唯一需要花錢或需要 API 金鑰的步驟。
沙盒化命令（Codex 中的預設行為）：clip stills、clip capture 和 clip serve 會在 127.0.0.1 上啟動一個 HTTP 伺服器，前兩個還會啟動 Chromium。命令沙盒會同時封鎖兩者。然後該命令會以狀態碼 1 退出，並發送一條標明沙盒名稱的訊息。請求批准在沙盒外部執行這三個命令，並說明原因。請勿替換其他擷取方法。其他命令既不需要伺服器也不需要瀏覽器，可以在沙盒內執行；tts --generate 和 music --generate 還需要網路存取。
簡報
在開始之前確定以下事項。僅詢問缺失的資訊。對於使用者未指定的任何內容，請使用預設值並用一行說明。
- 目的和觀眾：宣傳、產品示範、員工教學、課程。這決定了節奏。宣傳片節奏快；培訓片則留有時間跟隨每個步驟。
- 長度。預設值：宣傳或示範為 20 到 45 秒，培訓為 60 到 120 秒。
- 目的地，這決定了影格大小。預設值：
wide1920×1080，加上用於社群動態的tall1080×1350。請參閱references/delivery.md。 - 視覺方法：全新圖形或應用程式畫面。對於應用程式：哪些畫面，以及其原始碼或設計系統是否可作為顏色、字體和間距的來源。
- 聲音。預設值：靜音附帶字幕。這是免費的，而且大多數動態影片播放時是靜音的。旁白和音樂均為選擇性加入。
- 劇本。如果使用者有劇本就使用他們的。否則草擬一份並在建立場景之前獲得他們的批准。
工作流程
- 檢查工具：
clip doctor。 - 建立專案：
clip init <目錄> --template graphics或--template app-ui。這會寫入clip.json、一個包含可運作範例的scene/目錄以及audio/。兩個範本無需修改即可渲染。 - 在
clip.json中編寫提示，每個節拍一條。節拍是剪輯中具有一行台詞和一個可視狀態的片段。先寫劇本：場景會根據它來計時，而錄音後的任何措辭更改都將是另一次付費請求。references/narration.md涵蓋了針對語音的寫作。 - 建立場景：編輯
scene/index.html和scene/scene.js。首先閱讀references/scenes.md。它列出了使場景保持確定性的限制條件：沒有Math.random()、沒有時鐘或計時器、沒有 CSS 動畫、所有狀態都從s計算得出。對於應用程式畫面，還要閱讀references/app-ui.md。 - 審閱靜態畫面：
clip stills會將選定秒數的影格和一張預覽索引圖寫入out/review/。將預覽索引圖作為圖像打開並檢查。檢查文字是否清晰可讀、沒有重疊，以及每個節拍在其字幕顯示期間是否在螢幕上。對每個影格大小重複此操作（--frame tall）。在此步驟進行大部分迭代：靜態畫面速度快且無成本。clip serve為使用者提供即時預覽。 - 擷取草稿：
clip capture --draft以三分之二大小渲染，以檢查動態和節奏。將檔案路徑提供給使用者，並請他們觀看。 - 如果要求，添加聲音。旁白：
references/narration.md。音樂和混音：references/sound.md。首先在不帶旗標的情況下執行clip tts；它會列出計劃中的請求和字元數。獲得使用者的批准，然後執行clip tts --generate。在任何新錄音之後，執行clip timing，它會放置提示和字幕，並在設定後將場景拉伸以匹配旁白。然後再次審閱靜態畫面。 - 擷取最終版：對每個影格執行
clip capture --final，如果有聲音則執行clip mix，然後執行clip web <檔案>以獲得較小的上傳副本。 - 驗證和報告：審閱最終版的靜態畫面、閱讀混音報告中的響度，並執行
clip scan out。報告產生了什麼、檔案路徑、檢查了什麼以及未檢查什麼。
無聲剪輯會跳過步驟 7。其字幕來自每個提示的 at 和 until 值，並且 clip timing 會將它們寫入頁面。
安全規則
剪輯工作涉及使用者的金錢、API 金鑰和已發布的身份。
- 付費請求需要使用者明確批准。提供者會對旁白和音樂收取費用。CLI 在沒有
--generate的情況下不會發送任何內容；僅在使用者批准該特定錄製後才傳遞該旗標。對一次錄製的批准不涵蓋下一次。在詢問時顯示空運行輸出（行數和字元數）。如果請求中斷，其收據會保持attempted狀態。在使用者檢查提供者的使用記錄之前不要重試，因為該請求可能已被計費。 - API 金鑰僅來自環境。CLI 讀取
ELEVENLABS_API_KEY或OPENAI_API_KEY，不讀取其他來源。從使用者的秘密儲存庫中為單個命令內聯傳遞金鑰（references/keys-and-paid-calls.md中有相應的命令）。不要要求使用者將金鑰貼上到對話中，不要列印金鑰（使用echo、env、cat），也不要將金鑰寫入檔案。要確認金鑰已設定，請檢查其長度；clip doctor會執行此操作。 - 傳遞檔案；不要發布。發布或上傳剪輯是用戶的操作，除非他們要求該特定操作。
- 僅使用使用者有權使用的素材。音樂、字體、標誌和影片片段需要許可證或使用者的所有權。僅顯示使用者擁有或獲得許可顯示的應用程式，並且不要將模擬圖設計成其他公司的產品。兩個提供者的條款都涵蓋商業用途和生成聲音的揭露；在發布帶有旁白的剪輯之前，向使用者指明這些條款。
- 將私人資料遠離圖片和檔案。在應用程式畫面中使用虛構的名稱和數字。呈現為真實的數字和引言必須是真實的，並且範例必須可識別為範例。在共享任何內容之前，對其執行
clip scan。它會檢查 API 金鑰、本地使用者名稱和路徑、電子郵件地址、使用者的私有詞彙列表以及嵌入在多媒體檔案中的元數據。
編輯指南
- 每個剪輯只涵蓋一個主題。拆分涵蓋兩個主題的劇本。
- 在前幾秒內開始旁白或第一個字幕。
- 每個節拍使用一個提示，並在台詞朗讀期間將節拍的畫面保持在螢幕上。
- 始終包含字幕。大多數動態影片播放時是靜音的。
- 以手機尺寸審閱直立影格。出於這個原因，直立影格中的場景單位更大。
- 使用動態來標記狀態變化或引導注意力。避免持續移動。
- 將結束卡至少停留 2.5 秒。
- 對於培訓：展示操作，然後展示其結果，節奏要讓觀眾能夠邊看邊做。在螢幕上為步驟編號，並在開始時說明觀眾完成後將能夠做什麼。
命令
| 命令 | 功能 |
|---|---|
clip doctor | 檢查 Node、ffmpeg 和 Playwright，並報告哪些金鑰已設定（僅長度） |
clip init <目錄> --template graphics|app-ui | 從可運作範例建立專案 |
clip serve | 提供即時預覽；URL 中的 ?t=5 會停留在第 5 秒 |
clip stills [--at 2,5,9] [--frame tall] [--final] | 渲染審閱用的靜態畫面和預覽索引圖 |
clip capture [--frame wide] [--draft] [--final] [--from s --to s] [--web] | 渲染每個影格並編碼為 MP4 |
clip capture --mode clock --url ... --seconds N [--actions file.mjs] | 擷取正在執行的應用程式（實驗性；請參閱 references/app-ui.md） |
clip tts [--generate] | 列出仍需錄製的旁白；使用 --generate 則進行錄製（付費） |
clip music [--generate] | 同上，但用於生成的配樂（付費） |
clip timing | 計算提示和字幕時間；寫入 scene/timing.json 和一個 .srt 檔案 |
clip mix | 以標準響度建立音軌，並將其混入每個已擷取的影片中 |
clip web <影片> | 寫入一個較小的上傳用副本 |
clip scan <目錄> [--terms-file words.txt] | 在檔案共享前報告私人資料 |
clip strip <媒體檔案> | 寫入一個移除所有嵌入元資料的副本 |
輸出到 out/ 目錄，命名為 <名稱>-<版本>-<影格>.mp4，並根據情況添加後綴 -draft、-part（使用 --from/--to 擷取的範圍）、-sound 和 -web。若要將舊版本與新版本並存，請增加 clip.json 中的 "take" 值（a, b, c, ...）。
參考檔案
閱讀當前步驟所需的檔案。
| 檔案 | 何時閱讀 |
|---|---|
references/scenes.md | 編寫或更改場景時：頁面契約、輔助庫、單位、直立影格、字體，以及保持擷取確定性的限制條件 |
references/app-ui.md | 剪輯顯示應用程式畫面時：從設計令牌重建、指標、打字、相機移動，以及擷取正在執行的應用程式 |
references/narration.md | 編寫台詞、選擇提供者和聲音、發音、重新錄製一行、使場景適配旁白、字幕 |
references/sound.md | 音樂和混音：音量、側鏈壓縮、使音軌適配剪輯、響度、修正混音 |
references/keys-and-paid-calls.md | 在任何付費請求之前：安全地傳遞金鑰、發送了什麼、收據、中斷的請求 |
references/project-file.md | 關於 clip.json 的任何欄位 |
references/delivery.md | 影格大小、最終渲染、交付前的檢查、要報告的內容 |
references/cookbook.md | 請求符合常見工作時。十二個已實作的配方：無聲剪輯、從設計令牌建立的應用程式畫面、多種長寬比、逐步培訓剪輯、來自 JSON 的長條圖、每個提供者的旁白、重新錄製一行、背景音樂、自訂字體和標誌、正在執行的應用程式、最終檢查。還有 draw() 程式碼片段 |
故障排除
| 症狀 | 可能的原因 |
|---|---|
"這看起來像是一個命令沙盒"、listen EPERM 或瀏覽器無法啟動 | 代理的沙盒正在封鎖 HTTP 伺服器或瀏覽器。在使用者批准的情況下，在沙盒外部執行 stills、capture 和 serve |
| "頁面從未設定 window.ready" | 場景中的腳本錯誤（訊息會列出頁面的錯誤），或者頁面未呼叫工具包的 clip() |
| 同一場景的兩次擷取結果不同 | 場景中的某些狀態並非從 s 計算得出：Math.random()、Date、CSS 動畫或過渡、<video>、計時器 |
| 文字在另一台機器上以不同字體渲染 | 場景使用了系統字體。將字體檔案放在場景目錄中（references/scenes.md） |
| 畫面領先或落後於旁白 | 新錄音後未執行 clip timing，或者影片在此之前已被擷取。clip mix 在第一種情況下拒絕執行，並在第二種情況下發出警告 |
tts 列表中出現 attempted | 先前的請求未完成。在使用 --retry-attempted 之前檢查提供者的使用記錄 |
| 音樂音量在詞語之間起伏不定 | 設定 "mix": { "master": "limit" }（references/sound.md） |