QQTangBa/cangshu-koubo-motion-edit

口播動效剪輯管線（3:4 動效成片）

講者說一句，畫面對這句做出反應；圖形段是「一個主角演一條鏈」，不是一頁頁翻卡片。

本 skill 建在基座 cangshu-koubo-wudongxiao 上：剪口誤、停頓、剪點、字幕源和敏感詞用它的腳本和規則，本 skill 只在上面加 3:4 裁切、圖形段、B-roll、BGM、音效。兩個 skill 要裝在同一個 skills 目錄下。

文件地圖

文件	什麼時候讀
references/style-bible.md	寫 plan 前必讀：節奏、真人段疊層、進出圖形、聯動、鏡頭、畫風、音效
references/scene-guide.md	寫圖形段（手寫場景）時對照：座標和鏡頭、kit / lux / toon 工具、畫風主題、穿模清單、音效提示、範例拆解
references/plan-schema.md	寫 plan.json 時查欄位
references/metaphor-bank.md	每個圖形段論點先過一遍發散流程
references/demo-patterns.md	挑演示套路：第 2 節（套路庫）、第 4 節（抓注意力）
references/layout-34.md	第 2 節安全區（寫 plan 前讀）；第 1 節拍攝建議（用戶問怎麼拍時照著答）
references/sfx-palette.json	音效清單：角色 → 素材、裁剪、增益
references/board-draft.md	只在出草稿、對時間軸時看
assets/example-plan.json	完整範例，圖形段是模板裡的 custom/stock1.tsx、stock2.tsx（白卡畫風）；動畫片畫風範例是 custom/toon_panel_example.tsx。範例裡的 tag / pill 膠囊和「標籤飛進圖形段」是舊做法，別照抄

環境

uv venv -p 3.12 <臨時目錄>/venv && VIRTUAL_ENV=<臨時目錄>/venv uv pip install mlx-whisper "opencv-python-headless<5" numpy scipy pillow

opencv 要 5 以下（5.x 沒有人臉檢測器）。下文 $SK = 本 skill 目錄，$B = 基座的 scripts/ 目錄（和本 skill 同級的 cangshu-koubo-wudongxiao/scripts），$PY = 上面 venv 的 python。

• 只能在 macOS（Apple 晶片）上跑：轉寫用 mlx-whisper（模型優先讀本機快取，沒有就自動下載 mlx-community/whisper-large-v3-turbo），摳像用系統內建 Vision（要 Xcode 命令列工具裡的 swiftc）。另外要 ffmpeg、Node 18+。
• 渲染用 Remotion 4.0.520：new_project.sh 會 npm install（設了 KOUBO_REMOTION_CACHE 時先找那個目錄下同版本的依賴複用）。Remotion 有自己的許可：個人和小團隊免費，規模以上的公司商用要買 Remotion 的公司許可，開工前提醒用戶一次。
• 音效庫不隨 skill 分發。第一次用先徵得用戶同意（來源：mixkit.co 30 個 + kenney.nl 兩包，約 3.3MB），再 python3 $SK/scripts/fetch_sfx_library.py <目錄> 下載，之後 build_sfx.py 加 --library <目錄>，或設環境變數 KOUBO_SFX_LIB。用戶不想下載就在 plan 裡寫 meta.autoSfx: false、不寫 cue，出無音效版。
• BGM、圖庫、產品圖、角色精靈圖都由用戶提供，不去網上找。

流程

1. 收輸入、建工程

• 原始影片（必須）；口播稿定稿或剪映 / 其他軟體匯出的字幕 SRT（有就要）；品牌字（meta.brand，用戶的帳號名或品牌名，沒有就不開品牌字牆）；背景資料（數據卡的來源）；有授權的 BGM、圖片、產品圖。
• 問一句這條片子有沒有所屬系列的固定做法（畫風、片頭、BGM）：有就照辦，後面不再問。
• bash $SK/scripts/new_project.sh <工程>，工程放哪問用戶。

2. 剪口誤、對字幕（走基座），出 3:4 素材、摳像、音效

剪口誤和重複、剪停頓、剪點校正、字幕源和敏感詞、對字幕時間，都用基座的腳本和規則（它的 references/cut-rules.md、captions.md），在 <工程>/基座/ 裡做，這裡不另立一套。

