hyperframes-cli

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

HyperFrames CLI

The CLI turns HTML compositions into previews and rendered video. Everything runs through

npx hyperframes

bash

npx hyperframes <command>

Requires Node.js >= 22 and FFmpeg. Run

npx hyperframes doctor

if anything fails.

该CLI可将HTML合成内容转换为预览效果和可渲染视频，所有操作都通过

npx hyperframes

执行。

bash

npx hyperframes <command>

需要Node.js >= 22和FFmpeg环境。如果运行出现任何问题，请执行

npx hyperframes doctor

。

Workflow

工作流

The natural sequence when building a composition:

Scaffold —
```
npx hyperframes init my-video
```
(new projects only)
Write — author HTML composition (see
```
compose-video
```
skill)
Lint —
```
npx hyperframes lint
```
to catch structural errors
Preview —
```
npx hyperframes preview
```
to see it live in the studio
Render —
```
npx hyperframes render
```
to export video

Lint before preview. It catches missing

data-composition-id

, overlapping tracks on the same

data-track-index

, unregistered timelines, and other structural issues that silently produce broken output. A 2-second lint saves minutes debugging a blank screen. Both

preview

and

render

auto-lint, but linting explicitly after editing gives you a chance to fix issues without waiting for the server or renderer to spin up.

制作合成内容的标准流程：

项目初始化 —
```
npx hyperframes init my-video
```
（仅新项目需要）
内容编写 — 创作HTML合成内容（参考
```
compose-video
```
技能）
Lint校验 —
```
npx hyperframes lint
```
排查结构错误
预览 —
```
npx hyperframes preview
```
在工作室中实时查看效果
渲染导出 —
```
npx hyperframes render
```
导出视频

预览前请先执行Lint校验。它可以检测出缺失的

data-composition-id

、相同

data-track-index

下的轨道重叠、未注册的时间线，以及其他会悄无声息导致输出异常的结构问题。2秒钟的Lint校验可以帮你节省数分钟调试黑屏的时间。

preview

和

render

命令都会自动执行Lint，但编辑完成后显式执行Lint可以让你在服务器或渲染器启动前就修复问题，无需等待。

Scaffolding New Projects

新项目初始化

bash

npx hyperframes init my-video                        # interactive wizard
npx hyperframes init my-video --template warm-grain   # pick a template
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 --non-interactive       # skip prompts (CI/agents)

Templates:

blank

warm-grain

play-mode

swiss-grid

vignelli

decision-tree

kinetic-type

product-promo

nyt-graph

init

creates the right file structure, copies media, transcribes audio with Whisper, and installs AI coding skills. Use it instead of creating files by hand — the template includes boilerplate that's easy to forget.

bash

npx hyperframes init my-video                        # 交互式向导
npx hyperframes init my-video --template warm-grain   # 选择指定模板
npx hyperframes init my-video --video clip.mp4        # 导入视频文件
npx hyperframes init my-video --audio track.mp3       # 导入音频文件
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编码技能。建议使用该命令而非手动创建文件——模板中包含了很容易遗漏的样板代码。

Linting

Lint校验

bash

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

Lints

index.html

and all files in

compositions/

