Communitygithub.com

HyperFrames CLI 工具

HyperFrames CLI 命令行工具 — 支持 scaffold、lint、validate、preview、render、transcribe、tts、doctor、browser、info、upgrade、compositions、docs、benchmark 等命令。适用于项目初始化、组合检查、预览、渲染、音频转写、语音合成以及环境故障排查等场景。

HyperFrames CLI 工具 是什么?

HyperFrames CLI 是一个功能全面的命令行工具,专为 HyperFrames 视频合成项目提供全生命周期管理。它支持从项目脚手架搭建(`init`)、静态代码检查(`lint`)、浏览器内运行时校验(`validate`,包括 WCAG 对比度审计)、实时预览(`preview`)、最终渲染(`render`)到音频转写(`transcribe`)、文字转语音(`tts`)、环境诊断(`doctor`)等数十种命令。`validate` 命令尤为强大,它能在真实浏览器中定位到合成暂停的特定时间点,截图并采样每个文本元素后的像素,从而计算 WCAG 对比度,同时验证运行时合同(如 `window.__timelines` 注册、`class="clip"` 存在性等),捕捉 lint 无法发现的视觉问题。该工具支持多个渲染质量级别(draft/standard/high)、Docker 可复现输出、GPU 加速编码,并能自动安装 AI 编码技能,大幅降低手工配置负担。运行环境要求 Node.js >= 22 和 FFmpeg。

兼容平台✓Claude Code✓Codex CLI~Cursor
npx skills add https://github.com/johnnyjclin/video-producer/tree/HEAD/.claude/skills/hyperframes-cli

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

HyperFrames CLI

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

工作流程

  1. 脚手架搭建 — npx hyperframes init my-video
  2. 编写 — 编写 HTML 合成(参见 hyperframes 技能)
  3. 静态检查 — npx hyperframes lint(静态检查)
  4. 验证 — npx hyperframes validate(基于浏览器的运行时检查 + 对比度审计)
  5. 预览 — npx hyperframes preview
  6. 渲染 — 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输出路径
--fps24, 30, 603060fps 渲染时间翻倍
--qualitydraft, standard, highstandarddraft 用于迭代
--formatmp4, webmmp4WebM 支持透明通道
--workers1-8 或 autoauto每个工作进程启动 Chrome
--docker标志off可复现输出
--gpu标志offGPU 加速编码
--strict标志offlint 错误时失败
--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 .    # 基准测试渲染性能

相关技能