learnaiwithhugo/video-editor-skills

/kallaway-edit

原始片段輸入，垂直 Reel 輸出（1080x1920，30 fps，-14 LUFS），採用 Kallaway 風格。 一切均在使用者的 Mac 上以免費工具執行。使用者通常是非技術人員： 以簡單的英文與他們溝通，每個步驟只傳送一則簡短訊息，絕不讓他們接觸程式碼。

SK = ${CLAUDE_SKILL_DIR}，此技能的資料夾（請勿寫入：更新時會取代）。 DATA = $HOME/.claude-video-editor，編輯器的專屬資料夾，會在不同更新之間保留： 使用者的設定（DATA/config.json）、編輯器的 Python 環境（DATA/venv）、音效（DATA/sfx）。 ROOT = 專案資料夾（內含 raw/、exports/）：即 DATA/config.json 中的 projectRoot，由 設定精靈（步驟 0）儲存。WORK = ROOT/work/<slug>/（每個 Reel 一個資料夾；slug 為簡短的 kebab-case 格式，例如 opus-tips）。所有路徑請加上引號：因為常包含空格。 所有腳本必須透過以下兩種之一執行，且完全依照原樣，以便找到使用者的設定： PY = VIDEO_EDITOR_DATA="$HOME/.claude-video-editor" "$HOME/.claude-video-editor/venv/bin/python" -I（設定完成後） SETUP = VIDEO_EDITOR_DATA="$HOME/.claude-video-editor" python3 -I "${CLAUDE_SKILL_DIR}/scripts/setup.py" 建置前請閱讀以下參考資料：references/style-rules.md（外觀規範，以數字表示）、references/graphics-recipes.md（口語想法如何轉為圖表）、references/gotchas.md（常見陷阱）。

嚴格規則

• 僅限免費工具。 ffmpeg、Node 22+、Python、HyperFrames（npx hyperframes@<固定版本>）、faster-whisper、 HyperFrames 的本地去背功能、隨附的 OFL 字型、HyperFrames media-use 所記錄的音效 （設定時擷取，不隨技能包覆：Pixabay 授權）以及來自 Openverse 的 CC0/CC BY 音樂或使用者自己的曲目。 無付費 API、無 HeyGen 登入、無音樂生成、無任何版權素材。
• 使用者可提供的選項： music: on|off（預設值為設定時儲存的選擇）、music: <使用者自有曲目路徑>、setup（重新執行設定精靈）。
• 絕不執行 npx hyperframes init 或 npx hyperframes skills（它們會將技能安裝到 ~/.claude/skills）。每次呼叫 HyperFrames 時：HYPERFRAMES_SKIP_SKILLS=1 HYPERFRAMES_NO_TELEMETRY=1。 務必使用 snapshot ... --describe false（否則畫面會上傳至 Gemini）。
• 絕不碰觸使用者的原始影片。 從 raw/ 中的副本進行工作。工作檔案放在 WORK； 僅最終完成的 Reel 才放入 exports/。絕不刪除使用者的檔案。
• 字幕顯示實際說出的內容，拼寫正確（「Claude」、「Opus 5.5」），數字以數字呈現。
• 圖形絕不遮蓋臉部；文字絕不低於 y=1470 或位於 y=1155 以下的右側 100 畫素。
• 沒有任何動畫會移出畫面。紅色 #C41514 是唯一的強調色。每個標題和每個區段使用一個襯線斜體單字。
• 展示你的工作：在每個步驟將編號的 PNG 放入 WORK/progress/（01-takes-picked.png，……）。
• 在宣佈完成前，以全尺寸使用 qa.py 檢查最終渲染。誠實說明哪些部分不符合標準。

工作流程

0. 設定精靈（僅第一次，約需 5-10 分鐘）

讀取 DATA/config.json。如果其中 "setupComplete": true 且其 projectRoot 資料夾存在，則執行 SETUP --check（數秒鐘，不安裝任何東西）；若回傳 READY 則前往步驟 1，若回傳 NOT READY 則修正其指出的項目（在需要新工具版本的更新之後，只需再次執行 SETUP：使用者的資料夾和選擇都會保留）。否則（第一次執行，或使用者說 "/kallaway-edit setup"）則執行精靈。 以一行簡短的文字告知使用者目前進度（「步驟 2/5：檢查您的工具」）。

