Video Toolkit 用于从文本简报创建专业解说视频。工具集使用云端 GPU 上的开源 AI 模型（Modal 或 RunPod）完成配音、图像生成、音乐和数字人动画，Remotion（React）负责合成和渲染。
工具集路径与命令执行 工具集存放在固定路径 ~/.openclaw/workspace/claude-code-video-toolkit。运行任何工具命令前必须先切换到该目录，不要在项目目录内运行工具命令，因为工具会相对于工具集根目录解析路径。
进度报告 所有云端 GPU 工具命令都应添加 --progress json，以获得 stderr 上的结构化 JSON Lines 输出，从而监控任务状态、检测卡住的任务并向用户实时报告进度。支持 --progress json 的工具包括：music_gen.py、qwen3_tts.py、flux2.py、upscale.py、sadtalker.py、image_edit.py、dewatermark.py、ltx2.py、chain_video.py。
长时间运行任务 任何超过 30 秒的工具命令必须使用 exec 配合 yieldMs，以便实时报告进度。包括批量 FLUX 生成、chain_video、SadTalker、音乐生成以及任何多场景流水线。使用 yieldMs:10000 每 10 秒返回控制权，读取 --progress json 输出，查找 "stage":"item"（场景完成）或 "stage":"complete"（全部完成），向用户报告进度后再次轮询。不要使用 bash background:true 后承诺监控，也不要将批处理拆成跨多条消息的单独工具调用。
安装配置 第一步检查当前状态：运行 uv run tools/verify_setup.py，若全部显示 [x] 则跳到快速测试。第二步安装 Python 依赖：uv sync。uv sync 会从 lockfile 创建自己的 .venv/，绕过 Debian/Ubuntu 的受管理 Python 限制（PEP 668），无需 --break-system-packages。若缺少 uv，先安装：curl -LsSf https://astral.sh/uv/install.sh | sh。第三步配置云端 GPU 端点：检查 .env 中是否已有 Modal 端点。若未配置，可运行 uv sync --extra modal、uv run modal setup 进行认证，然后部署各工具并捕获端点 URL。需部署的工具包括 modal-qwen3-tts、modal-flux2、modal-music-gen、modal-sadtalker、modal-image-edit、modal-upscale、modal-propainter、modal-ltx2。LTX-2 部署前需创建 HuggingFace 密钥并接受 Gemma 3 许可证：uv run modal secret create huggingface-token HF_TOKEN=hf_your_read_access_token。将各 URL 添加到 .env，包括 ACEMUSIC_API_KEY、MODAL_QWEN3_TTS_ENDPOINT_URL、MODAL_FLUX2_ENDPOINT_URL、MODAL_MUSIC_GEN_ENDPOINT_URL、MODAL_SADTALKER_ENDPOINT_URL、MODAL_IMAGE_EDIT_ENDPOINT_URL、MODAL_UPSCALE_ENDPOINT_URL、MODAL_DEWATERMARK_ENDPOINT_URL、MODAL_LTX2_ENDPOINT_URL。可选推荐使用 Cloudflare R2 进行可靠文件传输，配置 R2_ACCOUNT_ID、R2_ACCESS_KEY_ID、R2_SECRET_ACCESS_KEY、R2_BUCKET_NAME。第四步验证并快速测试：运行 uv run tools/verify_setup.py，所有工具应显示 [x]；再运行 qwen3_tts 测试确认 GPU 流水线可用。Modal 包含每月 30 美元免费计算额度，典型 60 秒视频成本约 1-3 美元。
创建视频 第一步创建项目：从模板复制到 projects/PROJECT_NAME 并运行 npm install。模板包括 product-demo（营销/解说）、sprint-review、sprint-review-v2（可组合场景）。第二步编写配置：编辑 src/config/demo-config.ts，配置产品信息、场景和音频。场景类型包括 title、problem、solution、demo、feature、stats、cta。时长估算规则：ceil(word_count / 2.5) + 2，生成音频后需调整。第三步编写配音脚本：创建 VOICEOVER-SCRIPT.md，每场景词数预算为 (durationSeconds - 2) * 2.5，-2 用于 1 秒音频延迟加 1 秒填充。第四步生成素材，所有命令必须在工具集根目录运行：背景音乐使用 music_gen.py，默认提供方为 acemusic 云 API（免费密钥），无需 GPU，可回退到 Modal/RunPod；预设包括 corporate-bg、upbeat-tech、ambient、dramatic、tension、hopeful、cta、lofi。配音按场景逐个生成 MP3 文件，不要生成单一文件；说话人包括 Ryan、Aiden、Vivian、Serena、Uncle_Fu、Dylan、Eric、Ono_Anna、Sohee，语气包括 neutral、warm、professional、excited、calm、serious、storyteller、tutorial；也支持语音克隆（需参考录音）。场景图像使用 flux2.py，可用图像预设 title-bg、problem、solution、demo-bg、stats-bg、cta、thumbnail、portrait-bg。视频片段（可选）使用 ltx2.py 生成 b-roll、动画背景或片头片尾，在 Remotion 中用 <OffthreadVideo> 使用。LTX-2 规则：每段最长约 8 秒（24fps 下 193 帧），默认约 5 秒（121 帧）；宽高必须能被 64 整除，默认 768x512；每段约 0.20-0.25 美元，生成约 2.5 分钟；冷启动约 60-90 秒；生成音频仅为环境音；约 30% 的生成可能带有训练数据伪影（logo/文字），可用 --seed 重跑变化。链式视频序列使用 chain_video.py，从上一场景最后一帧生成下一场景，实现视觉连续性；支持从目录批量处理、断点续传、每场景提示词 JSON 文件、从已有片段继续。链式规则：提取场景 N 的最后一帧作为场景 N+1 的 --input；跳过已存在的场景；链接失败时回退到场景图像；用 --prefix 设置输出前缀；每场景约 2.5 分钟、约 0.20-0.25 美元；额外参数传给 ltx2.py。链式序列存在风格漂移风险，LTX-2 约 30% 训练数据污染（动漫/亚洲内容），通用提示词在 5-10 个链式场景内会漂移向动漫美学。应始终使用 --prompts-file 提供每个场景的具体提示词，始终添加 --negative-prompt 排除不想要的风格，如 --negative-prompt "anime, manga, asian, cartoon, illustration, watermark, text, logo"，每个提示词应包含强风格锚点。链式命令需使用 exec 配合 yieldMs 实时报告进度，不要拆成逐场景工具调用。数字人旁白（可选）：先用 flux2.py 生成主持人肖像，再用 sadtalker.py 按场景生成旁白片段。