影片工具包
根據文字簡報自主創建專業的說明影片。此工具包使用開源 AI 模型,部署在雲端 GPU(Modal 或 RunPod)上,處理旁白、圖片生成、音樂以及虛擬主持人動畫。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
注意:在配備有受管理 Python 環境的 Debian/Ubuntu 系統上(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(字數 / 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 "場景一的旁白文字。" \
--speaker Ryan --tone warm \
--output projects/PROJECT_NAME/public/audio/scenes/01.mp3 \
--cloud modal
# 場景 02
python3 tools/qwen3_tts.py \
--text "場景二的旁白文字。" \
--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 "要說的文字" \
--ref-audio assets/voices/reference.m4a \
--ref-text "參考音訊的確切逐字稿" \
--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 與動態背景(可選)
生成 AI 影片剪輯,用於 B-Roll 切換畫面、動態投影片背景或介紹/結尾序列:
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
檢查:文字截斷、動畫時間、主持人 PiP 定位、背景對比。
步驟 7:渲染
cd ~/.openclaw/workspace/claude-code-video-toolkit/projects/PROJECT_NAME
npm run render
輸出: out/ProductDemo.mp4
合成模式
每個場景的音訊
使用每個場景的音訊並加上 1 秒延遲(from={30} = 30 幀 = 30fps 下的 1 秒):
<Sequence from={30}>
<Audio src={staticFile('audio/scenes/01.mp3')} volume={1} />
</Sequence>
每個場景的主持人 PiP
<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/ 導入自訂轉場效果。
錯誤排除
| 問題 | 解決方案 |
|---|---|
| 工具命令失敗並顯示「No module named...」 | 從工具包根目錄執行 pip3 install --break-system-packages -r tools/requirements.txt |
| 「MODAL_*_ENDPOINT_URL not configured」 | 檢查 .env 中是否有端點 URL。執行 python3 tools/verify_setup.py |
| SadTalker 輸出為方形/被裁切 | 您忘記加上 --preprocess full。請使用該標誌重新執行 |
| 音訊對於場景來說太短或太長 | 重新執行步驟 5(同步時間)並更新設定檔 |
npm run render 失敗 | 確保您在專案目錄中,而非工具包根目錄。先執行 npm install |
| Remotion 中的「Cannot find module」 | 檢查導入路徑是否正確。確保所有相依套件已安裝 |
設計提醒
- 撰寫旁白腳本時,請記住:展示,不要只是告知。引導 AI 的提示詞,使其產生的視覺效果與旁白相輔相成,而不是直接重複。
- 圖片提示詞應專注於氛圍、光線和構圖,而不是敘事細節。讓旁白來說故事。
- 對於產品示範場景,生成一個有說服力的 UI 截圖,然後使用 LTX-2 對其添加微妙的粒子效果或攝影機漂移 — 這樣就能創建一個看起來昂貴的動畫示範,而無需實際錄製螢幕畫面或編寫 CSS。整個工具包的重點就在於此。