1. 歡迎。 「歡迎使用 Kallaway 編輯器！讓我們開始設定。這大約需要 5-10 分鐘，而且只會發生一次。」
2. 我們在 Claude Code 中嗎？ 這需要 Claude Code（終端機應用程式、Claude 桌面應用程式中的 Code 標籤，或 IDE 擴充功能），並在本地資料夾中開啟，因為它會編輯真實的影片檔案。如果你能執行 Shell 指令並讀取本地檔案，那麼你就在其中。如果你不能（一般的對話），則說： 「開啟 Claude 桌面應用程式，按一下 Code，選擇 Local，選取一個資料夾（或建立一個名為 AI video editor 的資料夾），然後再次輸入 /kallaway-edit。」然後停止。
3. 工具檢查。 SETUP --check。以簡短表格顯示結果：工具、 是否找到、用途（ffmpeg 剪輯和混合聲音；Node.js 執行 HyperFrames；HyperFrames 將 編輯結果轉為影片；faster-whisper 辨識每個字；Python 執行輔助腳本；yt-dlp 是選用的， 用於從連結下載 Reels，且 /new-edit-style 需要它）。對於使用者必須自行安裝的項目（ffmpeg、Node.js、Python）， 給出修復名稱和貼上位置：終端機應用程式（Mac：Command + 空白鍵，輸入 Terminal）。如果它要求輸入 Mac 密碼， 使用者自己在那裡輸入，絕不在這個對話中輸入。等待他們說完成，然後再次檢查。標記為「完整安裝會安裝它」的項目無需使用者操作。
4. 檔案存放位置。 在一則訊息中詢問，每個問題附帶建議答案： -「我應該在哪裡製作您的影片？」如果目前資料夾是空的或已經是影片資料夾，建議使用目前資料夾（顯示其完整路徑），否則建議 ~/Desktop/AI video editor。 -「您的影片素材通常放在哪裡？」建議 ~/Downloads（AirDrop 會將手機片段放在那裡），或「我自己會將片段放入 raw 資料夾」。 -「背景音樂是否覆蓋您的聲音：開啟或關閉？」建議開啟（他們可以在每個影片中變更）。 然後提供資料夾：「您要我設定您的專案資料夾嗎？我會建立 raw/（您的片段）、 references/（您喜歡風格的影片）、exports/（完成的 Reels）、work/（我的工作檔案）和 archive/（舊版本）。任何已存在的內容都會保持不變。」如果回答是： SETUP --project "<資料夾>" --clips-from "<資料夾或省略>" --music on|off。 它只會建立缺少的資料夾，並將答案儲存到 DATA/config.json。
5. 安裝。「正在安裝免費編輯工具（一次性，約需 5 分鐘：語音轉文字引擎、影片渲染器、音效和語音模型）。」在背景執行 SETUP 並以簡潔的文字轉達其進度。它只會安裝到 DATA（沒有全域安裝，沒有安裝在技能資料夾中，因此更新永遠不會取消安裝），並在完成時標記設定為完成。
6. 完成。 提供 references/filming-guide.md 中的 4 個拍攝技巧（固定相機、廣角鏡頭、黑暗房間搭配暖色光打在臉上、重複一句話直到滿意），然後：「設定完成。將您的片段放入 raw/（或告訴我 中的哪些檔案）並輸入 /kallaway-edit。」如果他們已經提供了片段，則直接繼續步驟 1。

每次執行時的接收：片段是使用者命名的檔案；否則詢問，並提供 clipsFrom 中最新的影片檔案。 將它們複製到 ROOT/raw/（絕不移動或變更原始檔案）。除非使用者另有指定，否則音樂遵循已儲存的 music 選擇。

1. 找出每個鏡次（每分鐘的素材約需 1 分鐘）

