CLI

npm install -g hyperframes
# 或直接使用 npx
npx hyperframes <command>

# 完全非交互 — 所有输入来自标志
npx hyperframes init my-video --example blank --video video.mp4
npx hyperframes render --output output.mp4 --fps 30 --quality standard
npx hyperframes upgrade --check --json

# 命令特定的交互流程
npx hyperframes init my-video

# catalog 支持的交互式选择器
npx hyperframes catalog --human-friendly

{
"name": "my-video",
"duration": 10.5,
"_meta": {
"version": "0.1.4",
"latestVersion": "0.1.5",
"updateAvailable": true
}
}

Update available: 0.1.4 → 0.1.5
Run: npx hyperframes@latest

npx hyperframes init --example warm-grain

npx hyperframes init my-video --example warm-grain

cd my-video
npx hyperframes preview

npx hyperframes lint

◆  Linting my-project/index.html

◇  0 errors, 0 warnings

npx hyperframes render --output output.mp4

npx hyperframes render -c compositions/intro.html -o intro.mp4

npx hyperframes render --docker --output output.mp4

# Agent 模式（默认）— --example 是必需的
npx hyperframes init my-video --example blank --video video.mp4

# 包含 Tailwind CSS 浏览器运行时支持
npx hyperframes init my-video --example blank --tailwind

# 人工模式 — 默认在 TTY 上使用交互式提示
npx hyperframes init my-video

# 添加块（子合成场景）
npx hyperframes add claude-code-window

# 添加组件（效果/代码片段）
npx hyperframes add shader-wipe

# 指定不同的项目目录
npx hyperframes add shader-wipe --dir ./my-video

# 无头/CI（跳过剪贴板；同样：--json 获取机器可读结果）
npx hyperframes add shader-wipe --no-clipboard --json

# 列出所有内容（默认：表格输出）
npx hyperframes catalog

# 按类型或标签筛选
npx hyperframes catalog --type block
npx hyperframes catalog --type block --tag social

# 机器可读的 JSON
npx hyperframes catalog --json

# 交互式选择器 — 选择以安装
npx hyperframes catalog --human-friendly

npx hyperframes compositions

# 使用本地 whisper.cpp 转录音频/视频
npx hyperframes transcribe audio.mp3
npx hyperframes transcribe video.mp4 --model medium.en --language en

# 从其他工具导入现有转录
npx hyperframes transcribe subtitles.srt
npx hyperframes transcribe captions.vtt
npx hyperframes transcribe openai-response.json

# 从文本生成语音
npx hyperframes tts "Welcome to HyperFrames"

# 选择声音
npx hyperframes tts "Hello world" --voice am_adam

# 保存到指定文件
npx hyperframes tts "Intro" --voice bf_emma --output narration.wav

# 调整语速
npx hyperframes tts "Slow and clear" --speed 0.8

# 生成西班牙语语音（语言从声音 ID 前缀自动检测）
npx hyperframes tts "La reunión empieza a las nueve" --voice ef_dora --output es.wav

# 覆盖音素器（用法语声音朗读英文文本）
npx hyperframes tts "Bonjour le monde" --voice af_heart --lang fr-fr

# 从文件读取文本
npx hyperframes tts script.txt

# 列出可用声音
npx hyperframes tts --list

# 默认：带 alpha 的 VP9 WebM（HTML5 原生，约 1 MB / 4s @ 1080p）
npx hyperframes remove-background avatar.mp4 -o transparent.webm

# ProRes 4444 .mov 用于编辑往返
npx hyperframes remove-background avatar.mp4 -o transparent.mov

# 单张图像 → 透明 PNG
npx hyperframes remove-background portrait.jpg -o cutout.png

# 图层分离：一次通过同时获取剪影和反向 alpha 背景板
npx hyperframes remove-background avatar.mp4 \
-o subject.webm --background-output plate.webm

# 在有 CoreML 或 CUDA 的机器上强制使用 CPU
npx hyperframes remove-background avatar.mp4 -o transparent.webm --device cpu

# 检查检测到的提供者而不渲染
npx hyperframes remove-background --info

npx hyperframes capture https://stripe.com
npx hyperframes capture https://linear.app -o captures/linear
npx hyperframes capture https://example.com --json

◇  Captured Stripe | Financial Infrastructure → captures/stripe-com

Screenshots: 12
Assets: 45
Sections: 15
Fonts: sohne-var

npx hyperframes preview [dir]
npx hyperframes preview --port 4567

npx hyperframes publish [dir]
npx hyperframes publish --yes

npx hyperframes lint [dir]
npx hyperframes lint [dir] --verbose   # 包含 info 级别发现
npx hyperframes lint [dir] --json      # 机器可读的 JSON 输出

◆  Linting my-project/index.html

