SergeoDev01/talking-head-reels

Talking-head reels

你將一段人物對著鏡頭說話的錄影，轉換為一則完成的直式短影音（MP4）。整體風格是編輯型且節奏明快：說話者是影片的主軸，每 2-4 秒畫面就會變化一次——放大鏡頭、大字卡、B-roll 插入、分割畫面——每一次變化都依據當下說話的內容來驅動。

整個機械流程已腳本化：剪除停頓、音訊後製、遮罩處理，以及一個根據編輯決策列表（EDL）直接繪製每一幀的渲染器。你的工作是編輯部分：理解談話內容、決定每個節拍應有的視覺效果、尋找或生成適合的素材、撰寫 EDL、檢查預覽圖，並與使用者進行修訂迭代。

需求

macOS（原生渲染目標）— Python 3.9+ 搭配 numpy 和 faster-whisper、ffmpeg 含 libass（Homebrew ffmpeg 或 imageio-ffmpeg）。可選：Xcode 命令列工具（Apple Vision 遮罩）。

Windows 10/11 渲染主機：渲染引擎是跨平台的。Python 3.9+ 搭配 numpy 和 faster-whisper，以及一個包含 libass 的 ffmpeg 版本（gyan.dev 的「完整」版本）即可——然後使用 assets/fonts/win/ 中附帶的免費替代字型（Playfair Display 400/700/italic + Inter Medium，OFL 授權）：

1. 設定一次使用者環境變數 REEL_FONT_FILES = 四個 .ttf 檔案路徑，以分號分隔。引擎會透過自己的 REEL_FONT_FILES 掛鉤（textass.py）讀取它們，並將字型檔萃取到 libass 資料夾中；
2. 在每個 EDL 中放入內建的 EDL 字型覆寫設定： "fonts": {"anton": "Anton-Regular", "serif": "PlayfairDisplay-Bold", "didot": "PlayfairDisplay-Regular", "sub": "Inter-Medium"} （reel_plan.py 中的預設映射保持不變 — macOS 的 EDL 無需覆寫）；
3. Windows 上沒有 Apple Vision 的去背遮罩：跳過那些節拍。 python scripts/check_setup.py 會回報 Windows 適用的檢查結果。

不包含素材來源：B-roll 來自使用者提供的素材以及免費圖庫（Pixabay / thesvg MCP 連接器、Wikimedia Commons）；付費生成附錄（Higgsfield / Seedance）僅限於明確要求時使用。

你交付的內容

• PROJECT/render/<name>_vN.mp4 — 1080x1920，H.264，AAC 320 kbps，人聲約 -14 LUFS。
• PROJECT/edl.json（以及每次修訂的 edl_vN.json 副本）— 整個編輯以資料形式呈現；重新渲染它總是會得到相同的影片。
• 供審查用的 QA 預覽圖（PROJECT/qa/.../sheet.jpg）。

步驟 0 — 設定與輸入

執行 python3 scripts/check_setup.py（此檔案中的路徑相對於 skill 資料夾）並修正它回報的問題。所有腳本使用同一個 Python；使用虛擬環境搭配 numpy faster-whisper imageio-ffmpeg 是最簡單的方式。ffmpeg 必須包含 libass（所有文字都透過它繪製）— 檢查腳本會顯示它找到了哪個二進位檔。

然後確保你了解以下資訊（只詢問缺少的部分 — 一則簡短訊息即可）：

1. 錄影檔案（路徑）。理想是 4K 橫向或 1080x1920 直式，說話者大致居中。
2. 語言，以及如果有腳本的話（有助於找出填充詞和錯誤轉錄）。
3. 色彩分級：已經過分級的檔案、一個 .cube LUT，或「使用相機原始色彩」。
4. 結尾的行動呼籲（例如「留言 WORD，我會傳送連結」）。
5. B-roll 的來源：他們自己的素材（預設）、免費圖庫與檔案庫（Pixabay MCP、Wikimedia Commons）、透過 thesvg MCP 取得的標誌/圖示（備用方案為 Commons 的 PNG 渲染）。詢問他們擁有哪些權利。只有當他們明確要求時，才使用付費 AI 生成（Higgsfield / Seedance）。
6. 專案資料夾的存放位置（預設：放在影片旁邊，名為 <name>_reel/）。

步驟 1 — 準備與分析（腳本化）

python3 scripts/prepare_project.py VIDEO.mov [--graded GRADED.mov | --lut grade.cube] [--project DIR]
python3 scripts/transcribe.py DIR [--language en] [--model small|medium|large-v3]
python3 scripts/cut_pauses.py DIR [--remove 2.40-2.72 ...]
python3 scripts/master_audio.py DIR
python3 scripts/presenter_mattes.py DIR        # 需要 swiftc；若不可用則跳過

