hyperframes-cli

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

HyperFrames CLI

Everything runs through

npx hyperframes

. Requires Node.js >= 22 and FFmpeg.

所有操作都通过

npx hyperframes

执行。需要 Node.js >= 22 和 FFmpeg。

Workflow

工作流程

Scaffold —
```
npx hyperframes init my-video
```
Write — author HTML composition (see the
```
hyperframes
```
skill)
Lint —
```
npx hyperframes lint
```
Preview —
```
npx hyperframes preview
```
Render —
```
npx hyperframes render
```

Lint before preview — catches missing

data-composition-id

, overlapping tracks, unregistered timelines.

搭建项目 —
```
npx hyperframes init my-video
```
编写内容 — 创作HTML组合（查看
```
hyperframes
```
技能文档）
代码校验 —
```
npx hyperframes lint
```
预览 —
```
npx hyperframes preview
```
渲染 —
```
npx hyperframes render
```

预览前先执行校验——可捕获缺失的

data-composition-id

、轨道重叠、未注册时间线等问题。

Scaffolding

项目搭建

bash

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 --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.

bash

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 --non-interactive       # 跳过提示（适用于CI/代理）

模板包括：

blank

、

warm-grain

、

play-mode

、

swiss-grid

、

vignelli

、

decision-tree

、

kinetic-type

、

product-promo

、

nyt-graph

。

init

命令会创建正确的文件结构、复制媒体文件、使用Whisper转写音频并安装AI编码技能。建议使用该命令而非手动创建文件。

Linting

代码校验

bash

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

Lints

index.html

and all files in

compositions/

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

--verbose

bash

npx hyperframes lint                  # 当前目录
npx hyperframes lint ./my-project     # 指定项目目录
npx hyperframes lint --verbose        # 显示信息级别的检查结果
npx hyperframes lint --json           # 输出机器可读格式

校验

index.html

和

compositions/

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

--verbose

参数查看）。

Previewing

预览

bash

npx hyperframes preview                   # serve current directory
npx hyperframes preview --port 4567       # custom port (default 3002)

Hot-reloads on file changes. Opens the studio in your browser automatically.

bash

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

文件变更时自动热重载。会自动在浏览器中打开工作室界面。

Rendering

渲染

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        # final delivery
npx hyperframes render --format webm                  # transparent WebM
npx hyperframes render --docker                       # byte-identical

Flag	Options	Default	Notes
`--output`	path	renders/name_timestamp.mp4	Output path
`--fps`	24, 30, 60	30	60fps doubles render time
`--quality`	draft, standard, high	standard	draft for iterating
`--format`	mp4, webm	mp4	WebM supports transparency
`--workers`	1-8 or auto	auto	Each spawns Chrome
`--docker`	flag	off	Reproducible output
`--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,

standard

for review,

high

for final delivery.

bash

npx hyperframes render                                # 生成标准MP4
npx hyperframes render --output final.mp4             # 指定输出文件名
npx hyperframes render --quality draft                # 草稿质量（快速迭代）
npx hyperframes render --fps 60 --quality high        # 60帧高质量（最终交付）
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`	开关参数	off	可生成一致的输出结果
`--gpu`	开关参数	off	GPU加速编码
`--strict`	开关参数	off	校验出错时终止渲染
`--strict-all`	开关参数	off	出错或警告时均终止渲染

质量建议： 迭代阶段使用

draft

，评审阶段使用

standard

，最终交付使用

high

。

Transcription

音频转写

bash

npx hyperframes transcribe audio.mp3
npx hyperframes transcribe video.mp4 --model medium.en --language en
npx hyperframes transcribe subtitles.srt   # import existing
npx hyperframes transcribe subtitles.vtt
npx hyperframes transcribe openai-response.json

bash

npx hyperframes transcribe audio.mp3
npx hyperframes transcribe video.mp4 --model medium.en --language en
npx hyperframes transcribe subtitles.srt   # 导入现有字幕
npx hyperframes transcribe subtitles.vtt
npx hyperframes transcribe openai-response.json

Text-to-Speech

文本转语音（TTS）

bash

npx hyperframes tts "Text here" --voice af_nova --output narration.wav
npx hyperframes tts script.txt --voice bf_emma
npx hyperframes tts --list  # show all voices

bash

npx hyperframes tts "Text here" --voice af_nova --output narration.wav
npx hyperframes tts script.txt --voice bf_emma
npx hyperframes tts --list  # 显示所有可用语音

Troubleshooting

故障排查

bash

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

Run

doctor

first if rendering fails. Common issues: missing FFmpeg, missing Chrome, low memory.

bash

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

如果渲染失败，请先运行

doctor

命令。常见问题：缺失FFmpeg、缺失Chrome、内存不足。

Other

其他命令

bash

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

bash

npx hyperframes compositions   # 列出项目中的所有组合
npx hyperframes docs           # 打开文档
npx hyperframes benchmark .    # 基准测试渲染性能