✗ missing_gsap_script: Composition uses GSAP but no GSAP script is loaded.
⚠ unmuted-video [clip-1]: Video should have the 'muted' attribute for reliable autoplay.

◇  1 error(s), 1 warning(s)

npx hyperframes inspect [dir]
npx hyperframes inspect [dir] --json
npx hyperframes inspect [dir] --samples 15
npx hyperframes inspect [dir] --at 1.5,4,7.25

◆  Inspecting layout for my-project (9 timeline samples)

✗ text_box_overflow t=3.25s #headline inside .bubble overflowed right 18px — "Quarterly plan"
Fix: Text is 418px x 42px inside 400px x 120px and overflows by up to 18px; widen the container to at least ~418px, or allow wrapping with max-width/fitTextFontSize.

◇  1 error(s), 0 warning(s), 0 info(s)

npx hyperframes layout [dir] --json

npx hyperframes snapshot my-project --at 2.9,10.4,18.7
npx hyperframes snapshot my-project --frames 10

◆  Capturing 3 frames at [2.9s, 10.4s, 18.7s] from my-project

◇  3 snapshots saved to snapshots/
snapshots/frame-00-at-2.9s.png
snapshots/frame-01-at-10.4s.png
snapshots/frame-02-at-18.7s.png

# 本地模式（快速迭代）
npx hyperframes render --output output.mp4

# Docker 模式（确定性输出）
npx hyperframes render --docker --output output.mp4

# 带透明度的 WebM（用于覆盖层、字幕、下方三分之一标题）
npx hyperframes render --format webm --output overlay.webm

# 使用选项
npx hyperframes render --output output.mp4 --fps 60 --quality high

# 退出本地浏览器 GPU 捕获
npx hyperframes render --no-browser-gpu --output cpu-browser.mp4

# 添加硬件 FFmpeg 编码
npx hyperframes render --gpu --output gpu.mp4

<html
data-composition-id="root"
data-composition-variables='[
{"id":"title","label":"Title","type":"string","default":"Hello"},
{"id":"theme","label":"Theme","type":"enum","options":[
{"value":"light","label":"Light"},
{"value":"dark","label":"Dark"}
],"default":"light"}
]'>
<body>
<h1 id="hero" class="clip" data-start="0" data-duration="3"></h1>
<script>
const vars = window.__hyperframes.getVariables();
document.getElementById("hero").textContent = vars.title;
document.body.dataset.theme = vars.theme;
</script>
</body>
</html>

# 使用声明的默认值渲染（预览也使用默认值）
npx hyperframes render --output default.mp4

# 在渲染时覆盖 — 缺失的键回退到声明的默认值
npx hyperframes render --variables '{"title":"Q4 Report","theme":"dark"}' --output q4.mp4

# 从 JSON 文件传递值
npx hyperframes render --variables-file ./vars.json --output out.mp4

# 渲染带透明背景的字幕覆盖层
npx hyperframes render --format webm --output captions.webm

# 使用 FFmpeg 叠加到另一个视频上
ffmpeg -c:v libvpx-vp9 -i captions.webm -i background.mp4 \
-filter_complex "[1:v][0:v]overlay=0:0" -y composited.mp4

npx hyperframes benchmark [dir]

npx hyperframes doctor

hyperframes doctor

✓ Version          0.1.4 (latest)
✓ Node.js          v22.x (linux x64)
✓ FFmpeg            7.x
✓ FFprobe           7.x
✓ Chrome            (system or cached)
✓ Docker            24.x
✓ Docker running    Running

◇  All checks passed

hyperframes doctor --json | jq -e '.ok' > /dev/null || handle_failure

npx hyperframes info [dir]

npx hyperframes upgrade
npx hyperframes upgrade --check         # 检查并退出（无提示）
npx hyperframes upgrade --check --json  # 机器可读的 Agent 友好格式
npx hyperframes upgrade --yes           # 显示升级命令而不提示

{
"current": "0.1.4",
"latest": "0.1.5",
"updateAvailable": true,
"_meta": { "version": "0.1.4", "latestVersion": "0.1.5", "updateAvailable": true }
}

# 查找或下载 Chrome 用于渲染
npx hyperframes browser ensure

# 打印浏览器可执行文件路径（用于脚本）
npx hyperframes browser path

# 移除缓存的 Chrome 下载
npx hyperframes browser clear

npx hyperframes docs [topic]

# 快速评分（1 = 差，5 = 好）
npx hyperframes feedback --rating 5

# 评分附带可选详情
npx hyperframes feedback --rating 3 --comment "render succeeded but GSAP timeline didn't animate"

npx hyperframes telemetry enable
npx hyperframes telemetry disable
npx hyperframes telemetry status

# 安装到所有默认目标（Claude Code、Gemini CLI、Codex CLI）
npx hyperframes skills

# 安装到特定工具
npx hyperframes skills --claude
npx hyperframes skills --cursor
npx hyperframes skills --claude --gemini

