commercial-creator

# 商业广告创作者 一个将产品描述转化为成品视频广告的智能工作流程：创意简报 → 概念 → 脚本 → 对抗性审查的镜头列表 → 样式化的故事板关键帧 → 配音同步动画 → Seedance 2.0 视频生成（带有故事板合成的多镜头窗口）→ 质量控制评判与纠正性再生 → 装配 → 音乐 + 表现力配音混合 → 最终剪辑，带有主题叠加层。FastAPI 服务器驱动它；单文件网页 UI 和 MCP 连接器（用于 Claude Code 等代理）位于其上。 从设计上讲，**人为参与其中**：简报、镜头列表和动画是审批关口，**视频生成在没有明确审批步骤的情况下绝不会花费资金** —— 在 UI 和 MCP 工具中皆如此。 ## 它能产生什么 30–60 秒的广告/预告片（草稿为 480–720p，最终为 1080p），具有： - 多代理规划：摄入策略师、创意总监（3 个概念，每个概念约 2.3 个字/秒的配音脚本），一个 **镜头室**，其中摄影师批评者和编辑批评者并行攻击草稿镜头列表，然后由导演修改 - 故事板关键帧（通过 fal.ai 的 Gemini nano-banana）锁定到样式配方，并带有产品参考图像以标识身份 - 一个 **音频优先的动画**：先生成和测量配音，时间线拉伸以适应，镜头计划将锁定的时间线协调到 Seedance 的 4–15 秒生成窗口（缩放 / 修剪 / 分割 / 多镜头折叠 / 故事板合成窗口） - 通过 fal.ai 的 Seedance 2.0 生成，带有每路由处理（t2v / i2v / 参考合成 r2v / 最后一帧链接），瞬时重试，计费快速失败和可取消的队列轮询 - 一个 6 维视觉质量控制裁判，负责分阶段纠正再生（绝不自动花费）和 **自我改进循环**，将反复出现的故障提炼成持久的提示规则（每个项目经验 + 全局规则） - ElevenLabs v3 表达性配音（每个节拍类型的音频标签，每个品牌的声音由代理选定）+ 生成的音乐床，配音下侧链鸭 - Remotion 渲染的叠加层：主题调色板下三分之一和结束卡，呈现设置（电影 / 平衡 / 信息）选择在摄入时或由简报代理推荐 典型草稿级别成本：**每 30 秒 10–20 美元**（Seedance 占主导地位；LLM/图像/配音为美分）。有关形成该工作流程的研究，请参见 `docs/`。 ## 实时演示 该流程生成的 5 个成品广告 —— 每个广告都是一个产品描述输入，一个视频输出（每个品牌都是虚构的）。作为演示上传到 [The Bearded AI Guy](https://www.youtube.com/@bearded-ai-guy)： ### 🎬 [PocketBrew — 咖啡广告](https://youtu.be/zSaz230ygl4) (45 秒，约 17 美元) 该流程的第一个完整广告：主题样式的下三分之一和结束卡，ElevenLabs 音乐床在配音下。每个镜头根据样式化的故事板从头到尾生成（图像到视频）。 <p> <a href="https://youtu.be/zSaz230ygl4"><img src="assets/pocketbrew_a.jpg" width="49%" alt="PocketBrew — 小木屋场景，带有主题下三分之一"></a> <a href="https://youtu.be/zSaz230ygl4"><img src="assets/pocketbrew_b.jpg" width="49%" alt="PocketBrew — 产品节拍，带有 3 分钟计时器"></a> </p> ### 🛸 [ScoutFly — FOMO 无人机广告](https://youtu.be/ddMKuNCeo-Y) (31 秒，约 15 美元) 视觉裁判在摄像头上的质量控制循环：裁判拒绝了 6 个草稿片段中的 4 个（蓝图主题中的文字模糊），分阶段纠正再生，其反馈拼接成提示，每个修复都通过。那种故障模式随后成为永久主题规则 —— 自我改进循环的起源故事。 <p> <a href="https://youtu.be/ddMKuNCeo-Y"><img src="assets/scoutfly_a.jpg" width="49%" alt="ScoutFly — 蓝图主题飞行路径"></a> <a href="https://youtu.be/ddMKuNCeo-Y"><img src="assets/scoutfly_b.jpg" width="49%" alt="ScoutFly — 无人机屏幕上的呼叫者脸"></a> </p> ### ⌚ [TIMEPIECE — 60 秒流媒体系列预告片](https://youtu.be/irapcuaeudw) (约 27 美元) 为一个不存在的节目制作的精致剧集预告片：自定义电影主题， tick 同步剪辑，自定义提示的管弦乐配乐，以及准确达到 60 秒目标的测量动画。 <p> <a href="https://youtu.be/irapcuaeudw"><img src="assets/timepiece_a.jpg" width="49%" alt="TIMEPIECE — 三个月亮下的悬崖"></a> <a href="https://youtu.be/irapcuaeudw"><img src="assets/timepiece_b.jpg" width="49%" alt="TIMEPIECE — 证据节拍特写"></a> </p> ### ☁️ [SKYSILVER — 动作喜剧预告片](https://youtu.be/neDwwKh56Pw) (31 秒，约 14 美元) 故事板合成路由的工作原理：它的两个蒙太奇是单个 Seedance 生成，按照编号的故事板网格（每个调用多个硬剪辑，场景检测验证），大致降低了按镜头生成的成本一半。 对抗性镜头室进行了 14 次修订，然后才花费一美元 —— 包括一个新的配音同步切出。 <p> <a href="https://youtu.be/neDwwKh56Pw"><img src="assets/skysilver_a.jpg" width="49%" alt="SKYSILVER — 云海中的黄铜飞艇"></a> <a href="https://youtu.be/neDwwKh56Pw"><img src="assets/skysilver_b.jpg" width="49%" alt="SKYSILVER — 白银船长的眨眼"></a> </p> ### ✨ [Wear Your Sparkles — 美容广告](https://youtu.be/s1I4wbIcFQk) (33 秒，约 17 美元) 最具挑战性的照片现实测试（宏观闪光，皮肤，眼睛）：裁判运行了 7 次纠正性再生，以应对闪光物理学幻觉，并提炼了两个关于宏观现实的持久经验教训，现在这些教训应用于该项目中的每个提示。 <p> <a href="https://youtu.be/s1I4wbIcFQk"><img src="assets/wys_a.jpg" width="49%" alt="Wear Your Sparkles — 涂抹器在盖子上捕捉光线"></a> <a href="https://youtu.be/s1I4wbIcFQk"><img src="assets/wys_b.jpg" width="49%" alt="Wear Your Sparkles — 带有产品的闪光眼宏观"></a> </p> ## 要求 - **Python 3.12** （pydub/audioop 兼容性） - **ffmpeg + ffprobe** 在 PATH 上 - **Node.js 18+** （仅用于通过 Remotion 进行最终叠加层渲染；其他阶段无需它） - API 密钥： - `FAL_KEY` — [fal.ai](https://fal.ai) （Seedance 视频 + nano-banana 图像） - `ANTHROPIC_API_KEY` — 规划/评判代理 - `ELEVENLABS_API_KEY` — 配音 + 音乐（可选；如果没有，流程会降级为无声计时） ## 设置 ```bash python -m venv .venv .venv/Scripts/activate # Windows; source .venv/bin/activate elsewhere pip install -r requirements.txt cp .env.example .env # fill in your keys uvicorn commercial_server:app --port 8700 # open http://127.0.0.1:8700 (the web UI) ``` 健康检查：`GET /api/v1/health` 报告缺少的二进制文件/密钥。 > **谷歌云盘/同步文件夹警告：** 如果此文件夹位于同步驱动器上，请将 `REMOTION_BUILD_DIR` 设置为本地路径（例如 `C:/remotion-build/projects`）—— `npm install` 在同步文件系统上失败，渲染阶段在驱动器外，然后复制回来。非同步安装可以设置 `REMOTION_WORK_MODE=project`。 ## 工作流程 ``` 摄入 → 简报* → 脚本 → 镜头* → 参考 → 故事板 → 动画* → 生成† → 装配 → 音频 → 变体 (*人为审批关口) (†明确支出审批) ``` 每个阶段都是一个带有实时日志的作业（SSE 到 UI），并且工件是版本化的，仅追加的 —— 编辑上游工件会使下游的所有内容失效，而不是删除它。 ## Claude Code / MCP 连接器 `mcp_server.py` 将流程公开为键入的 MCP 工具，以便代理可以驱动它端到端： ```bash pip install "mcp[cli]" claude mcp add commercial-creator -- python /absolute/path/to/mcp_server.py ``` 然后，在 Claude Code 中： *"为 \<产品> 创建 30 秒的广告"* —— 代理使用 `run_step` 遍历阶段，通过 `approve_artifact` 遵守审批关口，**无法一步生成视频**：`stage_video_batch` 返回美元估算，只有单独的 `approve_video_jobs` 调用才会花费。 将连接器指向非默认服务器，并使用 `COMMERCIAL_CREATOR_URL`。 ## 代码中的经验教训 - **Seedance 2.0 没有种子输入** —— 可重复性存在于参考图像 + 原样提示中。 一致性来自样式配方关键帧，参考绑定（`@Image1…`）和单生成多镜头窗口。 - **相似性关口**：提供者拒绝 *可检测的照片现实人类面部* 在参考到视频的 **参考图像和视频参考** （面部片段 - 宏观眼睛 - 计数）。相同的图像作为图像到视频的起始帧通过。样式化/动画角色表通过，并通过合成的多镜头生成显著地保持身份。 规划者通过每个镜头的 `face_prominent` 标志和每个项目的 `visual_mode` （照片现实 | 样式化）自动路由所有这些。 - **故事板合成窗口**：编号网格的关键帧（≤3×3，黑色边框，编号徽章）作为 `@Image1` + 计时 `Shot N` 块，可靠地产生一个具有原生硬剪辑的生成 —— 约 1.2 秒/镜头底线，10 秒内 6–7 个镜头是可读的上限。剪辑计数在下载后通过场景检测验证。 - **输出侧“敏感内容”标志是嘈杂的** —— 一个相同的重试是自动的，通常会通过。输入侧相似性拒绝是确定性的 —— 从不重试，而是重新路由。 - **ElevenLabs v3** 不支持 `previous_text`/`next_text`，其稳定性层映射到浮点数（0.5 = 自然）。 *声音* 是质量杠杆：会话标记的声音对 `[excited]` 样式的音频标签做出反应；叙述声音忽略它们。 - **组装策略**：从不连接流复制和重新编码的段；统一每个段编码修剪到编辑时长，在拍摄链接的连接处使用 4 帧交叉淡入。 **📖 [完整图解指南](docs/walkthrough.md)** — 从安装到成品广告，带有每个面板的截图（也作为 Medium 文章发布）。`docs/seedance-commercial-workflow-best-practices.md` 是完整的研究手册；`docs/seedance-commercial-app-implementation-plan.md` 是原始架构规范。 ## 成本和安全防护 - 每个项目 **预算上限**：作业在运行前进行估算；队列拒绝开始工作，如果工作会超出上限（402）计算中的飞行估算。 - 所有视频生成作业都创建为 `needs_approval`，并且在服务器重启时无需自动运行而存活。 - 质量控制裁判分阶段纠正再生，将反馈拼接成提示 —— 审批仍然是明确的，如果两次修复失败，它会升级到人类而不是烧更多的钱。 ## 仓库布局 ``` commercial_server.py FastAPI 应用（端口 8700）：REST + SSE + 静态 UI commercial/ 流程包 agents/ LLM 代理（摄入、导演、分解 + 镜头室、参考、裁判、继续）—— 通过工具强制结构化输出的 Claude adapters.py Seedance 能力描述符 + fal 队列客户端 shot_plan.py 时间合同：动画时间线 -> 生成行 compiler.py 确定性提示编译器（可检查的预支出） storyboard_sheet.py 编号网格合成器，用于合成窗口 keyframes.py/animatic.py/assembly.py/audio_vo.py/audio_final.py/music.py overlay.py/themes.py Remotion 叠加层渲染 + 主题调色板 jobs.py/store.py 审批关口作业队列 + 单写入 JSON 存储 lessons.py 自我改进：质量控制失败 -> 持久提示规则 static/commercial.html 整个 UI（无构建步骤） mcp_server.py 用于 Claude Code 的 MCP 连接器 remotion_template/ Remotion 项目（CommercialFinal 组合） ``` ## 许可证 MIT — 见 `LICENSE`。