$PY $B/prepare_source.py <原影片> <工程>/基座/source.mov    # 第 0 步：整理成 source.mov；用戶自己做過美顏 / 降噪匯出時用三參數版（見基座第 0 步）
$PY $B/transcribe.py <工程>/基座/source.mov <工程>/基座/raw_transcript.json
#   按基座 cut-rules.md 寫 <工程>/基座/edl.json（source 寫 source.mov；沒有系列固定片頭就在頂層寫 "intro": false）
$PY $B/cut_takes.py <工程>/基座
$PY $B/find_ng.py <工程>/基座                        # 短語級聽寫找重複，必跑
$PY $B/edl.py rebuild <工程>/基座 --remove <起-止>...  # 刪口誤、剪 >0.4 秒的停頓、收剪點兩側、刪碎片
$PY $B/cut_takes.py <工程>/基座 && $PY $B/find_ng.py <工程>/基座
$PY $B/transcribe.py <工程>/基座/cut.mp4 <工程>/基座/cut_transcript.json --prompt "以下是普通話口播，我是<講者名>，內容關於<領域>。"
python3 $SK/scripts/srt_captions.py <字幕.srt> <工程>/基座/字幕源.txt      # 用戶給了 SRT：用裡面的字出初稿
python3 $SK/scripts/captions.py <工程>/基座/cut_transcript.json <工程>/基座/字幕源.txt   # 沒給字幕：按轉寫出初稿
#   按基座 captions.md 改字幕源：錯字專名、[重點詞]、敏感詞
$PY $B/captions.py <工程>/基座
$PY $SK/scripts/from_base.py <工程>/基座 <工程>/public  # 剪點校正 + 裁 3:4 + 烤進 8 幀光流融合，寫 words.json、cuts.json，拷 captions.json
bash $SK/scripts/matte.sh <工程>/public/footage34.mp4 <工程>/public/person.webm
python3 $SK/scripts/build_sfx.py <工程>/public --library <音效庫目錄>

• 之後所有時間都用 public/words.json 的時間線（不變速時和 基座/cut.mp4 一致）。預設不變速；用戶說了倍速才給 from_base.py --speed 1.1（用基座同一套做法：系列片頭原速、之後整體變速、聲音不變調，字幕和逐字時間跟著換算）。片頭防抖、人聲消音照基座的規矩：不主動做，先問。
• from_base.py 列印的「臉中心 y」偏離 0.3–0.55 就檢查裁切，用 --face-y 指定；原片已經是 3:4 時整幅縮放不裁。
• 摳像抽一幀疊到深灰底上看頭髮和肩膀；摳不好就記下來，寫 plan 時刪掉 meta.person 欄位（不要寫空字串），模板自動降級。
• build_sfx.py 按 references/sfx-palette.json 從音效庫構建音效，不另找素材（選音原則見 style-bible 第 10 節）。
• 字幕：captions.json 放進 plan 的 captions，meta.captionStyle: "pop"（重點詞放大 1.32 倍亮黃，出字彈一下，消失一幀消失）。
• 素材（crf 10 + 輕銳化）、摳像（crf 18）、渲染（PNG 幀 + crf 12）的清晰度預設值已經寫進腳本和模板，不要調低（看得出糊）。
• BGM 沒定時先給試聽（用戶要推薦、或系列約定裡沒有）：從用戶提供的有授權曲庫挑 6–9 首風格不同的（需要署名的交付時提醒寫署名），每首挑已經進拍的位置，配到剪好的素材開頭 8 秒上出連播，等用戶選：

  $PY $SK/scripts/bgm_audition.py <工程>/public/footage34.mp4 <工程>/bgm試聽 --track "名字=路徑@起點秒" --track "名字=路徑@起點秒"
  

  試聽比人聲低約 11dB（低 20dB 幾乎聽不見）。選定後把曲子硬連結或複製進 <工程>/public/（meta.bgm.src 只認 public 下的檔案名稱）；成片比人聲低約 12.5dB：用 --rel -12.5 只放這一首再跑一次，meta.bgm.volume = 10^(列印的增益/20)，meta.bgm.from = 起點秒。曲子比片子短會循環，交付時說一句。用戶沒有 BGM 就不加。

