hyperframes-cli

HyperFrames CLI

HyperFrames CLI 是一个命令行工具，所有操作通过 npx hyperframes 运行。使用前需要 Node.js 22 或更高版本，以及 FFmpeg。

用途

该工具用于围绕 HyperFrames 项目进行脚手架搭建、作品校验、工作室预览、视频渲染、音频转录与语音合成，并帮助排查 HyperFrames 运行环境的问题。

主要能力

• 脚手架：npx hyperframes init 创建项目文件结构、复制媒体、使用 Whisper 转录音频，并安装 AI 编程技能。
• 校验：npx hyperframes lint 对 index.html 及 compositions/ 下的文件进行检查，报告必须修复的错误、应当修复的警告，以及在使用 --verbose 时显示的信息级结果。可发现缺失 data-composition-id、轨道重叠、未注册时间线等问题。
• 预览：npx hyperframes preview 在浏览器工作室中提供服务并自动打开，文件变更时热重载。
• 渲染：npx hyperframes render 输出视频，可控制输出路径、帧率、质量、格式、并行 worker、Docker 与 GPU 等选项。
• 转录：npx hyperframes transcribe 处理音频、视频，也可导入已有的 SRT、VTT 或 openai-response.json。
• 文本转语音：npx hyperframes tts 根据文本生成语音，可使用 --list 查看全部语音。
• 环境排查与维护：doctor 检查环境（Chrome、FFmpeg、Node、内存），browser 管理内置 Chrome，info 查看版本与环境详情，upgrade 检查更新。
• 其他：compositions 列出项目中的作品，docs 打开文档，benchmark 对渲染性能进行基准测试。

使用方式

推荐工作流：

1. 脚手架 — npx hyperframes init my-video
2. 编写 — 编写 HTML 作品（参见 hyperframes 技能）
3. 校验 — npx hyperframes lint
4. 预览 — npx hyperframes preview
5. 渲染 — npx hyperframes render

建议先 lint 后 preview，以便提前发现缺失 data-composition-id、轨道重叠、未注册时间线等问题。

脚手架命令

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	每个 worker 会启动 Chrome
--docker	标志	关闭	可复现输出
--gpu	标志	关闭	GPU 加速编码
--strict	标志	关闭	有 lint 错误时失败
--strict-all	标志	关闭	有错误和警告时都失败

质量建议：迭代时使用 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 "Text here" --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 .    # 对渲染性能进行基准测试

适用场景

适合以 HTML 编写作品并需要校验、预览、渲染为视频的工作流；需要在 CI 或智能体环境中进行非交互式项目搭建；需要转录音频、视频或导入已有字幕；需要生成文本转语音；以及需要诊断 HyperFrames 环境与渲染性能问题时使用。

限制

使用前需要 Node.js 22 或更高版本以及 FFmpeg。渲染失败常见原因包括缺少 FFmpeg、缺少 Chrome 或内存不足。关于收费、价格、平台等更多信息，当前资料暂未提供。