video-toolkit

Video Toolkit

根据文本简介创建专业的解说视频。此工具包使用云 GPU 上的开源 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

注意：在使用受管理 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   # Opens browser for authentication

# Deploy each tool — capture the endpoint URL from output
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      # Requires: 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：

## Scene 1: Title (9s, ~17 words)
Build videos with AI. The product name toolkit makes it easy.

## Scene 2: Problem (14s, ~30 words)
The problem statement goes here. Keep it punchy and relatable.

每个场景的字数预算： (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

# Scene 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

# Scene 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

# ... repeat for each scene

说话人： 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 与动态背景（可选）

生成 AI 视频片段，用于 B-roll 过场、动态幻灯片背景或片头／片尾序列：

cd ~/.openclaw/workspace/claude-code-video-toolkit

# B-roll clip from text
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

# Animate a slide/screenshot (image-to-video)
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

# Abstract intro/outro background
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. Generate portrait
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. Generate per-scene narrator clips (one per scene, NOT one long video)
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

# Repeat for each scene that needs a narrator

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(actual_audio_duration + 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"	检查导入路径。自定义组件使用 ../../../lib/ 相对路径
Modal 冷启动超时	空闲后的首次调用需要 30-120 秒。重试一次——第二次调用会使用预热的 GPU

---

费用估算（Modal）

工具	典型费用	备注
Qwen3-TTS	每个场景约 $0.01	GPU 预热后，每个场景约 20 秒
FLUX.2	每张图像约 $0.01	预热时约 3 秒，冷启动时约 30 秒
ACE-Step	约 $0.02-0.05	取决于时长
SadTalker	每个场景约 $0.05-0.20	每 10 秒音频约需 3-4 分钟
Qwen-Edit	约 $0.03-0.15	冷启动约需 8 分钟（25GB 模型）
RealESRGAN	每张图像约 $0.005	速度很快
LTX-2.3	每个片段约 $0.20-0.25	每个 5 秒片段约需 2.5 分钟，A100-80GB

**制作一段 60 秒视频的总费用：**约 $1-3，具体取决于场景和旁白片段。

Modal Starter 套餐：每月 $30 的免费计算额度。应用在空闲时会缩减至零。