產品宣傳片製作 (Remotion) 是做什麼的？

把「素材目錄 + 創意想法」做成一支可直接播放的 MP4 宣傳片。主體用 Remotion（React 程式化影片）本地渲染，可復現、易微調；腳本、TTS、少量補鏡優先用阿里雲百煉 CLI bl。

適合：圖片/實物圖/小程式截圖/短影片為主、文字+動效+配音的 motion-graphics 型宣傳片（展廳循環、產品介紹、發佈會片頭）。不適合：需要大量真人實拍/複雜運鏡的鏡頭。少量缺失鏡頭可用百煉快樂馬模型補齊，再回到 Remotion 合成。

環境前置

node(>=18) npm ffmpeg/ffprobe python3(含 numpy、requests)。開工前 which node ffmpeg python3 確認。
bl CLI 已安裝並登入：bl --version、bl auth status。使用 bl 前按 bailian-cli skill 的版本預檢規則確認版本。
渲染時需聯網（首次載入 Noto Sans SC 字型）。

標準工作流（按序執行）

1. 摸清素材與意圖

讓用戶給出素材目錄和創意想法/賣點。先列目錄：find <dir> -type f \( -iname '*.jpg' -o -iname '*.png' -o -iname '*.mp4' -o -iname '*.mov' \)。
逐張 Read 關鍵圖片（看清產品、功能點、界面），ffprobe 每個影片拿時長/編碼/解析度。
識別坑：① 截圖裡有不利數據（如"按時吃藥率 4%"）要在片中用 React 覆蓋成正向數據；② 同一產品多種顏色/型號要選主視覺；③ 無關素材剔除。

2. 設計分鏡，先和用戶對齊（重要）

用 AskUserQuestion 確認：風格、時長(展廳循環建議 60–90s)、畫幅(橫屏 1920×1080 / 豎屏 1080×1920)、配音方式。
風格直接給現成 3 套預設選(見 styles/STYLES.md)：warm 溫情家庭向 / guochao 活力國潮 / tech 商務科技。每套都已實現好配色+裝飾+分鏡，選定後在套用風格步驟直接使用，不用從零設計視覺。需要全新風格再以最接近的一套為基底改。
文案口吻隨風格定：情感敘事(warm/guochao) 還是公司產品介紹(tech)。
可用百煉先起草腳本/分鏡，再人工收斂：

bl text chat \
  --system "Reply in 簡體中文. 輸出緊湊的產品宣傳片分鏡表。" \
  --message "根據這些素材和賣點，寫一版60秒產品宣傳片分鏡：<素材清單+賣點>"

產出分鏡表：每段(鏡頭號/時長/畫面/大字卡/旁白/用哪個素材)。展廳片原則：無聲也能看懂(大字卡為主)、3秒抓人、結尾能循環接回開頭。

3. 從模板搭工程

PROJ="$HOME/<片名>"
cp -R ~/.claude/skills/product-promo-video/template "$PROJ"
cd "$PROJ" && npm install
mkdir -p public/assets public/audio out

模板已含：theme.ts(配色/字型/SCENE_FRAMES)、components.tsx(KenBurns/BigTitle/Subtitle/Narration/BgMusic/PhoneMock/Chip)、Video.tsx(TransitionSeries 疊化)、Root.tsx、scenes/AllScenes.example.tsx(完整示例,改寫後另存為 AllScenes.tsx 供 Video 引用)。

4. 處理素材進 public/assets

HEVC 必轉 H.264(Chromium 解 HEVC 不穩)： ffmpeg -y -i in.mp4 -c:v libx264 -pix_fmt yuv420p -crf 20 -an public/assets/weather.mp4
圖片拷入並改成 ASCII 檔名(staticFile 對中文路徑不穩)：intro.jpg / device.jpg / app_home.jpg ...。
不利數據的截圖照常拷入，靠分鏡組件裡畫 React 卡片覆蓋。

5. 可選：百煉快樂馬補鏡

素材缺關鍵鏡頭時可用 bl video generate / bl video ref 生成補鏡；素材足夠時可跳過，直接用 Remotion 動效。
不要在 skill 中限制快樂馬影片生產長度。--duration 按用戶需求、預算和百煉模型支援範圍設定；需要更長成片時生成多個片段後交給 Remotion/ffmpeg 合成。
為節省試錯成本，首次測試建議用 720P、5 秒小樣確認方向，確認後再按正式需求調整參數。
文生影片範例（低成本測試小樣，可調整時長）：

