HyperFrames CLI
所有操作均通过 npx hyperframes 执行。需要 Node.js >= 22 和 FFmpeg。
工作流程
- 搭建项目 —
npx hyperframes init my-video - 编写 — 创作 HTML 组合（参见
hyperframes技能） - 代码检查 —
npx hyperframes lint - 可视化检查 —
npx hyperframes inspect - 预览 —
npx hyperframes preview - 渲染 —
npx hyperframes render
先进行 lint 和 inspect，再进行预览。lint 能检查出缺失的 data-composition-id、重叠轨道以及未注册的时间线。inspect 在无头 Chrome 中打开渲染后的组合，遍历时间线，并报告内容溢出气泡/容器或超出画布的问题。
搭建项目
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/代理环境）
模板：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 设置。
代码检查
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 # 代理可读取的结果
npx hyperframes inspect --samples 15 # 更密集的时间线采样
npx hyperframes inspect --at 1.5,4,7.25 # 显式指定关键帧时间戳
应在 lint 和 validate 之后使用此命令，尤其对于包含气泡对话框、卡片、字幕或紧凑排版的组合。它会报告：
- 文本超出最近的视觉容器或气泡
- 文本被自身的固定宽度/高度框截断
- 文本超出组合画布范围
- 子元素溢出裁剪容器
错误应在渲染前修复。警告会呈现给代理审查；添加 --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/名称_时间戳.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 | 遇到 lint 错误时失败 |
--strict-all | 标志 | off | 遇到错误和警告时均失败 |
质量指南： 迭代时使用 draft，审查时使用 standard，最终交付时使用 high。
转录
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
文本转语音
npx hyperframes tts "此处输入文本" --voice af_nova --output narration.wav
npx hyperframes tts script.txt --voice bf_emma
npx hyperframes tts --list # 显示所有可用音色
故障排除
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 . # 基准测试渲染性能