3. 排段、補資料

• 按 style-bible 第 2、4 節分段：講機制、舉例、給數據、做對比進圖形；表態、結論、轉折回真人；圖形段 ≤16 秒；寫 chapters（短影片 3 段）。
• 資訊量靠查證過的數據：台詞裡的關鍵論點，能聯網就找能追到原始出處的數字做數據卡，拿不準的不用；螢幕上的出處寫泛稱，真實連結記進交付說明；口播裡的個人估計標「個人判斷」。補充的數據先列給用戶確認。

3.5 畫風、片頭（先定方向）

• 畫風兩條路：lux.tsx 白卡精緻（色板固定，不參與主題），或 toon.tsx 寫場景、用 meta.style 在 9 套主題裡換（style-bible 第 7 節）。系列約定裡有就照用；沒有就先用 toon 寫，第 5 步寫完第一個圖形段再出風格樣片讓用戶挑。用戶要換風格時只換元素和動畫，底色和字牆不動。
• wall 主題取的是實拍背景牆的顏色：用它之前，從 public/footage34.mp4 抽一幀量背景牆的顏色，改 toon.tsx 主題表裡 wall 的底色，拆景時空牆淡成圖形底才不跳色。
• 圖形段背後要品牌字牆（一行行品牌字左右交替滾動）寫 meta.wall: true（dark 主題預設開；只對 toon 場景生效），字取 meta.brand。
• 角色小人：預設用 toon.tsx 裡程式碼畫的 Kid。用戶有自己的角色精靈圖（透明 PNG）才開 meta.qkid: true：圖放 public/ipq/，尺寸登記進 src/scenes/custom/ipq.json（格式見 scripts/split_sheet.py 說明）。真人 ↔ 小人的變身（host: "morph"）也要精靈圖；沒有就不用，plan_check.py 會攔。
• 欄目化的系列（「歡迎來到 XX 第 N 期」）用 custom/intro.tsx 固定片頭：meta.series 寫欄目名、期數、題目，plan 裡在那句上放約 3.2 秒的 B 段，登記方法見 custom/index.ts 註解。

4. 每個圖形段先想清楚演什麼

• 按 metaphor-bank 第 1 節，每個論點在「直白 / 比喻 / 誇張 / 荒誕」四檔各寫一個候選，打分選一個；一條影片至少一半選到誇張或荒誕（1 秒看懂為前提）。表格存成工程裡的 創意發散.md。
• 定「主角 + 鏈條 + 聯動表」（style-bible 第 5 節）：同一個主角一路變形；至少 3 條狀態聯動鏈；跨段或跨世界至少照應 1 處；數據卡從主角邊上長出來做旁註，講完縮回去。

5. 寫手寫場景

按 scene-guide 寫 src/scenes/custom/<名字>.tsx 並登記。要點：

• 鏡頭只在句子交界處動，停留中位 ≥2 秒（個別不短於 1.4 秒）且完全靜止，一次運動 0.6–0.9 秒、多數是推拉；Camera3D + orbitAt 給整塊畫布 3D 透視。
• 畫風沒定時：先寫完第一個圖形段（toon），把 plan 裡這一段排好，跑 $PY $SK/scripts/style_reel.py <工程> <起秒> <止秒> --themes dark,white,chalk,news 出風格連播給用戶挑；要「再來幾個」就換別的主題（blue、neon、water、toon、wall）再出。只換畫風，不改動作和字。選定寫進 meta.style 再寫其餘段。
• 畫風按 3.5 定的來：白卡精緻用 lux.tsx，其餘用 toon.tsx（Stage 包場景，顏色只取 T.*，直接寫在底上的字和線用 T.onBg / T.onBgSoft）；平的畫面才加 Tilt。
• 物件用程式碼畫（custom/objs.tsx 的扁平向量，缺的照樣往裡加），不用寫實圖示。
• 卡點：動詞誤差 ≤0.1 秒，名詞提前 0.3–1 秒，數字提前 0.4 秒起跑。
• 第一個元素從 contentStart(seg) 以後出（切鏡動畫期間不出東西）；任何元素停 5–7 秒內要有新元素或變化（style-bible 第 5 節資訊量）。
• 一段 B-roll 資訊一螢幕放不下時才拆成幾塊、鏡頭在塊之間走（挪半螢幕、每螢幕填滿，style-bible 第 6 節「段內多畫布」）；一螢幕裝得下就不拆。
• 台詞講到具體的東西（一張畫、一頁 PPT、一個小程式、一份稿子）可以插真圖：只用用戶提供的有授權圖片，放 public/real/；AI 生成的掛「AI 生成」角標；只用圖不用網上找的實拍影片（style-bible 第 7 節）。用戶沒給圖就用程式碼畫。
• 擺位時就按 scene-guide 第 5 節防穿模、越界；cues 只給關鍵聯動配音效。

