remotion-script-writer

Remotion 脚本编写器

将视频目标，以及（可选的）代码库，转化为 Remotion Script JSON——按场景逐一编写的规范，精确到 Remotion Agent 无需追问即可实现。核心原则：脚本是渲染的唯一事实来源——每个时长、元素、动画和旁白台词都必须以数字和精确字符串明确写出，绝不能写「大约 5 秒」或「一些开场文字」。给定相同输入的两个 Agent 必须生成结构完全相同的脚本。

何时使用／何时不使用

• 当输出将通过 Remotion 以编程方式渲染时使用：Web 应用产品演示、带动画代码的编程教程、动态图形作品、数据可视化视频、短视频社交动画。
• 产品视频的概念和节奏尚未确定 → 先运行 skills/creative/product-video；其节奏表将作为本技能的场景列表。
• 真人出镜视频 → 使用 skills/creative/talking-head（Remotion 并非适用工具）。
• 静态图形 → 使用 skills/creative/social-graphics。
• 本技能只编写脚本——React 组件的实现、在 Remotion Studio 中预览和渲染由后续 Remotion 自带的 Agent 技能完成。

规则文件——编写脚本前阅读

• rules/prompt-structure.md — 脚本所依据的输入字段（goal、targetAudience、code、videoType、duration、style、animations、transitions）。将输入整理为输入对象时请阅读。
• rules/script-generation.md — 权威的输出 JSON 结构和生成说明。输出脚本前请阅读；下方的骨架只是摘要，该文件才是规范。
• rules/animation-patterns.md — 经批准的动画／转场词汇及其精确 JSON 格式和时间指南。指定任何 animation 或 transitionToNextScene 值时请阅读；不要使用其中未列出的动画类型。
• rules/scene-templates.md — 常见场景的现成 JSON（标题卡、功能展示、代码演示、数据可视化、结尾／CTA）。场景符合已知模式时请阅读；从模板开始修改。
• examples/product-demo-example.json — 一份完整的脚本示例。请阅读以校准细节粒度。

输入信息

一次性集中询问，只询问缺失的信息（字段名称参照 rules/prompt-structure.md）：

1. goal 和 targetAudience — 视频要实现什么目标，面向谁？
2. videoType — product-demo | coding-tutorial | animation | data-visualization | social-media？
3. duration（秒）和目标平台（据此决定宽度／高度／fps）。
4. code — 如果视频涉及应用或代码，提供代码库路径、仓库 URL 或代码片段。
5. style — 视觉／品牌限制（颜色、字体、Logo；如果有 skills/creative/creative-strategist 风格指南，也请提供）。

优先推断而非询问：根据代码库确定 language；根据平台确定尺寸（默认横屏 1920×1080，竖屏社交视频 1080×1920，fps 为 30）；如果未指定，则根据 style 推断动画／转场偏好。**不要停滞不前：**只要已知 goal、videoType 和 duration，就说明假设并继续。

工作流

1. 分析源材料

如果提供了 code，请探索代码库：找出值得展示的主要功能、用户流程、数据结构和 UI 界面。根据与 goal 的相关性为功能排序——视频展示排名前 3–5 的功能，而非全部内容。如果没有代码，则从用户描述中提取相应列表。

2. 规划场景结构

按 videoType 制定决策规则：

• product-demo → 标题卡 → 问题／背景 → 每个功能各一个场景（选出前 3–5 个）→ 结尾／CTA。
• coding-tutorial → 标题 → 概念铺垫 → 每个代码步骤各一个场景（先展示代码，再进行讲解）→ 总结。
• data-visualization → 标题 → 背景 → 每个图表／洞察各一个场景 → 结论。
• social-media → 开场吸引场景（≤3 秒）→ 1–2 个成果展示场景 → CTA；总时长 ≤60 秒。
• animation → 根据创意概念（或 skills/creative/product-video 的节拍表）推导节拍。

时长计算是强制要求：场景时长加上转场重叠时长必须恰好等于 duration。TransitionSeries 转场会使相邻场景重叠——必须将重叠时长计算在内，不能只把场景时长相加。总时长控制在约 5 分钟以内（渲染性能经验规则）。

