coleam00/hyperframes-ai-video-generation

HyperFrames CLI

所有操作通过 npx hyperframes 执行。需要 Node.js >= 22 和 FFmpeg。

工作流程

1. 脚手架搭建 — npx hyperframes init my-video
2. 编写 — 编写 HTML 合成（参见 hyperframes skill）
3. 代码检查 — npx hyperframes lint
4. 可视化检查 — npx hyperframes inspect
5. 预览 — npx hyperframes preview
6. 渲染 — npx hyperframes render

在预览前先进行代码检查和可视化检查。lint 能捕获缺失的 data-composition-id、重叠轨道和未注册的时间线。inspect 在 headless 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 --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 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。

渲染

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	标志	关	检查错误时失败
--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 .    # 基准测试渲染性能