6. 寫 plan.json

按 plan-schema 寫 segments、captions、chapters、真人段疊層。真人段的數字進左上數據卡（metric），結論用前景大字、並列關鍵詞用貼頭字（sideWords）、一段論證的收尾用便籤（sticker）；兩三個字的重點詞偶爾用頂邊身後大字（topWord，look: "steel"），要點清單偶爾用左上資訊框（infoBox），開頭兩者同時出時大字先飛成資訊框角標。進出圖形按 style-bible 第 9 節寫 enter / host / exit：拆景配角落半身、淡出配圓球，不混用；拆景只在背景左右兩側各有明顯物件時用，否則用淡出；B-roll 開頭或結尾是小人、且配了精靈圖時可以加變身（host: "morph" + hostPath）；exit 不寫 = 硬切。實拍段不短於約 2.2 秒。不用左上 / 右上的小字膠囊（tag、pill），AI 味重；批註、便利貼、新聞條、花字、不寫字的動效提示也預設不用。

$PY $SK/scripts/fit_bigtext.py <工程>
python3 $SK/scripts/plan_check.py <工程>/src/plan.json

有拆景段就生成拆景素材（從切鏡那一幀拆空牆 / 左側物件 / 右側物件三層）：$PY $SK/scripts/split_plates.py <工程>，改了段落邊界要重跑；拆出來的分界不對就按自己的背景調腳本裡的閾值，調不好就改用淡出。 fit_bigtext.py 給身後大字逐字算遮擋（≤35%）、不頂進度條，放不下就挪到人前面；plan_check.py 的「必須改」清零，「建議改」逐條處理或說明理由。

7. 畫面文字自查

python3 $SK/scripts/screen_text.py <工程>/src/plan.json --with-captions

手寫場景裡的字也會抽出來；插進去真圖裡畫著的字抽不出來，人工逐張看。項目裡裝了合規 / 敏感詞檢查的 skill 就交給它唯讀檢測（註明目標平台和是否商業推廣，字卡和字幕單獨一行報告）；沒有就自己逐句過一遍基座 captions.md 的敏感詞表和目標平台常見違規詞，並把抽出的文字交給用戶核。有風險先改再重抽重查。後面只挪位置、沒改字時，重抽一遍和上一輪逐行比對，完全相同就沿用結論。

8. 預覽

cd <工程> && npx tsc --noEmit -p . && npm run preview
bash $SK/scripts/stills.sh <工程> <名字> <秒> <秒>

stills.sh 出半解析度靜幀橫拼，寫場景時每個鏡頭落位、元素交接處都看一眼。 半解析度給用戶看，按反饋改場景和 plan 再出。用戶要比幾種做法時：變身用 Morph-<dissolve|iris|flip|poof>、身後大字用 Top-<steel|extrude|…> 合成渲同一段。

• 資訊量自查：逐段量畫面變化（去掉字幕帶和進度條），超過 4 秒沒新事件的空檔補東西。
• plan 寫好以後才發現口誤（同一句說了兩遍）：不改 plan 的時間，python3 $SK/scripts/cut_slips.py <工程> <起-止>… 剪素材、按它列印的寫 meta.cuts 等欄位（plan-schema 第 1 節），再轉寫剪點前後幾秒確認只剩一遍。換了深色主題，整片逐段查一遍「深字落在深底」「白字落在白卡」。

9. 成片 + 質檢