PY "SK/scripts/takes.py" "WORK" "ROOT/raw/clip1.MOV" "ROOT/raw/clip2.MOV"（加上 --fast 可進行更快速、較不精確的掃描）。讀取 WORK/takes/*.takes.txt：每個嘗試及其時間範圍，重拍會標記。 如果有的話，詢問（或在片段中找尋）劇本。說：「正在聆聽您的片段並找出每句台詞的最佳鏡次。」

2. 挑選鏡次與剪輯（約需 1 分鐘）

撰寫 WORK/edl.json（格式：SK/template/examples/edl.json）：每個行一段，按劇本順序，通常是最後一個完整乾淨的鏡次。使用 {"clip","chunk"} 或 {"clip","start","end"}（以跳過區塊內的結巴；使用 transcribe.py --range a-b --model medium.en --no-vad 檢查單字時間）。目標 20-30 秒；稍微超過（到約 38 秒）比打破鉤子所做的承諾好。除非要求，否則跳過 Call to Action。然後執行 PY "SK/scripts/assemble.py" "WORK"：cut.mp4（CFR、緊貼語音、壓縮、-14 LUFS）、segments.json、words.json、words.txt。讀取 words.txt：每一行必須表示其意圖。 PY "SK/scripts/qa.py" "WORK" --takes 寫入 progress/01-takes-picked.png。 說：「這是剪輯：<台詞>。 秒。」 在建置圖形前鎖定剪輯。 如果之後重新剪輯：PY "SK/scripts/reindex.py" "WORK" "WORK/.prev/words.json" 可讓每個圖形保留在其文字上。

3. 去背（約需 3-4 分鐘，在背景執行）

PY "SK/scripts/cutout.py" "WORK"：cutout.webm（畫面匹配、邊緣清理）+ headtrack.json。 在執行期間，規劃編輯（步驟 4）。然後將一個合成在黑色背景上的影格儲存為 progress/02-cutout-check.png，以檢查光暈。

3b. 音樂（除非 music: off；約需 2-6 分鐘，在背景執行）

PY "SK/scripts/music.py" "WORK"（或 --file "<他們的歌曲>"，或 --off）。它會從 Openverse 挑選免費的 CC0/CC BY 純音樂，排除人聲，並寫入 WORK/music-credit.txt。告知使用者它挑選了什麼，如果是 CC BY 音樂，則告知說明文字需要加在字幕中。

4. 逐行規劃編輯

撰寫 WORK/plan.json（格式：SK/template/examples/plan.json）：

• shots：每個佈局開始的位置（0、"line:N" = EDL 第 N 行的第一個影格、"w:N" = 第 N 個字的開始）。對於任何可以顯示的內容使用 Stage；對於連接性/個人台詞和回報（執行時間的 16-29%）使用 Full。Stage 場景之間也使用硬剪輯。第一次剪輯約在 3.5 秒處。
• scenes：哪個圖形在何時播放（id、from、to，可選 src + vars 以多次掛載同一個場景檔案，例如重複出現的編號「首頁」圖形）。場景可以在 Full 鏡頭下執行並返回（重新訪問會在 0.6 秒內新增一項內容）。
• punch：在結尾短語上進行快節奏推近（x1.19，伴隨 riser），最多一或兩次。
• captions：fix（單字索引 -> 更正文字）、emphasis（每個區段一個襯線字）、 keep_together（單字索引配對，例如「Number」+「1,」）。 使用 graphics-recipes.md：每個想法都有一個形狀、一個標題（粗體 + 一個襯線強調，紅色框中的主張），以及在其單字上的節拍，每約 1 秒出現新內容。以每個鏡頭一行來說明規劃。

5. 建置場景（約需 15-25 分鐘）

每個場景是 WORK/scenes/<name>.html，從 SK/template/scene-starter.html 或 SK/template/examples/ 中最接近的檔案（六個真實場景）開始。工具包（template/kit/kw.css、kw.js）提供舞台外觀和動畫輔助（KW.title、blurIn、pill、pulse、draw、cam、type、strike、count、scramble；at(i) = 第 i 個字的開始）。每個動畫都必須在場景的 <!--KW:SFX [...] --> 註解中獲得其音效提示，例如 {"t": "w:24-0.02", "s": "whoosh"}，遵循 references/sound-map.md（鏡頭移動 = whoosh、pill = pop、snap/tick = click、打字 = typing、重大時刻 = impact、回報 = sparkle）。如果您有 Agent 工具且場景超過約 3 個，則將場景交給最多 2 個並行 Agent，並附上：場景的準確單字清單和時間、想法、此技能的參考資料，以及 build.py ... --project WORK/project-<字母> 以避免衝突。 PY "SK/scripts/build.py" "WORK" 寫入 WORK/project/（根目錄：點狀舞台、臉部卡片、彈出圖層、字幕軌、場景主機、音效軌，全部生成）。然後在 WORK/project 中： npx -y hyperframes@<固定版本> lint（0 錯誤）和 snapshot --at <時間> --no-end --describe false -o snaps/x，讀取 PNG，修正，重複。將每個場景的畫面儲存為 progress/03-scene-.png。

6. 渲染（約需 1 分鐘）與檢查（約需 1 分鐘）

PY "SK/scripts/render.py" "WORK" --name draft（快速），然後 PY "SK/scripts/qa.py" "WORK" "WORK/renders/draft.mp4" 並查看 qa/cuts.png（每個剪輯前後的影格）、qa/beats.png（每個字幕區塊）、qa/report.txt（剪輯與語音的時間差、音量）。 檢查：彈出圖層沒有光暈或剪輯後偏移；臉部卡片顯示頭部和肩膀（絕不裁切到臉部）；沒有字幕或圖形在臉上；字幕與文字匹配；每個台詞剪輯在語音開始前 0-80 毫秒；沒有任何內容在 Instagram 禁止區域。然後執行 PY "SK/scripts/audiomap.py" "WORK" --out progress/NN-audio-map.png：音樂比語音低 18-24 dB，音效比其局部峰值低約 10-16 dB，沒有雙重打擊；對任何標記的提示以 "db": -3 修正。 樣式匹配： PY "SK/scripts/match/fingerprint.py" score "SK/references/style-spec.json" "WORK/renders/draft.mp4" --out "WORK/progress/NN-style-match.md" 以與三個 Kallaway Reel 相同的方式測量編輯（剪輯率、每秒視覺變化、佈局比例、臉部卡片和字幕位置、字幕大小和節奏、強調色比例、音量、立體聲效），並針對每個 FAIL 項目說明如何修正。修正編輯可控制的項目；由素材（例如近距離自拍）導致的 FAIL 則作為拍攝建議提供給使用者。WORK/progress/ 中的報告是記錄（SK/references/lock-log.md 保存樣式的測量歷史；保持不變）。 修正並重新渲染（重建 + 重新渲染約需 1.5 分鐘）。

7. 交付

PY "SK/scripts/render.py" "WORK" --final -> exports/<slug>-kallaway-vN.mp4（1080x1920）加上 -720p.mp4 手機版本。在匯出檔上執行 qa.py。如果使用者在 ROOT/references/ 中儲存了自己的 Kallaway Reel（此技能不隨附任何 Reel），則加入並排比較（--ref <該 Reel> --ref-at <t> --at <t>）並儲存為 progress/NN-side-by-side.png。 說明：檔案位置、長度、逐場景內容，以及哪些部分仍然不像 Kallaway（具體且誠實）。

時間預估（在 M4 Pro Mac 上，35 秒的 Reel 來自約 8 分鐘的原始素材）

設定 5 分鐘（第一次）· 鏡次 7 分鐘（medium 模型；--fast 約 3 分鐘）· 剪輯 1 分鐘· 去背 3.5 分鐘· 音樂 2-6 分鐘（背景執行；Openverse/Freesound 可能較慢）· 場景 15-25 分鐘· 草稿渲染 50 秒· 最終渲染 70 秒· 編輯後重新渲染約 1.5 分鐘。

拍攝

將 references/filming-guide.md 提供給即將拍攝的人：固定廣角鏡頭（橫向 4K 最佳）、黑暗房間搭配暖色主光、深色上衣、頭部後方為素色背景，重複一句話直到滿意為止。