影片工具包
根據文字簡報創建專業的說明影片。此工具包使用雲端 GPU(Modal 或 RunPod)上的開源 AI 模型來生成配音、圖片、音樂和說話頭像動畫。Remotion(React)負責合成與渲染。
關鍵:工具包路徑
工具包位於固定路徑。在執行任何工具命令之前,務必 cd 到此路徑。
TOOLKIT=~/.openclaw/workspace/claude-code-video-toolkit
cd $TOOLKIT
絕對不要在專案目錄內執行工具命令。 工具會解析相對於工具包根目錄的路徑。
設定
步驟 1:檢查當前狀態
cd ~/.openclaw/workspace/claude-code-video-toolkit
python3 tools/verify_setup.py
如果所有項目都顯示 [x],請跳到下面的「快速測試」。否則繼續設定。
步驟 2:安裝 Python 依賴
cd ~/.openclaw/workspace/claude-code-video-toolkit
pip3 install --break-system-packages -r tools/requirements.txt
注意:在 Debian/Ubuntu 使用受管理的 Python(PEP 668)時,需要使用 --break-system-packages。在容器內是安全的。
步驟 3:設定雲端 GPU 端點
工具包需要在 .env 檔案中設定雲端 GPU 端點 URL。檢查 .env 是否存在並包含 Modal 端點:
cat ~/.openclaw/workspace/claude-code-video-toolkit/.env | grep MODAL
如果 Modal 端點已設定,則準備就緒。如果沒有,請使用者提供 Modal 端點 URL 或設定 Modal:
pip3 install --break-system-packages modal
python3 -m modal setup # 開啟瀏覽器進行身份驗證
# 部署每個工具 — 從輸出中擷取端點 URL
cd ~/.openclaw/workspace/claude-code-video-toolkit
modal deploy docker/modal-qwen3-tts/app.py
modal deploy docker/modal-flux2/app.py
modal deploy docker/modal-music-gen/app.py
modal deploy docker/modal-sadtalker/app.py
modal deploy docker/modal-image-edit/app.py
modal deploy docker/modal-upscale/app.py
modal deploy docker/modal-propainter/app.py
modal deploy docker/modal-ltx2/app.py # 需要:modal secret create huggingface-token HF_TOKEN=hf_...
LTX-2 先決條件: 在部署 LTX-2 之前,建立一個 HuggingFace 密鑰並接受 Gemma 3 授權:
modal secret create huggingface-token HF_TOKEN=hf_your_read_access_token
將每個 URL 加入 .env:
MODAL_QWEN3_TTS_ENDPOINT_URL=https://...modal.run
MODAL_FLUX2_ENDPOINT_URL=https://...modal.run
MODAL_MUSIC_GEN_ENDPOINT_URL=https://...modal.run
MODAL_SADTALKER_ENDPOINT_URL=https://...modal.run
MODAL_IMAGE_EDIT_ENDPOINT_URL=https://...modal.run
MODAL_UPSCALE_ENDPOINT_URL=https://...modal.run
MODAL_DEWATERMARK_ENDPOINT_URL=https://...modal.run
MODAL_LTX2_ENDPOINT_URL=https://...modal.run
建議但非必要 — 使用 Cloudflare R2 以獲得可靠的檔案傳輸:
R2_ACCOUNT_ID=...
R2_ACCESS_KEY_ID=...
R2_SECRET_ACCESS_KEY=...
R2_BUCKET_NAME=video-toolkit
步驟 4:驗證與快速測試
cd ~/.openclaw/workspace/claude-code-video-toolkit
python3 tools/verify_setup.py
所有工具都應顯示 [x]。然後執行快速測試以確認 GPU 管道正常運作:
cd ~/.openclaw/workspace/claude-code-video-toolkit
python3 tools/qwen3_tts.py --text "Hello, this is a test." --speaker Ryan --tone warm --output /tmp/video-toolkit-test.mp3 --cloud modal
如果獲得有效的 .mp3 檔案,設定即完成。如果失敗,請檢查:
.env中的MODAL_QWEN3_TTS_ENDPOINT_URL是否正確- 執行
python3 tools/verify_setup.py --json並檢查modal_tools中缺少哪些端點
費用: Modal 提供每月 $30 的免費運算額度。一個典型的 60 秒影片花費約 $1-3。
創建影片
步驟 1:建立專案
cd ~/.openclaw/workspace/claude-code-video-toolkit
cp -r templates/product-demo projects/PROJECT_NAME
cd projects/PROJECT_NAME
npm install
範本:product-demo(行銷/說明)、sprint-review、sprint-review-v2(可組合場景)。
步驟 2:撰寫設定檔
編輯 projects/PROJECT_NAME/src/config/demo-config.ts:
export const demoConfig: ProductDemoConfig = {
product: {
name: 'My Product',
tagline: 'What it does in one line',
website: 'example.com',
},
scenes: [
{ type: 'title', durationSeconds: 9, content: { headline: '...', subheadline: '...' } },
{ type: 'problem', durationSeconds: 14, content: { headline: '...', problems: ['...', '...'] } },
{ type: 'solution', durationSeconds: 13, content: { headline: '...', highlights: ['...', '...'] } },
{ type: 'stats', durationSeconds: 12, content: { stats: [{value: '99%', label: '...'}, ...] } },
{ type: 'cta', durationSeconds: 10, content: { headline: '...', links: ['...'] } },
],
audio: {
backgroundMusicFile: 'audio/bg-music.mp3',
backgroundMusicVolume: 0.12,
},
};
場景類型:title, problem, solution, demo, feature, stats, cta。
持續時間規則: 將 durationSeconds 估算為 ceil(word_count / 2.5) + 2。在步驟 4 生成音訊後,你需要調整此數值。
步驟 3:撰寫配音腳本
建立 projects/PROJECT_NAME/VOICEOVER-SCRIPT.md:
## 場景 1:標題(9秒,約17個單詞)
使用 AI 建立影片。產品名稱工具包讓它變得簡單。
## 場景 2:問題(14秒,約30個單詞)
問題陳述放在這裡。保持精簡且易於共鳴。
每個場景的單詞預算: (durationSeconds - 2) * 2.5 個單詞。減 2 是為了容納 1 秒音訊延遲和 1 秒邊距。
步驟 4:生成素材
關鍵:以下所有命令都必須從工具包根目錄執行,而不是從專案目錄。
cd ~/.openclaw/workspace/claude-code-video-toolkit
4a. 背景音樂
cd ~/.openclaw/workspace/claude-code-video-toolkit
python3 tools/music_gen.py \
--preset corporate-bg \
--duration 90 \
--output projects/PROJECT_NAME/public/audio/bg-music.mp3 \
--cloud modal
預設:corporate-bg, upbeat-tech, ambient, dramatic, tension, hopeful, cta, lofi。
4b. 配音(逐場景)
每個場景生成一個 .mp3 檔案。不生成單一配音檔案。
cd ~/.openclaw/workspace/claude-code-video-toolkit
# 場景 01
python3 tools/qwen3_tts.py \
--text "The voiceover text for scene one." \
--speaker Ryan --tone warm \
--output projects/PROJECT_NAME/public/audio/scenes/01.mp3 \
--cloud modal
# 場景 02
python3 tools/qwen3_tts.py \
--text "The voiceover text for scene two." \
--speaker Ryan --tone warm \
--output projects/PROJECT_NAME/public/audio/scenes/02.mp3 \
--cloud modal
# ... 為每個場景重複
語者: Ryan, Aiden, Vivian, Serena, Uncle_Fu, Dylan, Eric, Ono_Anna, Sohee
語調: neutral, warm, professional, excited, calm, serious, storyteller, tutorial
若要進行語音複製(需要參考錄音):
cd ~/.openclaw/workspace/claude-code-video-toolkit
python3 tools/qwen3_tts.py \
--text "Text to speak" \
--ref-audio assets/voices/reference.m4a \
--ref-text "Exact transcript of the reference audio" \
--output projects/PROJECT_NAME/public/audio/scenes/01.mp3 \
--cloud modal
4c. 場景圖片
cd ~/.openclaw/workspace/claude-code-video-toolkit
python3 tools/flux2.py \
--prompt "Dark tech background with blue geometric grid, cinematic lighting" \
--width 1920 --height 1080 \
--output projects/PROJECT_NAME/public/images/title-bg.png \
--cloud modal
圖片預設(使用 --preset 取代 --prompt --width --height):
title-bg, problem, solution, demo-bg, stats-bg, cta, thumbnail, portrait-bg
cd ~/.openclaw/workspace/claude-code-video-toolkit
python3 tools/flux2.py \
--preset title-bg \
--output projects/PROJECT_NAME/public/images/title-bg.png \
--cloud modal
4d. 影片剪輯 — B-Roll 與動態背景(選擇性)
為 B-roll 切換鏡頭、動態投影片背景或片頭/片尾序列生成 AI 影片剪輯:
cd ~/.openclaw/workspace/claude-code-video-toolkit
# 從文字生成 B-roll 剪輯
python3 tools/ltx2.py \
--prompt "Aerial drone shot over a European city at golden hour, cinematic wide angle" \
--output projects/PROJECT_NAME/public/videos/broll-europe.mp4 \
--cloud modal
# 動畫化投影片/截圖(圖片轉影片)
python3 tools/ltx2.py \
--prompt "Gentle particle effects, soft ambient light shifts, very slight camera drift" \
--input projects/PROJECT_NAME/public/images/title-bg.png \
--output projects/PROJECT_NAME/public/videos/animated-title.mp4 \
--cloud modal
# 抽象片頭/片尾背景
python3 tools/ltx2.py \
--prompt "Dark moody abstract background with flowing blue light streaks, bokeh particles, cinematic" \
--output projects/PROJECT_NAME/public/videos/intro-bg.mp4 \
--cloud modal
在 Remotion 組合中使用 <OffthreadVideo>:
<OffthreadVideo src={staticFile('videos/broll-europe.mp4')} />
LTX-2 規則:
- 每個剪輯最多約 8 秒(24fps 下為 193 幀)。預設約 5 秒(121 幀)。
- 寬度/高度必須可被 64 整除。預設:768x512。
- 每個剪輯約 $0.20-0.25,生成時間約 2.5 分鐘。
- 冷啟動約 60-90 秒。後續在已預熱的 GPU 上生成更快。
- 生成的音訊僅為環境音 — 語音和音樂請使用配音/音樂工具。
- 約 30% 的生成可能包含訓練資料造成的偽影(標誌/文字)。使用
--seed重新生成來改變結果。
4e. 說話頭像旁白(選擇性)
先生成主持人的肖像,然後為每個場景動畫化剪輯:
cd ~/.openclaw/workspace/claude-code-video-toolkit
# 1. 生成肖像
python3 tools/flux2.py \
--prompt "Professional presenter portrait, clean style, dark background, facing camera, upper body" \
--width 1024 --height 576 \
--output projects/PROJECT_NAME/public/images/presenter.png \
--cloud modal
# 2. 生成每個場景的旁白剪輯(每個場景一個,不要一個長影片)
python3 tools/sadtalker.py \
--image projects/PROJECT_NAME/public/images/presenter.png \
--audio projects/PROJECT_NAME/public/audio/scenes/01.mp3 \
--preprocess full --still --expression-scale 0.8 \
--output projects/PROJECT_NAME/public/narrator-01.mp4 \
--cloud modal
# 為需要旁白的每個場景重複
SadTalker 規則 — 嚴格遵守:
- 一律使用
--preprocess full(預設crop會輸出方形,寬高比錯誤) - 一律使用
--still(減少頭部晃動,看起來專業) - 一律生成每個場景的剪輯(6-15 秒),絕不生成單一長影片
- 處理時間:在 Modal A10G 上,每 10 秒音訊約需 3-4 分鐘
--expression-scale 0.8使表情保持微妙(範圍 0.0-1.5)
4e. 圖片編輯(選擇性)
從現有圖片創建場景變體:
cd ~/.openclaw/workspace/claude-code-video-toolkit
python3 tools/image_edit.py \
--input projects/PROJECT_NAME/public/images/title-bg.png \
--prompt "Make it darker with red tones, more ominous" \
--output projects/PROJECT_NAME/public/images/problem-bg.png \
--cloud modal
4f. 放大(選擇性)
cd ~/.openclaw/workspace/claude-code-video-toolkit
python3 tools/upscale.py \
--input projects/PROJECT_NAME/public/images/some-image.png \
--output projects/PROJECT_NAME/public/images/some-image-4x.png \
--scale 4 --cloud modal
步驟 5:同步時間
在生成配音後務必執行此步驟。 音訊長度與預估值會有差異。
cd ~/.openclaw/workspace/claude-code-video-toolkit
for f in projects/PROJECT_NAME/public/audio/scenes/*.mp3; do
echo "$(basename $f): $(ffprobe -v error -show_entries format=duration -of csv=p=0 "$f")s"
done
將 demo-config.ts 中每個場景的 durationSeconds 更新為:ceil(實際音訊長度 + 2)。
範例:如果 01.mp3 是 6.8 秒,則將場景 1 的 durationSeconds 設為 9(ceil(6.8 + 2) = 9)。
步驟 6:檢查靜止幀
cd ~/.openclaw/workspace/claude-code-video-toolkit/projects/PROJECT_NAME
npx remotion still src/index.ts ProductDemo --frame=100 --output=/tmp/review-scene1.png
npx remotion still src/index.ts ProductDemo --frame=400 --output=/tmp/review-scene2.png
檢查:文字截斷、動畫時間、旁白畫中畫位置、背景對比度。
步驟 7:渲染
cd ~/.openclaw/workspace/claude-code-video-toolkit/projects/PROJECT_NAME
npm run render
輸出: out/ProductDemo.mp4
組合模式
逐場景音訊
使用帶有 1 秒延遲的逐場景音訊(from={30} = 30 幀 = 1 秒,在 30fps 下):
<Sequence from={30}>
<Audio src={staticFile('audio/scenes/01.mp3')} volume={1} />
</Sequence>
逐場景旁白畫中畫
<Sequence from={30}>
<OffthreadVideo
src={staticFile('narrator-01.mp4')}
style={{ width: 320, height: 180, objectFit: 'cover' }}
muted
/>
</Sequence>
一律使用 <OffthreadVideo>,絕不使用 <video>。 Remotion 需要自己的組件才能實現幀級精確渲染。
轉場
import { TransitionSeries, linearTiming } from '@remotion/transitions';
import { fade } from '@remotion/transitions/fade';
import { glitch } from '../../../lib/transitions/presentations/glitch';
import { lightLeak } from '../../../lib/transitions/presentations/light-leak';
絕對不要從 lib/transitions 的彙總匯入 — 直接從 lib/transitions/presentations/ 匯入自訂轉場。
錯誤恢復
| 問題 | 解決方案 |
|---|---|
| 工具命令失敗並顯示「找不到模組...」 | 從工具包根目錄執行 pip3 install --break-system-packages -r tools/requirements.txt |
| 未設定「MODAL_*_ENDPOINT_URL」 | 檢查 .env 中是否有端點 URL。執行 python3 tools/verify_setup.py |
| SadTalker 輸出為方形/被裁切 | 你忘了 --preprocess full。加上該標誌重新執行 |
| 音訊對場景來說太短/太長 | 重新執行步驟 5(同步時間)並更新設定 |
npm run render 失敗 | 確認你在專案目錄,而非工具包根目錄。先執行 npm install |
| Remotion 中出現「找不到模組」錯誤 | 檢查是否直接從 lib/transitions/presentations/ 匯入自訂轉場 |
| LTX-2 輸出有偽影 | 使用 --seed 重新執行來改變生成結果 |
| 雲端端點逾時 | Modal 冷啟動可能需要 60-90 秒。後續請求會更快 |