python3 $SK/scripts/render_final.py <工程> --ver v1 --py $PY

一條命令跑完：渲染 → 量渲染帶來的聲音延遲並在限幅時扣掉 → 量口型（qa/口型.txt，聲-畫中位超過 20ms 算要處理）→ 成片音訊總檢 → 渲純音效音軌逐個測響度 → 出分鏡拼圖（圖形段和換章處每秒 5 幀，真人段每秒 2 幀），彙總寫進 out/<ver>/qa/質檢.txt。然後：

• 逐張看 qa/sb_*.jpg，找四種錯：元素頂進紅線以上（進度條區）、被畫框裁切、兩個元素互相穿過、兩層字疊在一起。可疑處抽大圖：$PY $SK/scripts/storyboard.py <成片> --at 25.1,25.25,25.4 --w 405 --hud --out <圖>.jpg。
• 「要處理」清零：音效整體偏響或偏輕調 meta.sfxVolume，個別偏調那條 cue 的 vol，擠在一起的刪一個。剩下只差 0.3dB 以內的是測量誤差，說明後可以不再調。
• 改完換新版本號重跑。只改了聲音（sfxVolume、cue 的 vol、BGM 音量）就不重渲畫面：bash $SK/scripts/remix_audio.sh <工程> v1 v2 --py $PY（只渲音軌、合回原畫面、再質檢）；動了任何畫面就整片重渲。

10. 交付

給成片路徑和時長、各世界佔比、音效個數和逐個響度範圍、整片響度（都在 質檢.txt），加畫面文字自查結論和是否需要人工複核。直接給清晰版路徑，不另壓手機版。 要 3:4 封面時：截圖放 public/，meta.cover 寫兩行字，npx remotion still src/index.ts Cover out/cover/封面_3比4.png --frame=0；封面字也過第 7 步的自查。用戶要換音效時，直接列出候選素材讓用戶自己聽，按選擇改源清單 $SK/references/sfx-palette.json（以後所有工程都用它）再跑 build_sfx.py；只改這一條片子，就把源清單複製進工程改，用 build_sfx.py <工程>/public --palette <那份> 重建。工程裡的 src/sfx-palette.json 是生成物，不要手改。

硬規則（每條都踩過坑）

