promo-video
一部影片分六個階段製作。每個階段都以人類需確認的產出結束。 不可超前執行：昂貴的階段（建構）只有在前面階段都確定之後才變得便宜，因為每一幀畫面事件都是相對於音樂和語音來擺放的。
一開始先向人類說明計畫一次（README.md 有人類看得懂的版本），然後依序執行各個階段。用他們的語言與他們溝通。將所有專案檔存放在同一個目錄（<project>/）下：包含 audio/、vo/、PLAN.md、elevenlabs.md，以及 Remotion 專案 video/。
| # | 階段 | 你做的事情 | 人類做的事情 | 參考文件 |
|---|---|---|---|---|
| 1 | 音樂 | 分析音軌，找出真實節奏與明顯標記 | 在 Epidemic Sound 上選曲、使用 Create a cut 設定長度、給你檔案 | references/01-music.md |
| 2 | 分鏡 | 提出引導性問題，撰寫 PLAN.md（配合音樂時間的鏡頭表） | 回答問題、核准 | references/02-storyboard.md |
| 3 | 旁白稿 | 撰寫台詞 + 標記好的 ElevenLabs 錄音稿 | 在 ElevenLabs 產生語音、傳送檔案 | references/03-voiceover.md |
| 4 | 裁剪語音 | 開啟 cut_ui.py 處理錄音、分割、調整音量、擺放每個句子 | 在瀏覽器頁面上按句子之間點擊、按下 Done；檢查擺放位置表 | references/03-voiceover.md |
| 5 | 建構 | 從 template/ 建立 Remotion 專案，一個場景一個場景來，持續以靜止畫格檢查 | 審視靜止畫格 / 草稿渲染 | references/04-build.md |
| 6 | 審閱 + 打磨 | 渲染、檢查音量、在渲染檔上開啟 review_ui.py、閱讀人類的筆記與幀數、修正、重新渲染 | 在審閱頁面上觀看、在畫面上留下筆記、選擇「已核准」或「需要修改」 | references/05-review.md |
瀏覽器自動化：主動提供，但從不預設
階段 1 與階段 3 在網站上進行（Epidemic Sound、ElevenLabs）。如果瀏覽器自動化的技能或工具可用（例如 ego-browser、Playwright 設定、browser MCP），主動提議由你來做這些部分，並在詢問同意前清楚說明會涉及哪些事項：
- 帳號：兩個網站都需要帳號（Epidemic Sound 是付費訂閱制，有試用期；ElevenLabs 有免費方案，每月有字數上限）。如果人類還沒有帳號，他們自行註冊：你不可建立帳號。
- 費用：ElevenLabs 以字數計費；一部 40-60 秒的影片約 600-1000 字，每次重新產生都會再次收費。Epidemic 的下載次數會計入方案用量。告知他們預估花費並先詢問。
- 登入與付款是人類的責任：將瀏覽器控制權交給人類（例如在 ego-browser 中
task.handOff()），讓他們處理登入、雙重驗證、驗證碼以及任何付款畫面；等他們說完成後再繼續。絕不打人類的密碼，絕不輸入或儲存信用卡資訊，絕不將他們的 API 金鑰貼到頁面或檔案中。 - 同意後你可以做的事：按商定的風格與 BPM 搜尋/篩選音軌，並開啟候選曲目讓人類試聽（由他們選擇）；按下 Create a cut 設定目標長度並下載結果；貼上
elevenlabs.md的錄音稿、套用他們挑選的聲音與設定、產生一次、下載 mp3。 - 如果沒有此類工具，或人類拒絕使用：給他們確切的步驟（階段 1 與階段 3 的文件），然後等待檔案。
選擇權始終屬於人類：音樂和聲音都不是由你為他們決定的。
基本規則（從經驗學到的教訓）
- 所有展示內容都必須是真實的。 真實的範例網格（將實際 CAD/STEP 檔案細分網格）、程式碼面板中的真實程式碼與 API、從產品自己的前端元件重建的 UI。虛假內容是觀眾唯一會注意到的東西。如果你無法取得真實內容，請說出來並詢問——切勿自行虛構。
- 音樂就是時鐘。 測量真實節奏（
scripts/music_analyze.py會擬合真實 BPM；猜測的 BPM 只要有 1.2% 的誤差，就會讓接合點偏移三分之一拍，人類會感覺到不流暢）。所有時間都存在src/marks.ts中；場景引入這些時間，絕不硬編碼秒數。 - 確認對外展示或昂貴的步驟：音樂檔與語音檔由人類選擇；你絕不能幫他們挑。絕不列印出現在你所拍攝產品中的 API 金鑰或登入令牌。
- 用靜止畫格檢查畫面，而不是靠信心：在關鍵標記點（節拍點、剪接點、標誌）渲染幀數並實際檢查，然後再進行完整渲染。完整渲染需要數分鐘；靜止畫格只需要數秒鐘。
- 保留舊版本。 當人類要求縮短版本或變體時，複製整個專案目錄，然後編輯拷貝（
cp -R video video_short，並將node_modules建立符號連結）。 - 像剪接師一樣報告：說明了改變了什麼、檔案路徑、要聽/看什麼、以及在哪個時間點。
此技能內含的工具
所有 Python 腳本都透過 uv run 執行（每個檔案中都宣告了相依性；無需額外安裝）。
| 腳本 | 用途 |
|---|---|
scripts/music_analyze.py track.wav --out beats.json | 真實 BPM（擬合）、拍子/小節格線、段落、重拍、靜音間隙 |
scripts/music_splice.py track.wav out.wav --beats beats.json --keep a:b --keep c:d | 透過對齊小節的交叉淡入跳接來縮短音軌；驗證接合點 |
scripts/cut_ui.py take.mp3 --mode cuts --script elevenlabs.md --out vo/cuts.json | 瀏覽器剪接頁面（波形、逐行顯示腳本、語音 vs 停頓、縮放、復原/重做）：人類播放音檔並在每句結尾處點擊，按下 Done，分頁關閉後 cuts.json 就會產生供你使用。--mode marks --beats beats.json 在節拍格線上標記音樂的重拍、衝擊音、斷點 |
scripts/vo_cut.py take.mp3 --regions vo/cuts.json --out vo/ | 將 ElevenLabs 錄音檔分割成已調整音量的片段 + clips.json（或者如果人類偏好輸入時間點，可使用 --lines N --ends t1,...） |
scripts/review_ui.py out/promo.mp4 --out review/review.json [--overlay overlay.json] | 瀏覽器審閱頁面：上方為監視器，下方為時間軸條（膠片檢視 + 最終混音的波形 + 可選的節拍 / 標記 / 語音線條）。人類可在特定時刻或範圍內留下註記；每條註記都包含確切的幀數；他們最後選擇「已核准」或「需要修改」，然後 review.json 就會產生供你使用 |
scripts/new_project.sh <dir> [--link-modules path] | 從 template/ 建立 Remotion 專案（包含金屬舞台、節拍時鐘、VO 混音、虛擬攝影機） |
template/tools/mesh.py | STEP/OCC 形狀 -> 精簡網格 + 用於 three.js 的 B-rep 邊緣 |
template/tools/refold.py | 清空 OCC 無法讀取的大型 STEP 中繼資料字串 |
template/tools/variants.py、stages.py | 網格參數變體 / CAD 筆記本中的每個中間實體（用於「拖動滑桿，模型隨之變化」和「逐格推進」的場景） |
需要安裝：ffmpeg、node 20+、uv。對於 headless Chrome 中的 three.js：playwright 的 chrome-headless-shell（new_project.sh 會安裝它）。