动态推广视频协议 (Motion Promo Protocol)
概述
此技能呈现的是真实产品的动态、广告级推广视频——不是屏幕录制,也不是模拟图。它会在无头浏览器中驱动实际应用,针对演示环境运行,捕获每个屏幕的干净截图,然后在其上合成运动设计剪辑:动态排版、电影推近、追踪变焦的聚光灯高亮、移动端屏幕手机边框、富有节奏的场景切换以及背景音乐。输出为 16:9 主版本和 9:16 竖版。
它是 launch-feature 的渲染对应角色:launch-feature 编写 video-script.md(剧本/节拍散文);motion-promo 将节拍列表转化为最终带配乐的成品视频。当两者同时运行时,将它们串联起来——launch-feature 脚本 → motion-promo 节拍。
为什么选择 HyperFrames (HTML→MP4) 而非屏幕录制: 它确定、可重复运行、品牌可控,并且避免了捕获实时导航的失败模式(见规则)。应用仅用于生成截图 + 设计令牌;所有动画都是自主创作的。
何时使用
- 着陆页/销售页需要产品演示或主导视频。
- 宣布新功能,希望获得渲染好的视频而不仅仅是脚本。
- 拥有包含真实数据的演示/沙箱租户。
不要用于:对保真度要求不高的内部操作指南(原始屏幕录制更便宜),或者没有可运行演示环境的应用。
前提条件与密钥
无需 API 密钥/密钥。 HyperFrames render 是无密钥的(本地 HTML→MP4),字体(Google Fonts)和默认音乐(incompetech)均为公开 URL。唯一的凭据是目标应用的演示登录信息,它存在于目标仓库的 promo.config.mjs 中——绝不在本技能中。身份验证是可插拔的配方:authInject() 返回要注入的值(localStorage 中的令牌、cookie、API 密钥、多步骤租户选择),或 authFlow(page) 驱动交互式登录界面(Azure AD / Entra、Okta、Google SSO),引擎会快照会话(localStorage + sessionStorage + cookies,包括 HttpOnly)。SSO 凭据来自环境变量而非文件。无头浏览器无法通过交互式 MFA——请使用免 MFA 的演示账户(条件访问例外)或应用密码。
系统依赖(由您安装——本技能无法安装): Node 20+、系统 Chrome (google-chrome/Chromium)、ffmpeg + ffprobe。需要网络出口以获取字体/音乐。
自动/按需依赖: hyperframes 通过 npx 按需获取(无需预安装)。puppeteer-core 是脚手架化的 npm 依赖项——它使用系统 Chrome,不会下载 Chromium。
设置: 将 templates/ 模板文件架到 video/<slug>/ 目录下(包含 hyperframes.json;meta.json 由 compose-gen 生成),将 gitignore 重命名为 .gitignore,然后运行 npm install 和 npm run preflight(验证 Chrome、ffmpeg/ffprobe 和 puppeteer-core;如果缺失任何一个会输出错误)。逐步运行管道或直接 npm run build。
- 目标应用的一个可运行演示/沙箱。
输入
所有项目特定的内容都位于目标仓库中,绝不在此技能中:
promo.config.mjs——约定文件(参见templates/promo.config.example.mjs)。包含应用 URL/服务方式、身份验证配方、演示账户/租户、输出路径和音乐偏好。设计令牌会自动提取(步骤 2),但可在此处覆盖。beats.json——有序镜头列表(参见templates/beats.schema.json)。每个节拍包含:一个屏幕(路由或捕获的静态截图)+ 可选的高亮目标 + 标注文案 + 视口(桌面/移动端)。
将这两个文件从 templates/ 模板架放到目标仓库的 video/<slug>/ 目录下。
协议
在目标仓库的 video/<slug>/ 目录下工作。每个步骤都有验证环节。
0. 修复演示数据(首先执行此步骤——它决定视频成败)
演示/沙箱数据通常已过时或归零(当前期间未付费的发票、空的漏斗),这在“自动运行”的文案旁边表现为 “R$0 收入”——完全偏离信息主题。在捕获之前,编写一个幂等的、相对当前日期的种子数据,让每个节拍都显示健康的数字(参见规则 → 演示数据为零)。通过查询每个节拍将显示的指标进行验证。
1. 在允许 CORS 的来源上为应用提供服务,指向演示 API
构建/启动应用,指向演示 API。服务来源必须在 API 的 CORS 白名单中,否则每个数据请求都会被阻止,屏幕渲染为空(参见规则 → CORS 来源)。探测 API 的白名单,并在允许的端口上提供服务。验证:深层路由返回 200,且从该来源发出的已验证 /api/... 请求返回 2xx。
2. 提取目标应用的设计系统
针对已启动、已验证的应用运行 templates/engine/extract-design.mjs。它会采样计算样式(页面背景、按钮/链接的主色/强调色、标题 + 等宽字体族、圆角)→ design.tokens.json。这些内容作为 CSS 变量供给合成,使动态覆盖层、强调色和字体自动匹配应用的品牌。如果采样的令牌有误,请在 promo.config 中审查并覆盖。
3. 按节拍捕获干净截图
运行 templates/engine/capture.mjs。它会进行身份验证(通过配置的 authInject 配方),以每个节拍的视口导航到其路由,等待真实数据加载完成(不仅仅是网络空闲——参见规则),并将截图保存到 assets/<beat>.png。验证每个截图显示已加载的内容(大小 > 约 10 KB,抽查目标元素是否存在)。
4. 定义节拍 + 生成合成
填写 beats.json(路由/截图、高亮 {x,y,w,h,label} 以截图像素坐标表示——或 {selector,label,padding?},由 capture.mjs 自动测量,优先于手动调整的坐标;标注 {kicker,headline,sub};视口;持续时间)。运行 templates/engine/compose-gen.mjs → 从 templates/composition.html 生成 index.html,注入令牌和节拍。保持简洁有力:每个节拍 3–5 秒,硬切,每个节拍一个想法。
5. 获取免费音乐曲目
运行 templates/engine/fetch-music.mjs → assets/music.mp3。默认来源为 CC-BY (incompetech);CC-BY 需要署名(请记录在 LP 描述中)。如果可能,优先使用项目提供/CC0 的曲目。
6. 渲染
npx hyperframes render → 静音 MP4。首先运行 hyperframes lint / inspect;将画布外装饰/退出动画溢出视为噪音,真正的文字裁剪则需要修复。
7. 检查帧 + 修复高亮对齐
提取每次推近的开始和结束时的帧并进行肉眼检查。头号缺陷:聚光灯高亮在变焦过程中偏离目标——因为高亮框必须是缩放容器的子元素(参见规则 → 高亮跟踪)。同时验证:没有空白/加载中画面,移动端屏幕整齐地放置在手机框内,文案清晰可辨。
8. 混入音乐
运行 templates/engine/mux.mjs → 最终带配乐的 MP4(loudnorm、淡入淡出、-shortest)。验证输出包含音频流且与视频时长匹配。
9. 生成 9:16 竖版
mux.mjs --reframe 生成 1080×1920 竖版。不要居中裁剪(否则会切掉底部固定的标注)——应使用模糊信箱格式保留整个画面;移动端节拍已居中放置。
规则(来之不易——请勿重蹈覆辙)
- 高亮跟踪。 在推近过程中,屏幕上的聚光灯/高亮矩形必须是在截图像素坐标空间中应用
scale变换的同一元素的子元素。作为兄弟元素,它会在图像缩放时保持固定,从而导致在整个镜头中偏离目标。 - 演示数据为零。 当前期间通常未付费或为空。使用幂等的种子数据(确定性 ID,先删后插)并相对于
current_date进行修复,使其每个期间都能自我修复。 - CORS 来源。 本地服务的应用调用已部署的演示 API 属于跨域行为。请在 API 允许的来源上提供服务(探测它)——绝不要通过禁用浏览器 Web 安全来绕过此问题。
- 等待真实数据。
networkidle2可能在应用的数据请求到达之前就解析完成→ 你会捕获到加载画面。在屏幕截图之前,还要额外等待成功的/api/...响应(或目标内容选择器)。 - HyperFrames 优于实时捕获。 CDP screencast 在视觉上静态的页面上会停止发送帧,且运行帧率低于标称值;在 HTML(GSAP)中创作可避免这两个问题。如果必须录制实时内容,请抖动光标并以有效帧率编码。
- 音乐许可。 CC-BY (incompetech/Kevin MacLeod) 需要在 LP 描述中注明出处;CC0 (Pixabay 等) 则不需要。切勿将未授权的抓取片段发布到公开页面。
- 如果片段具有不同的帧率,请使用滤镜进行拼接,而不是解复用器——解复用器会静默地丢弃帧。
设计系统提取(无关品牌的品牌化)
合成本身是品牌中性的;extract-design.mjs 从目标应用本身填充其 CSS 变量:--bg(页面背景)、--accent(主色/链接颜色)、--fg(标题颜色)、--font-hero / --font-mono(计算字体族)、--radius。这正是同一个技能能为任何应用生成品牌推广视频的原因——无需手动选择令牌。请始终审查采样的令牌——低对比度或临时颜色有时会采样错误;在 promo.config.design 中覆盖。
错误
- 应用无法在无头模式下进行身份验证 → 配置的
authInject配方有误;请在首次导航之前验证令牌是否正确存储在localStorage/cookies 中。 - 屏幕渲染为空 → 未处理 CORS 来源(步骤 1)或等待数据规则(规则)遗漏。
- 渲染时出现画布外错误 → 真正的文字裁剪需要更小的字体/换行;装饰/退出动画溢出是噪声。
- 高亮未对齐 → 它不是缩放容器的子元素(规则)。
与营销者角色的协作
使用营销者角色负责文案:每个节拍的引文、标题和价值定位应遵循项目语气(launch-feature 的 voice.md / marketer-hooks.md,如果存在)。屏幕上的文案保持为节拍加一个短标题再加一行副标题。