hyperframes-cli

HyperFrames CLI

所有操作都通过 npx hyperframes 执行。需要 Node.js >= 22 和 FFmpeg。

工作流

1. 搭建脚手架 — npx hyperframes init my-video
2. 编写 — 编写 HTML 合成内容（参见 hyperframes skill）
3. Lint — npx hyperframes lint
4. 视觉检查 — npx hyperframes inspect
5. 预览 — npx hyperframes preview
6. 渲染 — npx hyperframes render

在预览之前先运行 lint 和 inspect。lint 会检查是否缺少 data-composition-id、轨道是否重叠，以及时间线是否已注册。inspect 会在无头 Chrome 中打开渲染后的合成内容，遍历时间线，并报告文本是否溢出气泡／容器或画布。

搭建脚手架

npx hyperframes init my-video                        # interactive wizard
npx hyperframes init my-video --example warm-grain   # pick an example
npx hyperframes init my-video --video clip.mp4        # with video file
npx hyperframes init my-video --audio track.mp3       # with audio file
npx hyperframes init my-video --example blank --tailwind # with Tailwind v4 browser runtime
npx hyperframes init my-video --non-interactive       # skip prompts (CI/agents)

模板：blank、warm-grain、play-mode、swiss-grid、vignelli、decision-tree、kinetic-type、product-promo、nyt-graph。

init 会创建合适的文件结构、复制媒体、使用 Whisper 转录音频，并安装 AI 编码技能。请使用它，而不要手动创建文件。

使用 --tailwind 时，请先调用 tailwind skill，再编辑类或主题令牌。脚手架通过浏览器运行时使用 Tailwind v4.2，而不是 Studio 的 Tailwind v3 配置。

Lint

npx hyperframes lint                  # current directory
npx hyperframes lint ./my-project     # specific project
npx hyperframes lint --verbose        # info-level findings
npx hyperframes lint --json           # machine-readable

对 index.html 和 compositions/ 中的所有文件运行 lint。报告错误（必须修复）、警告（应修复）和信息（使用 --verbose 查看）。

视觉检查

npx hyperframes inspect                 # inspect rendered layout over the timeline
npx hyperframes inspect ./my-project    # specific project
npx hyperframes inspect --json          # agent-readable findings
npx hyperframes inspect --samples 15    # denser timeline sweep
npx hyperframes inspect --at 1.5,4,7.25 # explicit hero-frame timestamps

在 lint 和 validate 之后使用此命令，尤其适用于包含对话气泡、卡片、字幕或紧凑排版的合成内容。它会报告：

• 文本超出最近的视觉容器或气泡
• 文本被自身固定宽度／固定高度的框裁切
• 文本超出合成画布
• 子元素超出裁切容器

渲染前应修复错误。警告会显示出来供 Agent 检查；添加 --strict 也可让警告导致失败。默认会合并重复的静态问题，让 JSON 输出在大模型上下文窗口中保持精简。如果溢出是入场／退场动画的有意设计，请在元素或其祖先上添加 data-layout-allow-overflow。如果装饰元素不应接受审查，请为其添加 data-layout-ignore。

npx hyperframes layout 仍可作为兼容性别名，用于执行相同的视觉检查。

预览

npx hyperframes preview                   # serve current directory
npx hyperframes preview --port 4567       # custom port (default 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                                # standard MP4
npx hyperframes render --output final.mp4             # named output
npx hyperframes render --quality draft                # fast iteration
npx hyperframes render --fps 60 --quality high        # final delivery
npx hyperframes render --format webm                  # transparent WebM
npx hyperframes render --docker                       # byte-identical

标志	选项	默认值	备注
--output	path	renders/name_timestamp.mp4	输出路径
--fps	24, 30, 60	30	60fps 会使渲染时间翻倍
--quality	draft, standard, high	standard	迭代时使用 draft
--format	mp4, webm	mp4	WebM 支持透明度
--workers	1-8 or auto	auto	每个工作进程都会启动一个 Chrome
--docker	flag	off	可复现的输出
--gpu	flag	off	GPU 加速编码
--strict	flag	off	遇到 lint 错误时失败
--strict-all	flag	off	遇到错误和警告时均失败
--variables	JSON object	—	覆盖 data-composition-variables 中声明的变量值
--variables-file	path	—	包含变量值的 JSON 文件（--variables 的替代方式）
--strict-variables	flag	off	--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 skill。）

资源预处理

npx hyperframes tts、transcribe 和 remove-background 会生成可放入组合中的资源（旁白音频、逐词转录文本、透明视频）。每个命令首次运行时都会下载自己的模型。有关语音选择、whisper 模型规则（.en 会将非英语文本翻译成英语这一易错点）、输出格式选择（VP9 alpha WebM 或 ProRes），以及 TTS → 转录 → 字幕流程，请调用 hyperframes-media skill。

故障排除

npx hyperframes doctor       # check environment (Chrome, FFmpeg, Node, memory)
npx hyperframes browser      # manage bundled Chrome
npx hyperframes info         # version and environment details
npx hyperframes upgrade      # check for updates

如果渲染失败，请先运行 doctor。常见问题：缺少 FFmpeg、缺少 Chrome、内存不足。

其他

npx hyperframes compositions   # list compositions in project
npx hyperframes docs           # open documentation
npx hyperframes benchmark .    # benchmark render performance