cut_pauses.py 會印出每個保留的片段及其文字內容。對照轉錄稿閱讀它：使用 --remove 開始-結束（原始秒數）移除錯誤開頭、重複錄製和填充詞，然後再次執行。向使用者回報移除了多少內容（例如「81.5 秒 → 73.4 秒」）。後續步驟全部使用節目時間線（analysis/program_words.json）。

步驟 2 — 規劃編輯（你的判斷）

閱讀 references/style-guide.md（外觀與規則）和 references/edit-planning.md（如何將談話轉換為節拍），然後撰寫一個節拍表：每個節拍一行，包含節目時間、說話內容、畫面上顯示的內容（主持人全景/特寫、插入類型、佈局）、文字處理方式以及素材構思。在尋找素材前先向使用者展示——現在修改成本低，之後修改成本高。

步驟 3 — 素材

遵循 references/broll-sourcing.md：尋找什麼、來源何處、授權方式，以及經過測試的免費素材擷取方法（Pixabay MCP 搜尋 + URL 驗證、Wikimedia Commons API + curl UA/重試 + SHA-1 校驗、thesvg MCP 用於標誌、ffmpeg 轉碼）。付費生成（透過 Higgsfield 的 Seedance）位於附錄中——僅在使用者明確要求 AI 生成畫面並同意成本時使用。所有素材放在 PROJECT/broll/ 中，標誌放在 PROJECT/logos/ 中。使用 scripts/clip_sheet.py 審查候選素材。如果使用者已經有剪輯或插入素材，直接使用——不要重新尋找已有的內容。

步驟 4 — EDL 與驗證

根據 references/edl-schema.md 撰寫 PROJECT/edl.json（完整的實作範例——此風格所依據的短影音——在 assets/examples/example_edl.json 中）。然後：

python3 scripts/validate_edl.py DIR/edl.json

修正每個錯誤；閱讀每個警告，並修正它或有意地接受它。

步驟 5 — 預覽圖，然後渲染

python3 scripts/render_reel.py DIR/edl.json --stills 0.6 2.4 4.8 ... --out-dir DIR/qa/stills_v1
python3 scripts/render_reel.py DIR/edl.json --out DIR/render/<name>_v1.mp4

預覽圖只需幾秒：選取每個節拍內的某個時刻，加上每個轉場的中間點，然後根據 references/style-guide.md 中的檢查清單檢查連續圖（無空白邊緣、文字可讀且在畫面內、無物體遮住眼睛、文字位於中央堆疊、色彩處理正確）。修正 EDL 並重新檢查直到無誤。然後渲染完整的短影音（在較新的 Mac 上需要幾分鐘；請參閱 references/renderer.md）並將路徑以及渲染器輸出的數據（大小、幀率、時長、音量）提供給使用者。

步驟 6 — 修訂迭代（使用者的工作方式）

• 使用者逐條提供意見，通常是附帶幾個字的螢幕截圖。為它們編號（1, 2, 3...），簡短確認，並在他們表示完成（「開始」、「進行」、「就這樣」）之前不要更改任何內容。然後一次套用所有修改。
• 每次迭代都是一個新版本：在編輯前將 edl.json 複製為 edl_vN.json，渲染為 <name>_vN.mp4。切勿覆蓋使用者已經看過的渲染檔案或 EDL 版本。
• 先使用 --stills 檢查更改的時刻，然後再渲染一次完整影片。
• 在迭代過程中保持相同的風格；當一個意見暗示一個通用規則時（「無空白邊緣」、「字幕更大」），應套用至所有地方，而不僅是螢幕截圖中的那處。
• 如果使用者想要為某個鏡頭更換不同的素材，請在 EDL 中更改該片段（請參閱 references/edl-schema.md 中的「更換片段」）— 其他部分不動。

其他工具

• scripts/render_reel.py --stills ... — 任何時刻，輸出為 PNG 加上連續圖。
• scripts/clip_sheet.py — 候選片段的幀圖與硬剪輯時間。
• references/renderer.md — 渲染器的工作原理、速度、字型、疑難排解。

基本規則

• 素材：只使用使用者擁有權限的素材——他們自己的素材、已授權或免費授權的圖庫素材，或為他們生成的片段。生成的人物不得看起來像真實演員或名人，且不得重現著名角色、服裝、標誌或電影場景。
• 每次渲染都是一個新檔案。切勿覆蓋使用者已審查過的內容。
• 在專案檔案中使用英文；用使用者的語言與他們溝通。