video-forge

# video-forge · AI 视频模板工厂 27 个 Remotion 模板 + 合成管线。你（AI agent）的工作流：**选模板 → 备素材 → 写 input → 出片**。 ## 何时使用 用户要「做一个视频 / 宣传片 / 产品介绍 / 开场动画 / 数据视频 / 标题动效」等成片产出，或要求用这些模板渲染内容。 ## 工作流（三步） ### 第 1 步：选模板 读 `registry.json`（**不要猜模板**）。按以下元数据决策： | 场景 | 首选模板 | |---|---| | 强主张开场 | TextScalePunch / template_01（标题+多图） | | 数据亮点 | TextNumberCountUp / template_complex | | 情感收尾 | TextFadeByWord | | 章节转承 | TextSlideIn / TextRollUp | | 对比概念 | TextFlip3D | | 话题密度 | TextTickerScroll（横向）/ TextVerticalMarquee（纵向） | | 口播/叙事 | TextTypewriter / TextHandwrite | | 科技/悬念 | TextGlitch / TextScramble | | 复古氛围 | TextVHS / TextNeonFlicker | | 金句引用 | TextQuote | | 清单卖点 | InfoBullets | | 节奏转场 | TextCountdown | | 加载/进度 | InfoProgress | | 片尾转化 | EndCardCTA | | 多图叙事 | template_02（高级感）/ template_03（长篇）/ template_08（图卡） | | 产品矩阵 | template_07（点阵）/ template_09（图片扩展）/ template_10（双图推拉） | 进一步看 `bestFor` / `styleTags` / `pairWith`（官方搭配建议）/ `textLength`（字数约束，超限会被 Zod 拒绝）/ `durationRange`。 ### 第 2 步：备素材 文字模板无需素材。多图段（template_*）需要图片： - **已有图片**：放到 `public/` 下，props 传相对路径（如 `demo/my.png`）或完整 http URL - **AI 生成**（推荐，与模板风格统一）： ```bash 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 → 出片 ```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 } } ``` ```bash npm run build:registry # registry.json 刷新 node scripts/compose.mjs examples/quick-text.json # 合成 → out/composed.mp4 ``` ## 命令速查 ```bash 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 会输出安装指引） ## 排错 | 症状 | 处理 | |---|---| | 下载 403 | result_url 必须带浏览器 UA（lumina.mjs 已内置；自写脚本注意） | | 提交 502 | 域名瞬时故障，lumina.mjs 自动降级重试；持续失败换模型 | | composition id 报错 | 输入模板 id（带下划线原样），工具自动转换，不要手动改 | | 图片路径错误 | props 里 public/ 下的相对路径不带 `public/` 前缀 | 更多：`docs/workflow.md`（决策细节）、`docs/template-reference.md`（模板全表）、`docs/luminaapis-guide.md`（AI 素材生成）。