3. 完整指定每个场景

为每个场景填写所有字段：sceneNumber、title、durationInSeconds、visuals.background、visuals.elements[]（包括 type、准确的内容字符串、字体、字号、颜色、位置，以及取自 rules/animation-patterns.md 的 animation）、audio.voiceover（实际说出的准确句子——按每秒约 2.5 个单词核实是否符合场景时长），以及 transitionToNextScene。适用时使用 rules/scene-templates.md 中的模板。

4. 汇总素材和技术要求

在 requiredAssets 中列出每个场景引用的所有图像、视频片段、音轨、字体和徽标——不得遗漏任何引用的素材。素材生成不在本任务范围内：标明每项素材由用户提供，或对其进行准确描述；静态图像可通过 skills/creative/image-generation 生成（仓库流水线：docs/creative_cli.py，模型 fal-ai/nano-banana-pro）。列出 remotionPackages（例如，使用转场时需列出 @remotion/transitions）以及任何第三方库。

5. 根据质量标准进行验证，然后交付 JSON

交付脚本和交接说明（见下文）。

必需的输出格式

准确输出一个符合 rules/script-generation.md 中结构的 JSON 对象：

{
  "videoMetadata": {
    "title": "...", "durationInSeconds": 60,
    "width": 1920, "height": 1080, "fps": 30,
    "videoType": "product-demo"
  },
  "scenes": [
    {
      "sceneNumber": 1, "title": "...", "durationInSeconds": 5,
      "visuals": {
        "background": "#RRGGBB or asset ref",
        "elements": [
          { "type": "text|image|code|chart", "content": "exact content",
            "animation": { "type": "<from rules/animation-patterns.md>", "durationInSeconds": 1 } }
        ]
      },
      "audio": { "voiceover": "Exact spoken sentence(s)." },
      "transitionToNextScene": { "type": "<from rules/animation-patterns.md>", "durationInSeconds": 1 }
    }
  ],
  "requiredAssets": { "images": [], "videos": [], "audio": [], "fonts": [], "logos": [] },
  "technicalRequirements": { "remotionPackages": [], "thirdPartyLibraries": [] }
}

JSON 后附上一则简短的 Markdown 交接说明：时长核对（展示场景时长计算）、你作出的 1–3 项假设，以及用户在渲染前必须提供的素材。

质量标准（交付前检查）

• 场景时长加上转场重叠时长必须恰好等于 videoMetadata.durationInSeconds；在交接说明中展示计算过程。
• 每个 animation 和转场 type 都必须存在于 rules/animation-patterns.md 中——不得自行编造类型。
• 每句旁白按每秒约 2.5 个单词计算，都必须符合所在场景的时长；不得出现画面没有旁白或标题说明用途的场景。
• 场景中引用的每项素材都必须出现在 requiredAssets 中；文本元素所用字体必须列出。
• 规范中须明确 Remotion 的正确用法：基于帧的计时使用 useCurrentFrame()；揭示动画的弹簧使用 damping: 200；打字机效果通过字符串切片实现（而非逐字符设置透明度）；随机性必须具有确定性（仅使用 remotion 中的 random()，绝不使用 Math.random()）；为较重的序列设置 premountFor；使用 <Sequence>/<Series>/<TransitionSeries> 进行排序。
• content 字段必须是最终文案，不得使用“此处填写功能描述”之类的占位内容。
• 旁白为自动起草——在交接说明中注明用户可能需要对其进行润色。

集成

• skills/creative/product-video → 输入：产品视频的概念、节拍表和关键帧；每个节拍对应一个场景。
• skills/creative/creative-strategist → 输入：应用于 visuals 和 style 的风格指南（颜色、字体、氛围）。
• skills/creative/original-design → 输入：设计语言简介；每个场景的视觉词汇都必须源自该设计世界。
• skills/creative/image-generation → 生成：列在 requiredAssets.images 中的静态素材。
• skills/creative/social-graphics → 使用：渲染后的静态图像／缩略图来制作帖子素材。
• 下游：Remotion Agent 技能（位于本仓库之外）使用 JSON 来构建组件、预览和渲染。