bl video generate \
  --model happyhorse-1.1-t2v \
  --prompt "明亮現代展廳裡，一台智慧健康設備在柔和燈光下緩慢旋轉，商務科技質感，無文字，無logo" \
  --ratio 16:9 \
  --resolution 720P \
  --duration 5 \
  --download public/assets/ai_device_5s.mp4

圖生影片範例（低成本測試小樣；本地圖片可直接傳給 --image，CLI 會自動上傳臨時檔案）：

bl video generate \
  --model happyhorse-1.1-i2v \
  --image public/assets/device.jpg \
  --prompt "保持產品外觀一致，鏡頭輕微推進，背景乾淨，柔和反光，無文字" \
  --ratio 16:9 \
  --resolution 720P \
  --duration 5 \
  --download public/assets/device_i2v_5s.mp4

生成後用 ffprobe 看時長/編碼；若是 HEVC 或瀏覽器不穩，按第 4 步轉 H.264。

6. 寫文案 + 阿里百煉配音（首選）

把旁白寫進 narration.json：{"s1":"...","s2":"..."}，鍵名對應分鏡段，與 Narration file="s1.mp3" 一致。逗號分句有助於 TTS 自然停頓。
首選百煉 CosyVoice：

source ~/.claude/skills/product-promo-video/config/bailian.env
python3 ~/.claude/skills/product-promo-video/scripts/gen_tts_bailian.py \
  --script narration.json --out public/audio

直接調 CLI 生成單句時：

bl speech synthesize \
  --text "一句產品宣傳片旁白" \
  --voice longanwen_v3 \
  --language zh \
  --instruction "商務科技宣傳片旁白，語氣自信、清晰、溫暖，語速適中" \
  --format mp3 \
  --out public/audio/s1.mp3

火山引擎作為備選：

source ~/.claude/skills/product-promo-video/config/volcano.env
python3 ~/.claude/skills/product-promo-video/scripts/gen_tts_volcano.py \
  --script narration.json --out public/audio

報 code 3001 resource not granted = 帳號側未授權：火山控制台開通「語音合成」、把音色加到該 appid、確認 appid/token 配對。服務剛開通時首個請求可能仍失敗，腳本已內置重試；個別沒成的單獨重跑即可。
無網路/無授權時兜底：scripts/gen_tts_say.sh narration.json public/audio(macOS say，音質一般，作佔位)。
大模型音色(更自然，推薦)：若用 *_bigtts / saturn_* / *_uranus_* 等大模型音色，走 v3 介面：source config/seed.env 後 python3 scripts/gen_tts_seed.py --script narration.json --out public/audio。換音色直接 export SEED_SPEAKER=<音色ID> 覆蓋即可。它是 API Key 鑑權(X-Api-Key)、串流式返回，和 v1(BV音色)是兩套服務/計費。
- Resource-Id 用 seed-tts-2.0(seed.env 預設值)。實測 saturn_* 和 *_uranus_* 音色都走它；用錯(如 seed-tts-1.0/volc.megatts.default)會報 code 55000000 resource ID is mismatched with speaker。
- 網路/代理抖動會偶發 RemoteDisconnected，腳本已內置異常捕獲+重試(--retry 5)。

7. 按真實音訊時長校準鏡頭長度（關鍵，否則截斷）

~/.claude/skills/product-promo-video/scripts/measure_audio.sh public/audio

在 theme.ts 的 SCENE_FRAMES 裡，確保每段：

鏡頭幀數 ≥ Narration 的 delayFrames + ceil(音訊秒數 × fps) + 收尾留白(建議 ≥15 幀) 改完時長記得同步檢查 Video.tsx 總幀數(自動求和，一般不用動)。

8. 套用風格 / 寫分鏡組件

首選：套用現成風格預設(styles/STYLES.md)。把選定風格的 theme.ts、裝飾模組、AllScenes.tsx 拷進 src/ 對應位置，再按本片文案改螢幕大字卡文字即可。三套：warm/guochao/tech。
若手寫/微調分鏡：用 components.tsx 的 BigTitle(大字卡)、KenBurns、Subtitle、PhoneMock(支援 crop)、Chip、FeatureCard；國潮/科技再疊各自裝飾件(印章/玻璃卡/角標/HUD)。
每段放一個 <Narration file="sX.mp3" delayFrames={..} />。
覆蓋不利數據：在對應 PhoneMock 上疊一個 React 卡片(見範例 MedsBadge)。

9. 背景音樂

