HyperFrames CLI
所有操作均通过 npx hyperframes 执行。需要 Node.js >= 22 和 FFmpeg。
工作流程
- 脚手架搭建 —
npx hyperframes init my-video - 编写 — 编写 HTML 合成(参见
hyperframes技能) - 静态检查 —
npx hyperframes lint(静态检查) - 验证 —
npx hyperframes validate(基于浏览器的运行时检查 + 对比度审计) - 预览 —
npx hyperframes preview - 渲染 —
npx hyperframes render
lint 捕获静态问题(缺少 data-composition-id、重叠轨道、未注册的时间线)。validate 通过在实际浏览器中定位到暂停合成来捕获运行时/视觉问题(对比度、损坏的叠加层、缺失的资源)。在渲染之前同时运行两者。
验证
npx hyperframes validate # 完整验证(静态 + 对比度 + 合同)
npx hyperframes validate --no-contrast # 快速迭代时跳过 WCAG 对比度审计
npx hyperframes validate --json # 机器可读输出
验证会在暂停的合成中定位到多个时间戳,对页面截图,采样每个文本元素背后的像素以计算 WCAG 对比度,并验证运行时合同(window.__timelines 注册、class="clip" 存在性、有效的 data-* 属性)。在每次渲染前运行它——它成本低廉,并能捕获 lint 无法看到的问题。
脚手架搭建
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 编码技能。请使用它而不是手动创建文件。
静态检查
npx hyperframes lint # 当前目录
npx hyperframes lint ./my-project # 指定项目
npx hyperframes lint --verbose # 信息级别的发现
npx hyperframes lint --json # 机器可读
检查 index.html 和 compositions/ 目录下的所有文件。报告错误(必须修复)、警告(建议修复)和信息(带 --verbose 时)。
预览
npx hyperframes preview # 提供当前目录服务
npx hyperframes preview --port 4567 # 自定义端口(默认 3002)
文件变更时自动热重载。在浏览器中自动打开工作室。
渲染
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 | 每个工作进程启动 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 . # 基准测试渲染性能