代码生成与渲染
您的任务是将文案摘要转化为 plan.json 并进行渲染。参考项目已经实现了发布视频的语法——您只需提供数据,而不是从头编写视频。
参考项目的精美程度决定了此工具生成的所有视频的精美程度。 因此,强有力的默认做法是:编写 plan.json,不要改动其他任何内容。您为单次运行添加的每一行定制动画,都是无法惠及下一个视频的精美细节,也是渲染失败的新隐患。
文件映射
pitchframe/
├── plan.json ← 场景计划。这就是视频。
├── palette.json ← 提取的颜色。数据,非描述。
├── public/assets/*.png ← 截取的屏幕截图。
├── scripts/
│ ├── extract-palette.mjs ← Tailwind → CSS 变量 → 实时 URL
│ ├── apply-palette.mjs ← 从 palette.json 写入 src/theme.ts
│ └── capture.mjs ← 开发服务器 + Playwright 截图
├── src/
│ ├── Root.tsx ← 注册 LaunchVideo 合成
│ ├── LaunchVideo.tsx ← 将节拍映射到序列。拥有交叉淡入淡出效果。
│ ├── theme.ts ← 已生成。所有颜色在此处解析。
│ ├── lib/
│ │ ├── types.ts ← 计划合约
│ │ └── motion.ts ← 缓动、淡入淡出、点击脉冲、保持漂移
│ ├── components/ ← 背景、光标、焦点覆盖、缩放、面板……
│ └── scenes/
│ ├── TypographyBeat.tsx
│ ├── InteractionBeat.tsx ← 英雄时刻
│ ├── UIBeat.tsx
│ └── CTABeat.tsx
└── output.mp4
编写计划
加载 pitchframe-launch-video 以了解结构和模式。简述:
- 四部分——Setup、Hero、Payoff、CTA。按此顺序。始终如此。
- 恰好一个交互节拍,并且它占据至少 30% 的帧数。
- 时长来自文案摘要中的
thesis_weight,而非默认值。 - 将
video_thesis和hero_moment复制到计划中,以便审查阶段可以检查视频内容是否与主张一致。
确保在渲染前算术正确
一次失败的渲染耗时两分钟;一个节拍漂移的计划需要重新渲染并花费时间才能发现。请每次都手动检查:
- 节拍连续——每个节拍的
frames[0]等于前一个节拍的frames[1]。 - 第一个节拍从 0 开始;最后一个节拍恰好结束于
total_frames。 total_frames === duration_seconds * fps。- 没有排版节拍短于 45 帧。
- 交互节拍 ≥
total_frames的 30%。
理性思考坐标,不要猜测
target_element.coordinates 和 zoom_target 是相对于截图的百分比。它们表明有趣像素所在的位置,焦点偏移 10% 会让英雄镜头对准空白的浏览器边框。
打开截图,找到元素,转换为百分比,然后对照节拍应当展示的内容验证结果。当操作的结果发生在目标之外的位置(例如拖拽的目的地、其他位置更新的字段)时,请将 zoom_target 指向结果,而不是光标触及的物体。
颜色:绝不在计划中,绝不在组件中
theme.ts 由 apply-palette.mjs 从 palette.json 生成。它是唯一写入颜色的地方。
node pitchframe/scripts/extract-palette.mjs # → palette.json
node pitchframe/scripts/apply-palette.mjs # → src/theme.ts
由此产生的规则:
- 绝不在
plan.json中放入颜色。 计划指定哪个词被强调;主题指定强调色是什么。 - 绝不在组件中放入颜色字面量。 如果您需要主题未暴露的某个色调,请向生成器添加派生令牌,以便未来的每个视频也能得到它。
- 绝不要手动编辑
theme.ts。 它会在下次生成时被覆盖。
如果两个产品的视频看起来颜色一样,说明 theme.ts 没有被重新生成。这是首先要检查的事项,然后才能碰其他东西。
渲染
cd pitchframe && npx remotion render LaunchVideo output.mp4
首先进行三项检查,耗时不超一秒,却能避免耗时两分钟的失败渲染:
plan.json解析成功;上述算术成立。- 计划中提到的每个截图都存在于
public/assets/中。交互节拍需要同时包含before_screenshot和after_screenshot。 node_modules存在于pitchframe/中。如果不存在,请先运行npm install。
一个 20 秒的视频预计需要 20–60 秒。
当渲染失败时
在修改任何内容之前,先阅读实际错误。
| 症状 | 原因 | 修复 |
|---|---|---|
Cannot find module '../plan.json' | 脚手架不完整 | 重新运行 npx pitchframe install |
Cannot find name 'ACCENT' 等 | theme.ts 未生成 | 运行 apply-palette.mjs |
| 字体延迟渲染超时 | 离线,或字体不在 Google Fonts 上 | 将 palette.json 中的 fonts.sans 设置为 Inter 并重新生成 |
| 图片解码错误 | 截图损坏或不完整 | 重新捕获该截图 |
| 合成时长不匹配 | total_frames 与节拍不一致 | 修正算术 |
| OOM / Chrome 崩溃 | 截图尺寸过大 | 缩小任何宽度超过约 4000px 的截图;使用 --concurrency=2 |
永远不要通过重写合成来应对渲染失败。修复数据即可。
如果渲染连续失败两次,请停止并保留证据。 保留 plan.json、palette.json 和资产文件,并说明需要查看哪个文件。一次失败但计划可检查的渲染是可恢复的;而一次被“修复”性重写覆盖的渲染则不可恢复。
何时必须修改组件
仅当计划需要节拍组件真正无法表达的内容时。如果您需要修改组件,请遵守三条规则:
- 添加,绝不重写。 新的镜头移动是在
lib/camera.ts的SHOTS中添加一条记录,而不是重构组件——并且必须将其记录在pitchframe-motion-language中,否则永远不会被选用。 - 使用
lib/motion.ts和lib/camera.ts。EASE、EASE_OUT、clickPulse、heldDrift、entranceBlur是标准风格。手写缓动会导致某个节拍看起来像来自不同的视频。弹簧、弹跳和弹性曲线被禁止。恰好只有一个相机系统。 不要在Stage.tsx之外添加perspective或 3D 变换;这个仓库曾有两个相机系统,它们发生了漂移,镜头看起来不再像同一个人拍摄的。 - 保持数据驱动。 您添加的任何内容都必须能从
plan.json的字段访问到。如果触发它的唯一方式是编辑组件,那它就是一次性代码,不属于参考项目。
以下做法永远错误:颜色字面量;产品名称或文案硬编码到组件中;新的顶层合成;更改 1920×1080 / 30fps 的约定;导入动画库。
添加节拍类型几乎总是错误的答案。 模式中有四种节拍,因为发布视频只需要四种。新的节拍类型通常是乔装的功能节拍,一旦模式能表达功能列表,计划就会开始包含它们。
渲染成功后
报告路径和编辑提示:
完成。视频位于 ./pitchframe/output.mp4
如需编辑,只需提出:
"英雄时刻停留更久"
"聚焦发生变化的那个字段"
编辑由 pitchframe-editing 处理,而不是重新运行管道。