. Reports errors (must fix), warnings (should fix), and info (with

--verbose

When to lint:

After writing or editing any composition file — always
Before rendering —
```
render
```
blocks on errors with
```
--strict
```
, but linting first is faster
After timing changes — overlapping clips on the same track are a common mistake

bash

npx hyperframes lint                  # 校验当前目录
npx hyperframes lint ./my-project     # 校验指定项目
npx hyperframes lint --verbose        # 输出信息级检测结果
npx hyperframes lint --json           # 输出机器可读的JSON格式结果，适用于脚本调用

Lint会校验

index.html

以及

compositions/

目录下的所有文件，报告错误（必须修复）、警告（建议修复）和信息级提示（需添加

--verbose

参数）。

适用场景：

编写或编辑任意合成文件之后——务必执行
渲染导出之前——
```
render
```
命令在
```
--strict
```
模式下遇到错误会终止执行，但先执行Lint速度更快
修改时间配置之后——同一轨道下的片段重叠是常见错误

Previewing in the Studio

工作室预览

bash

npx hyperframes preview                   # serve current directory
npx hyperframes preview ./my-project      # specific project
npx hyperframes preview --port 4567       # custom port (default 3002)

Opens the studio in your browser automatically. Hot-reloads on file changes. Run from the project root (directory containing

index.html

bash

npx hyperframes preview                   # 启动当前目录的预览服务
npx hyperframes preview ./my-project      # 启动指定项目的预览服务
npx hyperframes preview --port 4567       # 自定义端口（默认3002）

会自动在浏览器中打开工作室页面，文件变更时支持热重载。请在项目根目录（包含

index.html

的目录）下运行该命令。

Rendering to Video

渲染导出视频

bash

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 -o hd.mp4      # high quality
npx hyperframes render --format webm -o overlay.webm          # transparent WebM
npx hyperframes render --docker -o deterministic.mp4          # reproducible

Flag	Options	Default	Notes
`--output`	path	renders/name_timestamp.mp4	Output file path
`--fps`	24, 30, 60	30	60fps doubles render time
`--quality`	draft, standard, high	standard	Use draft while iterating
`--format`	mp4, webm	mp4	WebM supports transparency
`--workers`	1-8 or auto	auto (half CPU cores, max 4)	Each spawns a Chrome process
`--docker`	flag	off	Byte-identical output across machines
`--gpu`	flag	off	GPU-accelerated encoding
`--strict`	flag	off	Fail on lint errors
`--strict-all`	flag	off	Fail on errors AND warnings

Quality guidance:

```
draft
```
while iterating on timing and layout — fast feedback
```
standard
```
for review and most deliverables
```
high
```
only for final delivery where render time doesn't matter

bash

npx hyperframes render                                        # 导出标准MP4格式
npx hyperframes render --output final.mp4                     # 自定义输出文件名
npx hyperframes render --quality draft                        # 草稿画质，快速迭代
npx hyperframes render --fps 60 --quality high -o hd.mp4      # 高画质60帧导出
npx hyperframes render --format webm -o overlay.webm          # 导出支持透明通道的WebM格式
npx hyperframes render --docker -o deterministic.mp4          # 可复现的一致性导出

参数	可选值	默认值	说明
`--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（CPU核心数的一半，最高4）	每个工作进程对应一个Chrome进程
`--docker`	开关参数	关闭	跨机器导出字节完全一致的结果
`--gpu`	开关参数	关闭	GPU加速编码
`--strict`	开关参数	关闭	遇到Lint错误时终止导出
`--strict-all`	开关参数	关闭	遇到Lint错误或警告时都终止导出

画质建议：

调整时间线和布局时使用
```
draft
```
模式——反馈速度快
```
standard
```
模式适用于审阅和大多数交付场景
仅当渲染时间不敏感的最终交付时使用
```
high
```
模式

Troubleshooting

问题排查

bash

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

Run

doctor

first if rendering fails or produces unexpected results. Common issues:

Missing FFmpeg →
```
brew install ffmpeg
```
Missing Chrome →
```
npx hyperframes browser ensure
```
Low memory → close other apps (each render worker uses ~256MB)

bash

npx hyperframes doctor       # 检查环境（Chrome、FFmpeg、Node、内存、磁盘）
npx hyperframes browser      # 管理内置的Chrome安装
npx hyperframes info         # 查看版本和环境详情
npx hyperframes upgrade      # 检查版本更新

如果渲染失败或输出结果不符合预期，请先执行

doctor

命令。常见问题：

缺失FFmpeg → 执行
```
brew install ffmpeg
```
安装
缺失Chrome → 执行
```
npx hyperframes browser ensure
```
安装
内存不足 → 关闭其他应用（每个渲染工作进程约占用256MB内存）

Other Commands

其他命令

bash

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

bash

npx hyperframes compositions   # 列出当前项目中的所有合成内容
npx hyperframes docs           # 在浏览器中打开官方文档
npx hyperframes benchmark .    # 测试渲染性能