python3 ~/.claude/skills/product-promo-video/scripts/gen_bgm.py \
  --duration <影片秒數+2> --out public/audio/bgm.mp3   # 可選 --semitones 移調 --gain 調音量

Video.tsx 已有 <BgMusic base={0.85} />，會自動按影片長度淡出、壓在旁白下。覺得吵就調小 base。

10. 渲染 + 自檢

npx remotion render Promo "out/<片名>.mp4" --concurrency=2
~/.claude/skills/product-promo-video/scripts/verify.sh "out/<片名>.mp4"

用 --concurrency=2：高並發(4)在本機偶發 Node 崩潰(輸出只剩 Node.js v22.x 棧尾、無成片)。崩了就降並發前台重跑，通常即過。
後台跑渲染時，崩潰也可能報 exit 0，務必檢查 out/ 裡 mp4 是否真生成，別只看退出碼。然後用 Read 看 /tmp/vchk 抽幀(確認中文/emoji/排版)、看 verify.sh 的音量(mean 約 -18~-23dB 為正常，不可靜音)。必要時 silencedetect 檢查某句旁白是否完整發音。

11. 交付與變體

報成片路徑/規格/時長。常見追加：嵌入實拍短影片、出豎屏版(改 Root.tsx 寬高 + 重排佈局)、改文案/配色/音樂後重渲染。也可 npm run dev 開 Remotion Studio 即時預覽。

硬核坑（務必遵守）

旁白必須放進 <Sequence from={delayFrames}>。不能用 if(frame<delay) return null 來"延遲"——那不是延後起播，而是跳過音訊開頭 delay 秒，會把每句開頭的字吃掉(典型症狀："爸媽的藥"只唸出"的藥")。模板的 Narration 已是正確寫法。
HEVC 影片先轉 H.264 再 <OffthreadVideo>，否則 Chromium 渲染黑屏/報錯。
素材用 ASCII 檔案名放 public/assets，staticFile('assets/xx.jpg') 引用。
中文字型用 @remotion/google-fonts/NotoSansSC(模板 theme.ts 已配，回退蘋方)；彩色 emoji 在 Chromium 渲染正常，可放心用作圖示。
配音生成後一定重新量時長並校準 SCENE_FRAMES，不同音色/語速時長會變，否則尾音被切。
不要把 5 秒小樣寫成生產限制。快樂馬補鏡的 --duration 由用戶需求、預算和模型支援範圍決定；長片可由多個 AI 片段、真實素材和 Remotion/ffmpeg 拼接完成。
AI 影片提示詞避免文字/Logo，否則容易生成錯字或變形標識。品牌名、賣點、字幕統一用 Remotion 疊加。
火山 3001 多為帳號授權問題，不是程式碼問題，按配音步驟排查。
火山憑證在 config/volcano.env(含密鑰，勿外傳)；Secret Key 此 HTTP 介面用不到。
所有 remotion 包必須鎖同一精確版本(remotion / @remotion/cli / @remotion/transitions / @remotion/google-fonts 全部 4.0.xxx 不帶 ^)。帶 caret 會讓某個子包裝成更新版，出現 export 'HtmlInCanvas' was not found in 'remotion' 這類打包報錯。模板已鎖定；新裝包後用 node -e "..." 核對版本一致。

檔案地圖

scripts/gen_tts_bailian.py 阿里百煉 CosyVoice TTS(首選, 調 bl speech synthesize)
scripts/gen_tts_volcano.py 火山標準TTS(BV音色, v1介面, env 讀憑證, JSON 讀文案)
scripts/gen_tts_seed.py 火山大模型TTS(bigtts/saturn/uranus 音色, v3介面, API Key 鑑權, 推薦)
scripts/gen_tts_say.sh macOS 離線兜底配音
scripts/gen_bgm.py 合成溫情背景樂
scripts/measure_audio.sh 量旁白時長→幀，校準 SCENE_FRAMES
scripts/verify.sh 成片自檢(規格/音量/抽幀)
config/bailian.env 百煉 TTS 參數 · config/volcano.env 火山標準TTS憑證 · config/seed.env 大模型TTS憑證
config/narration.example.json 情感敘事文案樣例 · config/narration.corporate.example.json 公司產品介紹文案樣例
styles/STYLES.md + styles/{warm,guochao,tech}/ 三套風格預設(配色+裝飾+分鏡)，選定後拷進工程 src/
template/ 可直接 cp -R 的 Remotion 工程骨架

產品宣傳片製作 (Remotion)