Communitygithub.com

PITCHFRAME 视频生成与构建部署

生成发布视频的 Remotion 场景计划并渲染为 MP4,仅在计划需要组件无法表达的内容时扩展节拍组件。由 Pitchframe 用于代码生成和渲染步骤。

PITCHFRAME 视频生成与构建部署 是什么?

此技能专为 Pitchframe 工具链设计,负责将用户提供的文案摘要转化为结构化的 `plan.json` 场景计划,并最终通过 Remotion 渲染为 1920x1080、30fps 的 MP4 发布视频。其核心原则是最大程度复用参考项目中的现有组件(TypographyBeat、InteractionBeat、UIBeat、CTABeat),避免任何不必要的自定义动画或组件重写,以确保所有视频拥有统一的高质量视觉风格。技能严格规定了四部分结构(Setup、Hero、Payoff、CTA)以及持续时间、坐标、色彩管理的精确规则,并提供了一套完整的预检查流程来提前发现渲染错误。它还详细说明了失败处理策略:如果渲染失败两次,必须保留现场证据(plan.json、palette.json 等)供审查,而不是盲目修改。此技能适用于任何需要从文案摘要自动化产出高质量产品发布视频的 CI/CD 流程或 AI Agent 工具。

兼容平台~Claude Code~Codex CLI✓Cursor
npx skills add https://github.com/Sachin-pro-dev/PITCHFRAME-push-to-prod/tree/HEAD/skills/pitchframe-remotion

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

代码生成与渲染

您的任务是将文案摘要转化为 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

首先进行三项检查,耗时不超一秒,却能避免耗时两分钟的失败渲染:

  1. plan.json 解析成功;上述算术成立。
  2. 计划中提到的每个截图都存在于 public/assets/ 中。交互节拍需要同时包含 before_screenshot 和 after_screenshot。
  3. 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 和资产文件,并说明需要查看哪个文件。一次失败但计划可检查的渲染是可恢复的;而一次被“修复”性重写覆盖的渲染则不可恢复。

何时必须修改组件

仅当计划需要节拍组件真正无法表达的内容时。如果您需要修改组件,请遵守三条规则:

  1. 添加,绝不重写。 新的镜头移动是在 lib/camera.ts 的 SHOTS 中添加一条记录,而不是重构组件——并且必须将其记录在 pitchframe-motion-language 中,否则永远不会被选用。
  2. 使用 lib/motion.ts 和 lib/camera.ts。 EASE、EASE_OUT、clickPulse、heldDrift、entranceBlur 是标准风格。手写缓动会导致某个节拍看起来像来自不同的视频。弹簧、弹跳和弹性曲线被禁止。恰好只有一个相机系统。 不要在 Stage.tsx 之外添加 perspective 或 3D 变换;这个仓库曾有两个相机系统,它们发生了漂移,镜头看起来不再像同一个人拍摄的。
  3. 保持数据驱动。 您添加的任何内容都必须能从 plan.json 的字段访问到。如果触发它的唯一方式是编辑组件,那它就是一次性代码,不属于参考项目。

以下做法永远错误:颜色字面量;产品名称或文案硬编码到组件中;新的顶层合成;更改 1920×1080 / 30fps 的约定;导入动画库。

添加节拍类型几乎总是错误的答案。 模式中有四种节拍,因为发布视频只需要四种。新的节拍类型通常是乔装的功能节拍,一旦模式能表达功能列表,计划就会开始包含它们。

渲染成功后

报告路径和编辑提示:

完成。视频位于 ./pitchframe/output.mp4

如需编辑,只需提出:
  "英雄时刻停留更久"
  "聚焦发生变化的那个字段"

编辑由 pitchframe-editing 处理,而不是重新运行管道。

相关技能