itgoyo/hermes-skills

HyperFrames CLI

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

工作流程

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

预览前先检查 — 可捕获缺失的 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（自动输出到 renders/）
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	每个 workers 启动一个 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 "此处文本" --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、内存不足。

陷阱

--out 路径必须是目录，而不是文件名

npx hyperframes render --out renders/output.mp4 → ✗ 错误：“不是目录” npx hyperframes render → ✅ 自动输出到 renders/name_timestamp.mp4 使用 --output（而不是 --out）指定命名文件路径。

index.html 根时间线必须匹配子合成的 data-composition-id

如果 index.html 只包含 data-composition-src 引用（没有内联内容），您仍然需要一个与真实 data-composition-id 匹配的 window.__timelines 注册。最佳实践：注册 window.__timelines['<子合成 ID>'] = gsap.timeline({paused:true}) — 但由于子合成会注册自己的时间线，index.html 脚本块仅用于通过 lint 检查。使用子合成的 ID（而不是 'root'）。

子合成 <div> 需要 data-start="0" 和 data-duration

<template> 内部的 <div data-composition-id="..."> 必须具有 data-start="0" 和 data-duration="N"，否则 lint 会发出警告，并且播放可能无法启动。

其他

npx hyperframes compositions   # 列出项目中的合成
npx hyperframes docs           # 打开文档
npx hyperframes benchmark .    # 对渲染性能进行基准测试