motion-video-maker

# Motion Video Maker 本技能用于构建结构化讲解动画视频，而不是让 AI 直接输出一份不可维护的随意 HTML。 核心工作流是： `用户输入 -> 拆分分镜与讲述节奏 -> 按解说文本同步 timing -> 生成 movie.json -> Web 预览 -> 自然语言编辑 -> 用户确认 -> 导出 mp4` ## ClawHub 版本说明 - 发布包默认不包含 `node_modules`、Chromium 浏览器二进制和历史导出产物。 - 首次使用先进入 `{baseDir}` 安装依赖；只有在需要导出 mp4 时才安装 Playwright 浏览器。 - 导出 mp4 还需要系统里有 `ffmpeg`；仅做预览和结构编辑时不依赖它。 ```bash cd {baseDir} npm install npx playwright install chromium ``` - 云端 TTS 需要用户自行配置 API key；未配置时可只做 preview，或使用 `system` fallback。 ## 何时使用 - 用户要把一段文字、脚本或 Markdown 做成讲解型动画视频 - 用户要做类似 AE / PR 风格的口播辅助动效、字幕强化或知识讲解卡片 - 用户想先在 Web 页面里预览动效，再导出成视频 - 用户希望后续能继续改文案、调整节奏、换模板，而不是每次重做页面 ## 核心原则 - `movie.json` 是唯一事实来源，不能只改最终 HTML - 一段视频先拆成多个 `scene`，每个 scene 只负责一个讲述重点 - 动效优先服务“讲解清晰度”，不是无目的堆特效 - 文本语义要先映射成合适的版式与动画模板，再生成具体元素 - `scene.durationMs`、元素入场时间和分步出现节奏必须优先根据 `scene.narration` 推导，不能凭感觉平均分配 - 配置引导要先收窄再确认：先帮助用户选内容结构和视觉方向，再进入 TTS 与导出 - 在用户没有明确说“确认导出”“可以导出视频”之前，只允许生成和修改预览，不允许自动导出视频 - 如果用户要接入语音，必须先确认 TTS provider、voice、language、speed 和 fallback，不能默认假设 - 音色必须由用户明确点名确认；如果用户还没选定 voice，只能停留在 `pending`，不能直接开始合成 - 如果用户没有明确说“你来定”，不要擅自替用户选模板、主题或音色 - 本技能的本机 TTS 兜底必须同时兼容 macOS 和 Windows - 优先产出稳定可编辑的讲解视频，再逐步扩展更复杂的 AE 风格动效 ## 目录导航 - `references/movie-schema.md` 定义 `movie.json` 的结构、scene 与 element 字段。 - `references/animation-rules.md` 定义“文本内容 -> 讲解动画”的映射规则。 - `scripts/sync_timings.js` 按 `scene.narration` 自动同步场景时长和动画开始时间。 - `references/template-catalog.md` 定义当前可选模板、主题配色、适用场景与 UI 风格。 - `references/tts-catalog.md` 定义当前支持的 TTS provider、确认要求和兜底规则。 - `references/prompt-patterns.md` 定义从原始文本生成分镜、scene 和节奏的提示模式。 - `scripts/init_project.js` 创建新的独立项目目录与 starter `movie.json`。 - `scripts/validate_movie.js` 校验 `movie.json` 是否满足最小结构要求。 - `scripts/render_preview.js` 根据 `movie.json` 生成可播放的 `preview.html`。 - `scripts/export_video.js` 用浏览器逐帧截图并调用 `ffmpeg` 导出 `.mp4`，必须显式确认。 - `scripts/build_project.js` 一键完成 timing 同步、校验、预览生成；只有显式确认后才导出视频。 - `scripts/list_catalog.js` 列出可用模板、主题与 TTS provider。 - `scripts/configure_tts.js` 先把 TTS provider、language、speed 和 fallback 写入 `movie.json`，并保持 `pending`。 - `scripts/confirm_tts.js` 在用户明确选定 voice 后，把 voice 写入 `movie.json`，并把状态切到 `confirmed`。 - `scripts/synthesize_voice.js` 生成逐 scene 音频。当前支持 MiniMax 和本机朗读兜底；本机兜底兼容 macOS 与 Windows。 - `assets/themes/*.json` 定义主题颜色、字体、背景与高亮色。 - `assets/templates/*.json` 定义预设模板的 UI 风格、舞台样式和推荐主题。 - `samples/example-movie.json` 示例动画工程。 ## 推荐工作流 1. 先读 `references/animation-rules.md`，把用户原文拆成 4 到 8 个讲述节拍。 2. 再读 `references/movie-schema.md`，把每个节拍映射成 `scene`，同时补齐 `scene.narration`。 3. 在 `{baseDir}/projects/<slug>/movie.json` 中写入结构化分镜，并选择合适的 `template`。 4. 运行 `node {baseDir}/scripts/build_project.js {baseDir}/projects/<slug>`。该命令会先同步 narration timing，再生成 `preview.html`。 5. 通过自然语言继续修改某个 scene、元素、文案、时长和动效。 6. 如果用户没指定视觉风格，先按 `references/template-catalog.md` 给出 2 到 4 个模板选项，并明确推荐 1 个；theme 默认跟模板走。 7. 只有当用户明确说想换配色、品牌色或 UI 质感时，才单独展开 theme 选项。 8. 如果用户要接入语音，先按 `references/tts-catalog.md` 确认 provider、language、speed、fallback，先写入 `pending` 的 `audio` 配置。 9. 然后必须把可用 voice 列给用户，等用户明确点名其中一个 voice。 10. 只有在用户明确选定 voice 后，才运行 `node {baseDir}/scripts/confirm_tts.js {baseDir}/projects/<slug> --voice <voice-id> ...`，再运行 `node {baseDir}/scripts/synthesize_voice.js {baseDir}/projects/<slug>`。 11. 只有用户明确确认导出后，才运行 `node {baseDir}/scripts/build_project.js {baseDir}/projects/<slug> --export --confirm-export`。 ## 命令示例 在本技能目录下运行： ```bash cd {baseDir} npm install npx playwright install chromium node scripts/list_catalog.js node scripts/init_project.js demo-video "AI 剪辑讲解" --template creator-pop node scripts/sync_timings.js samples/example-movie.json node scripts/configure_tts.js projects/demo-video --provider minimax --language zh-CN --speed 1.0 --fallback system node scripts/list_tts_voices.js minimax node scripts/confirm_tts.js projects/demo-video --voice "Chinese (Mandarin)_Reliable_Executive" --provider minimax --language zh-CN --speed 1.0 --fallback system node scripts/synthesize_voice.js projects/demo-video node scripts/validate_movie.js samples/example-movie.json node scripts/render_preview.js samples/example-movie.json outputs/example-preview.html node scripts/export_video.js samples/example-movie.json outputs/example.mp4 --confirm node scripts/build_project.js projects/demo-video node scripts/build_project.js projects/demo-video --export --confirm-export ``` ## 结构化生成要求 - 每个 `scene` 必须有稳定的 `id` - 每个 `element` 必须有稳定的 `id` - `scene.narration` 不能为空或应能从当前元素文本推导 - `scene.durationMs` 要真实反映讲解节奏，并且优先根据解说文本自动同步 - 所有元素必须显式给出 `x`, `y`, `w`, `h` - 预览画布固定为 `1280 x 720` - 动效统一写在元素的 `animation` 字段里 - 同一 scene 内不宜同时出现过多入场动画，优先控制信息密度 - 如需完全手动控制 timing，必须把 `scene.timingMode` 设为 `manual` - 如需接入语音，`audio.confirmationStatus` 在用户确认前必须保持 `pending` ## 文本到动画的默认映射 - 金句 / 定义句：大标题 + 强调副标题 + `fade-up` - 步骤说明：标题 + 列表分步出现 + `itemStaggerMs` - 对比内容：左右分栏 + `slide-left` / `slide-right` - 数据结论：大数字或结论卡片 + `pop` - 总结 / 行动号召：收束标题 + 标语 + `fade` / `pop` ## Timing 规则 - 默认以 `scene.narration` 作为 timing 真相来源 - 单个 scene 的总时长必须覆盖该段解说的朗读时长，并留出开场和收尾缓冲 - 标题通常先于正文出现，正文和 bullet 要跟着语义停顿逐步展开 - 列表项的 `itemStaggerMs` 要根据解说内容长度自动调整，不能固定套用同一个值 - 如果某段 narration 太长，优先拆分 scene，而不是强行压缩动画 ## 编辑要求 当用户说“第二段太长”“第三个要点出现快一点”“把结论页更像 AE 的 kinetic typography”时： - 先定位 `scene` - 再定位对应 `element` - 修改 `movie.json` - 重新生成预览 - 不要直接只改 `preview.html` ## 配置引导顺序 当用户还没把配置说全时，优先按这个顺序引导，不要一次把所有问题都堆给用户： 1. 先确认内容目标：这条视频是在讲产品、教程、步骤、案例，还是观点总结。 2. 再确认视觉方向：优先给 2 到 4 个模板选项，并说明推荐理由。 3. theme 默认跟模板走；只有用户明确说“换配色”“更亮一点”“更像品牌视觉”时，才展开 theme。 4. narration 与 timing 优先根据文本自动生成，不把它当成需要用户手调的首轮配置。 5. 如果用户要配音，先确认 provider、language、speed、fallback。 6. 然后列出当前 provider 的可用 voice，让用户点名选择。 7. 最后再问是否导出视频；未确认导出前只给 preview。 建议用“推荐项 + 2 到 3 个备选”的方式提问，而不是开放式追问。只有当用户明确说“你来定”时，才可以直接使用推荐模板和其默认 theme。 ## 视觉配置引导 - 模板是主风格选择，theme 是细化配色和气质的次级选择 - 用户没提视觉风格时，必须至少给出一个推荐模板，并说明为什么适合当前内容 - 如果用户只是说“做一个介绍视频”，优先推荐 `signal-stage` - 如果用户强调教程拆解、案例复盘，优先推荐 `editorial-board` - 如果用户强调短视频感、字幕冲击力、社媒节奏，优先推荐 `creator-pop` - 如果用户强调极简、理性、访谈摘要，优先推荐 `mono-frame` - 如果用户说“你定”，可以直接采用推荐模板和默认 theme，但要在回复里说清楚你替他采用了什么 ## TTS 确认要求 - 当用户说“接语音”“配音”“上 TTS”时，必须先停下来确认 - 必须确认：`provider`、`voice`、`language`、`speed`、`fallbackProvider` - 可选 provider：`microsoft-azure`、`openai`、`minimax`、`doubao`、`system` - 如果用户没有指定，必须先问，不能擅自选定 - 如果用户还没选中 voice，必须先展示可选音色，再等用户点名确认 - 如果用户选择的是当前还未接好适配器的 provider，必须明确告知“现在只能做配置或回退到 `system`，不能假装已经原生接通” - 默认推荐保留 `system` 作为 fallback - `system` fallback 在 macOS 使用 `say`，在 Windows 使用 PowerShell + `System.Speech` ## 导出确认要求 - 默认只构建预览，不自动导出视频 - 只有用户明确表达“确认导出”“可以导出视频”“开始导出”这类意思后，才允许使用导出命令 - 如果用户还在看预览、改文案或调 timing，严禁提前导出 ## 导出说明 - 预览层由 Web 页面实时渲染 - 导出层通过浏览器逐帧截图 + `ffmpeg` 合成 `.mp4` - 当前 MVP 重点支持无音轨讲解动画；后续可扩展旁白、BGM 和字幕烧录