HyperFrames CLI
所有操作都通过 npx hyperframes 运行。需要 Node.js >= 22 和 FFmpeg。
工作流
- Scaffold(脚手架) —
npx hyperframes init my-video - 编写 — 编写 HTML 合成文件(参见
hyperframes技能) - Lint(检查) —
npx hyperframes lint - 视觉检查 —
npx hyperframes inspect - 预览 —
npx hyperframes preview - 渲染 —
npx hyperframes render
在预览前执行 lint 和 inspect。lint 会捕获缺失的 data-composition-id、重叠的轨道以及未注册的时间轴。inspect 会在无头 Chrome 中打开渲染后的合成,扫描时间轴,并报告文本溢出气泡/容器或画布的问题。
Scaffold(脚手架)
npx hyperframes init my-video # 交互式向导
npx hyperframes init my-video --example warm-grain # 选择一个示例
npx hyperframes init my-video --video clip.mp4 # 带视频文件
npx hyperframes init my-video --audio track.mp3 # 带音频文件
npx hyperframes init my-video --example blank --tailwind # 使用 Tailwind v4 浏览器运行时
npx hyperframes init my-video --non-interactive # 跳过提示(CI/agent 使用)
模板:blank、warm-grain、play-mode、swiss-grid、vignelli、decision-tree、kinetic-type、product-promo、nyt-graph。
init 会创建正确的文件结构、复制媒体文件、使用 Whisper 转录音频,并安装 AI 编码技能。请使用它而不是手动创建文件。
当使用 --tailwind 时,在编辑类或主题令牌之前调用 tailwind 技能。该脚手架通过浏览器运行时使用 Tailwind v4.2,而不是 Studio 的 Tailwind v3 设置。
Lint(检查)
npx hyperframes lint # 当前目录
npx hyperframes lint ./my-project # 指定项目
npx hyperframes lint --verbose # 信息级别发现
npx hyperframes lint --json # 机器可读
检查 index.html 和 compositions/ 目录下的所有文件。报告错误(必须修复)、警告(应该修复)和信息(使用 --verbose)。
视觉检查
npx hyperframes inspect # 检查时间轴上的渲染布局
npx hyperframes inspect ./my-project # 指定项目
npx hyperframes inspect --json # agent 可读的发现结果
npx hyperframes inspect --samples 15 # 更密集的时间轴扫描
npx hyperframes inspect --at 1.5,4,7.25 # 指定关键帧时间戳
在 lint 和 validate 之后使用此命令,特别是对于包含对话气泡、卡片、字幕或紧凑排版的合成。它会报告:
- 文本超出最近的视觉容器或气泡
- 文本被其自身的固定宽度/高度框裁剪
- 文本超出合成画布
- 子元素逃离裁剪容器
错误应在渲染前修复。警告提供给 agent 审查;添加 --strict 可以将警告也视为失败。默认情况下,重复的静态问题会被折叠,以便 JSON 输出保持紧凑,适合 LLM 上下文窗口。如果溢出是入场/出场动画的设计需要,请在元素或祖先上标记 data-layout-allow-overflow。如果某个装饰性元素不应被审计,请标记 data-layout-ignore。
npx hyperframes layout 仍然可用,作为同一视觉检查过程的兼容别名。
预览
npx hyperframes preview # 提供当前目录服务
npx hyperframes preview --port 4567 # 自定义端口(默认 3002)
文件更改时热重载。会自动在浏览器中打开 Studio。
当将项目交还给用户时,请使用 Studio 项目 URL,而不是源 index.html 路径:
http://localhost:<port>/#project/<project-name>
使用预览输出中的实际端口和项目目录名称。例如,在 codex-openai-video 目录中执行 npx hyperframes preview --port 3017 后,应报告 http://localhost:3017/#project/codex-openai-video。
将 index.html 仅作为源代码上下文。将其链接为实现文件是可以的,但不要将其标记为项目或预览界面。
渲染
npx hyperframes render # 标准 MP4
npx hyperframes render --output final.mp4 # 命名输出
npx hyperframes render --quality draft # 快速迭代
npx hyperframes render --fps 60 --quality high # 最终交付
npx hyperframes render --format webm # 透明 WebM
npx hyperframes render --docker # 字节一致
| 标志 | 选项 | 默认值 | 说明 |
|---|---|---|---|
--output | 路径 | renders/name_timestamp.mp4 | 输出路径 |
--fps | 24, 30, 60 | 30 | 60fps 使渲染时间翻倍 |
--quality | draft, standard, high | standard | draft 用于迭代 |
--format | mp4, webm | mp4 | WebM 支持透明通道 |
--workers | 1-8 或 auto | auto | 每个 worker 会启动一个 Chrome 实例 |
--docker | 标志 | 关闭 | 可复现的输出 |
--gpu | 标志 | 关闭 | GPU 加速编码 |
--strict | 标志 | 关闭 | lint 错误时失败 |
--strict-all | 标志 | 关闭 | 错误和警告都失败 |
--variables | JSON 对象 | — | 覆盖在 data-composition-variables 中声明的变量值 |
--variables-file | 路径 | — | 包含变量值的 JSON 文件(替代 --variables) |
--strict-variables | 标志 | 关闭 | 对 --variables 中未声明的键或类型不匹配时渲染失败 |
质量指导: 迭代时使用 draft,审阅时使用 standard,最终交付时使用 high。
参数化渲染: 合成文件在 <html> 根元素上使用 data-composition-variables 声明其变量——这是一个 JSON 声明数组(每个条目包含 {id, type, label, default}),定义了模式。内部脚本通过 window.__hyperframes.getVariables() 读取解析后的值。CLI 的 --variables '{"title":"Q4 Report"}' 是一个以 id 为键 的 JSON 对象,用于覆盖声明的默认值以进行一次渲染;缺失的键会回退,因此同一个合成文件在开发预览和生产环境中运行不变。(子合成宿主也可以使用 data-variable-values 按实例覆盖——相同对象形状,作用域限定为子合成的一次挂载。完整模式请参见 hyperframes 技能。)
资源预处理
npx hyperframes tts、transcribe 和 remove-background 会生成资源(旁白音频、单词级转录、透明视频),这些资源会被放入合成中。每个命令在首次运行时都会下载自己的模型。有关语音选择、Whisper 模型规则(.en 翻译非英语的陷阱)、输出格式选择(VP9 alpha WebM 与 ProRes)以及 TTS → 转录 → 字幕链,请调用 hyperframes-media 技能。
问题排查
npx hyperframes doctor # 检查环境(Chrome、FFmpeg、Node、内存)
npx hyperframes browser # 管理捆绑的 Chrome
npx hyperframes info # 版本和环境详情
npx hyperframes upgrade # 检查更新
如果渲染失败,首先运行 doctor。常见问题:缺少 FFmpeg、缺少 Chrome、内存不足。
其他
npx hyperframes compositions # 列出项目中的合成
npx hyperframes docs # 打开文档
npx hyperframes benchmark . # 基准测试渲染性能