1. 畫面是的字只用台詞、口播稿或用戶給的資訊；不編數字、評論、出處；浮水印用途戶品牌。
2. 圖形段超過 6 秒一律寫手寫場景；board 畫板只做草稿（自動排版會錯亂，像翻 PPT）。
3. 圖形段一個主角一條鏈，至少 3 條狀態聯動；不在幾個孤立道具之間來回切（像 PPT 翻頁）。
4. 鏡頭停得住：停留中位 ≥2 秒、最短 1.4 秒、停的時候完全靜止，不要「停留時慢推」（切太快觀眾看不清）。
5. 立體傾斜只救平的畫面，不是每張卡都加。
6. 真人段的字走毛玻璃數據卡、左上資訊框、逐字升起的大字、貼頭字和便籤，不用角落小字膠囊；身後大字只偶爾用（高級感低、字被人擋太多、小字膠囊 AI 味重）。
7. 不穿模、不越界：整條路徑在安全區裡，不穿頂部進度條，不互相穿過，管子水流光束到接觸面為止，變形時兩層字不疊。
8. 音效少而輕：只配關鍵聯動，圖形段每秒 0.3–0.7 個，兩兩隔 ≥0.5 秒，每個比人聲中位低 1–6dB，用偏亮的實錄素材（太密、太響就是污染，AI 味重）。
9. 模板改動同步進工程只用 bash $SK/scripts/sync_template.sh <工程>：它不碰工程自己的 plan.json、sfx-palette.json、手寫場景登記表 scenes/custom/index.ts 和工程自己的場景檔案（整體 rsync 曾把音效清單覆蓋成空，兩版成片一個音效都沒有）；但 remotion.config.ts 和 custom/ 下的工具檔案 toon.tsx、lbkit.tsx、intro.tsx、qkid.tsx、ep.tsx、real.tsx 每次覆蓋，工程專用的道具另寫檔案。new_project.sh 碰到已有工程會拒絕。工程裡改好的模板程式碼用 sync_back.sh <工程> <檔案>… 點名拷回。
10. 查完問題就動手改，改完重渲給結果，不要只彙報思路。
11. 真人段前景字落在淺色牆上要有深色描邊（模板的 BigText、SideWords 已帶兩層貼字陰影 + 柔投影，別去掉）；深色主題裡直接寫在底上的字和線用 T.onBg，卡片上的灰字用 T.inkSoft（白字白底看不清）。
12. 多段音影片拼接（BGM 試聽、風格樣片、連播）一律重新取樣到 48k、用 concat 濾鏡重新編碼，不用 -c copy（44.1k/48k 混著會把人聲拉高變調）；拼接命令用 Python 寫，zsh 裡 $i:a 會被當成路徑修飾符、set -- $x 不按空格拆。
13. Remotion 的靜態檔案服務不認軟連結：別的工程的素材放進 public/ 用硬連結（ln）或複製。後台在渲成片時 remotion still 會超時，自查用的靜幀一律走 stills.sh（先刪舊圖、渲失敗就報錯），不然會拿上一次的圖當新圖看。
14. 動效為內容服務：切鏡動畫不蓋內容（回真人預設硬切），元素不被摳像、圓球、字幕擋住；兩種進場切鏡不混用（拆景後不配圓球）。
15. 資訊量：任何元素停 5–7 秒內必須有新元素或變換，除非它本身在給大量資訊。小人是配角，不圍著小人設計動效。
16. 不為運鏡而運鏡：一螢幕裝得下就不拆塊；拆塊只在一段 B-roll 內部、挪半螢幕、每螢幕填滿（不同 B-roll 之間翻頁沒意義）。
17. 圖形段裡插的真實素材只用用戶提供的圖、不用網上找的實拍影片，圖要講台詞裡那件事，AI 生成的掛「AI 生成」角標（實拍影片出戲、不符合畫風）。用戶自己給的授權實拍照舊走實拍段（world S），不受這條限制。
18. 音畫不分離：素材、切片都走同一份 source.mov 和一張剪輯表；模板要混 BGM 和音效，聲音只能另鋪，由 render_final.py 量出延遲扣掉，不手動挪（渲染會讓聲音晚幾十毫秒，口型就對不上）。

改模板

模板在 assets/remotion-template/src/：Film.tsx（世界切換、拆景 / 淡出 / 變身切鏡、講者、音訊；sfxOnly 只出音效）、timing.ts（切鏡時間表、contentStart、剪口誤的時間換算）、morph.tsx + morphState.ts（真人 ↔ 小人變身，要精靈圖）、components/（base 基礎件、overlays 真人段疊層、hud 進度導航、extra 左上資訊框和頂邊身後大字）、scenes/kit.tsx 和 lux.tsx（手寫場景工具和白卡畫風）、scenes/custom/（types.ts 類型、index.ts 登記表、範例 stock1 和 stock2；toon.tsx 動畫片工具 + 9 套主題 + 品牌字牆、qkid.tsx 可選的角色精靈圖（圖在 public/ipq/、尺寸 ipq.json，預設空）、ep.tsx 產品界面式道具、objs.tsx 扁平向量物件、real.tsx 真圖和段內多畫布、lbkit.tsx 動畫片道具、intro.tsx 系列片頭、toon_panel_example.tsx 範例）、Root.tsx（Koubo34 按 meta.style 出成片，Style-<主題> 出風格樣片，Morph-<做法> / Top-<樣式> 出變身和身後大字對比，Cover 出封面）、Cover.tsx、scenes/scenes.tsx（單卡版式）、sfx.tsx（自動配音效）、scenes/board.tsx（草稿用）、scenes/props.tsx（卡通道具草稿用，裡面的 TablerIcon 成片也用）。字體在 theme.ts 的 F（預設蘋方、Avenir 等 macOS 系統字體，商用前換有授權的字體）。加欄位先改 plan.ts，再在 plan-schema.md 補一行。在工程裡改好、要留給以後的，用 bash $SK/scripts/sync_back.sh <工程> <相對 src 的檔案>… 拷回模板；往已有工程同步用 sync_template.sh。