Video Forge

video-forge · AI 视频模板工厂

27 个 Remotion 模板 + 合成管线。你（AI agent）的工作流：选模板 → 备素材 → 写 input → 出片。

何时使用

用户要「做一个视频 / 宣传片 / 产品介绍 / 开场动画 / 数据视频 / 标题动效」等成片产出，或要求用这些模板渲染内容。

工作流（三步）

第 1 步：选模板

读 registry.json（不要猜模板）。按以下元数据决策：

进一步看 bestFor / styleTags / pairWith（官方搭配建议）/ textLength（字数约束，超限会被 Zod 拒绝）/ durationRange。

第 2 步：备素材

文字模板无需素材。多图段（template_*）需要图片：

• 已有图片：放到 public/ 下，props 传相对路径（如 demo/my.png）或完整 http URL
• AI 生成（推荐，与模板风格统一）：

node scripts/lumina.mjs generate --model tt-image-2.5 --prompt "<你的提示词>" --size 1536x1024
node scripts/lumina.mjs poll --task-id <返回的任务ID>     # 每 5-10 秒一次直到 success
node scripts/lumina.mjs download --url <result_url> --out public/demo/<名字>.png

用户没有 LUMINA_API_KEY？ 引导：到 https://luminaapis.com 注册充值 → 「API 密钥管理」创建 key → export LUMINA_API_KEY=sk-... 或写入 ~/.lumina-api-key。详见 docs/luminaapis-guide.md。脚本无 key 时也会自动输出此引导。

演示图集（扫地机器人主题 33 张）已内置 public/demo/，可直接跑通全流程。

第 3 步：写 input.json → 出片

{
  "segments": [
    { "template": "TextScalePunch", "props": { "text": "全新发布" } },
    { "template": "template_01", "props": { "images": ["demo/hero-01.png", "demo/hero-02.png", "demo/hero-03.png", "demo/hero-04.png"], "title": "洁净，从未如此简单" } },
    { "template": "TextNumberCountUp", "props": { "number": 987600, "label": "累计清扫", "suffix": "小时" } },
    { "template": "TextFadeByWord", "props": { "text": "让每一条故事 都被看见" } }
  ],
  "bgm": { "path": "public/demo/bgm.mp3", "volume": 0.3 }
}

npm run build:registry                                # registry.json 刷新
node scripts/compose.mjs examples/quick-text.json     # 合成 → out/composed.mp4

命令速查

npm run studio                                        # Remotion Studio 可视化预览（调试模板首选）
npm run render -- <TemplateId> [--props '{"k":"v"}']  # 单模板渲染
node scripts/compose.mjs <input.json> [--out x.mp4]   # 多段合成（2-30 段，可选 BGM）
node scripts/generate-demo-assets.mjs                 # 复刻演示图集
npm test && npm run smoke                             # 测试 + 全模板视觉冒烟

硬约束（违反会渲染失败）

• 视口 1920×1080@30fps；成片时长 = 各模板 durationSec 之和
• props 全部经 Zod 校验：字数/张数超限直接报错，按报错信息调整后重试
• 多图段 images 数量约束见 registry（如 template_07 需 3-12 张，template_10 恰好 2 张）
• 渲染代码确定性：不要在 props 里引入随机数/时间戳
• BGM 音量 0-1；ffmpeg 必须已安装（缺失时 compose 会输出安装指引）

排错

更多：docs/workflow.md（决策细节）、docs/template-reference.md（模板全表）、docs/luminaapis-guide.md（AI 素材生成）。