■  Failed to clone repository
fatal: active `post-checkout` hook found during `git clone`
└  Installation failed

GIT_CLONE_PROTECTION_ACTIVE=0 npx skills add heygen-com/hyperframes

# 交互式隐藏输入提示
hyperframes auth login --api-key

# 从 stdin 管道传入密钥（CI 友好）
echo "$HEYGEN_API_KEY" | hyperframes auth login --api-key

hyperframes auth status
hyperframes auth status --json   # 机器可读

hyperframes auth logout
hyperframes auth logout --keep-api-key   # 仅清除 OAuth 会话
hyperframes auth logout --yes            # 跳过确认提示

hyperframes auth login                          # 一次性
hyperframes cloud render ./my-video             # 压缩 + 上传 + 轮询 + 下载
hyperframes cloud render ./my-video --no-wait   # 提交并以 render_id 退出
hyperframes cloud list                          # 浏览最近的渲染

# 默认流程 — 渲染当前目录。
hyperframes cloud render

# 选择合成 + 输出路径。
hyperframes cloud render . \
--composition compositions/intro.html \
--output ./renders/intro.mp4

# 更高质量，60fps。
hyperframes cloud render --quality high --fps 60

# 使用 webhook 的即发即忘（无本地轮询）。
hyperframes cloud render --callback-url https://example.com/hf-hook --no-wait

# 重新渲染已上传的合成（跳过压缩 + 上传）。
hyperframes cloud render --asset-id asst_abc123

# 从公共 URL 渲染（无需上传）。
hyperframes cloud render --url https://cdn.example.com/site.zip

hyperframes cloud render . --idempotency-key "$(uuidgen)"

hyperframes cloud list
hyperframes cloud list --limit 50 --json
hyperframes cloud list --all

hyperframes cloud get hfr_abc123
hyperframes cloud get hfr_abc123 --json

hyperframes cloud delete hfr_abc123
hyperframes cloud delete hfr_abc123 --no-confirm --json

hyperframes lambda deploy
hyperframes lambda render ./my-project --width 1920 --height 1080 --wait
hyperframes lambda destroy   # 完成后

hyperframes lambda deploy \
--stack-name=hyperframes-prod \
--region=us-east-1 \
--concurrency=8 \
--memory=10240

hyperframes lambda sites create ./my-project
# → siteId: abc1234deadbeef0  （相同树的重新运行稳定）

hyperframes lambda render ./my-project --site-id=abc1234deadbeef0 --width 1920 --height 1080

hyperframes lambda render ./my-project \
--width=1920 --height=1080 --fps=30 --format=mp4 \
--chunk-size=240 --max-parallel-chunks=16 \
--wait

hyperframes lambda render ./my-template --site-id=abc1234deadbeef0 \
--width=1920 --height=1080 \
--variables '{"title":"Hello Alice","accent":"#ff0000"}'

hyperframes lambda render ./my-template --site-id=abc1234deadbeef0 \
--width=1920 --height=1080 \
--variables-file ./alice.json --strict-variables

{"outputKey": "renders/alice.mp4", "variables": {"name": "Alice", "accent": "#ff0000"}}
{"outputKey": "renders/bob.mp4",   "variables": {"name": "Bob",   "accent": "#0000ff"}}
{"outputKey": "renders/carol.mp4", "variables": {"name": "Carol"}, "executionName": "hf-carol-001"}

hyperframes lambda render-batch ./my-template \
--batch ./users.jsonl \
--width 1920 --height 1080 \
--max-concurrent 10

Batch dispatched: 3 started, 0 failed-to-start.

✓ line 1  renders/alice.mp4  arn:aws:states:us-east-1:1234:execution:hf:hf-render-...
✓ line 2  renders/bob.mp4    arn:aws:states:us-east-1:1234:execution:hf:hf-render-...
✓ line 3  renders/carol.mp4  arn:aws:states:us-east-1:1234:execution:hf:hf-carol-001

hyperframes lambda render-batch ./my-template --batch ./users.jsonl \
--width 1920 --height 1080 --dry-run --json

hyperframes lambda progress hf-render-abcd1234

# 打印可附加到运行 CLI 的 IAM 用户的内联策略文档。
hyperframes lambda policies user

# 打印 { TrustRelationship, InlinePolicy } 用于 IAM 角色（默认：cloudformation 主体）。
hyperframes lambda policies role --principal=cloudformation

# 验证已签入的策略仍覆盖 CLI 的需求。
hyperframes lambda policies validate ./infra/iam/hyperframes-deploy.json

{
"$schema": "https://hyperframes.heygen.com/schema/hyperframes.json",
"registry": "https://raw.githubusercontent.com/heygen-com/hyperframes/main/registry",
"paths": {
"blocks": "compositions",
"components": "compositions/components",
"assets": "assets"
}
}