装好 HyperFrames，用 doctor 体检，起第一个项目并抽帧

第 1 步：确认 Node.js 与 FFmpeg

官方 README 写明的依赖只有两项：Node.js 22 或更高、FFmpeg。

node -v
ffmpeg -version | head -1

对照结果（测试机系统自带的是 v20.19.2，已换成官方 Linux x64 二进制）：

v22.21.1
ffmpeg version 7.1.5-0+deb13u1 Copyright (c) 2000-2026 the FFmpeg developers

Node 低于 22 先升级（nvm、fnm，或从 https://nodejs.org/ 下载 22.x 官方压缩包）。FFmpeg 在 Debian / Ubuntu 上用 sudo apt-get install -y ffmpeg，macOS 用 brew install ffmpeg，Windows 可用 winget install ffmpeg。

第 2 步：安装并确认版本

官方两种写法：不安装直接用 npx，或者全局安装一次。

npx hyperframes@0.9.26 --version

npm install -g hyperframes@0.9.26
hyperframes --version

本课为了不改系统目录，在实验文件夹里做了本地安装，效果相同，只是命令在 node_modules/.bin 里：

mkdir -p ~/hf-lab && cd ~/hf-lab
npm install --prefix . hyperframes@0.9.26
export PATH="$PWD/node_modules/.bin:$PATH"
hyperframes --version

对照结果：

0.9.26

后面的命令统一写成 hyperframes …；没加到 PATH 的话，把开头换成 npx hyperframes 即可。用 hyperframes --help 可以看到全部命令分组（Getting Started、Project、Tooling、Deploy、AI & Integrations 等），本课只用其中十来个。

第 3 步：用 doctor 体检，并决定是否关闭遥测

hyperframes doctor

对照结果（节选）：

hyperframes doctor

  ✓ Version          0.9.26 (not checked yet)
  ✓ CLI binary       project-local install (node_modules) ·
      …/hf-lab/node_modules/hyperframes/bin/hyperframes.mjs
  ✓ Node.js          v22.21.1 (linux x64)
  ✓ Memory           15.6 GB total · 6.0 GB available
  ✓ Frames cache     /tmp/hyperframes-extract-cache-1000 · 60.8 GB free at /tmp · default
  ✓ /dev/shm         8001 MB
  ✗ whisper-cpp      Not found (optional — needed for transcription)
  ✗ TTS (Kokoro)     Not installed (optional — local voice fallback)
  ✗ BGM (MusicGen)   Not installed (optional — local music fallback)
  ✓ FFmpeg           ffmpeg 7.1.5-0 at /usr/bin/ffmpeg; loudness numbers are only comparable
      on 8.0.1
  ✓ FFprobe          ffprobe 7.1.5-0 at /usr/bin/ffprobe
  ✓ Chrome           system: /usr/bin/google-chrome
  ✗ Docker           Not found
  ✗ Docker running   Not running

  ◇  Some checks failed — see hints above

怎么读这张表：

所以上面虽然显示 Some checks failed，失败的全是可选项，可以继续。

HyperFrames 默认会上报匿名使用统计（命令名、渲染耗时、系统信息等，官方 CLI 参考的 telemetry 一节列出了完整清单，不含项目名和视频内容）。不想上报可以关掉，并用 status 确认：

hyperframes telemetry disable
hyperframes telemetry status

本课测试时是用环境变量 HYPERFRAMES_NO_TELEMETRY=1 关闭的，对照结果：

  Status:     disabled
  Source:     HYPERFRAMES_NO_TELEMETRY

第 4 步：起第一个项目，看懂它的骨架

hyperframes init my-video --non-interactive --skip-skills
cd my-video
ls

--non-interactive 跳过交互式向导，--skip-skills 表示这次不给 AI 编程 Agent 安装技能包（本课不用 Agent；以后要让 Claude Code 等接手，再按官方 Quickstart 运行 npx hyperframes skills update）。

对照结果：

Created my-video/
  AGENTS.md
  CLAUDE.md
  hyperframes.json
  index.html
  meta.json
  package.json

各文件的作用：index.html 是视频本体；AGENTS.md 与 CLAUDE.md 内容相同，是写给编程 Agent 看的项目说明；hyperframes.json 记录组件库地址和组件落盘目录（第 3 课会用到）；package.json 里预置了 npm run dev、npm run check、npm run render 等脚本，背后就是对应的 hyperframes 命令。

打开 index.html，去掉样式后骨架是这样的（真实生成内容节选）：

<div
  id="root"
  data-composition-id="main"
  data-start="0"
  data-duration="10"
  data-width="1920"
  data-height="1080"
>
  <h1 id="title" class="clip" data-start="0" data-duration="10" data-track-index="0">Title</h1>
</div>
<script>
  const tl = gsap.timeline({ paused: true });
  window.__timelines["main"] = tl;
  tl.seek(0);
</script>

记住三条约定，后两课都靠它们：

1. 根元素用 data-composition-id 起名，用 data-duration 定总时长（秒），data-width 与 data-height 定画幅
2. 每个要上时间轴的元素加 class="clip"，用 data-start 与 data-duration 决定它何时出现、出现多久；data-track-index 只决定在编辑器里显示在哪一行，不决定谁在上层
3. 动画写在一条 { paused: true } 的 GSAP 时间线里，并以与 data-composition-id 相同的名字注册到 window.__timelines，播放头由 HyperFrames 控制

第 5 步：不渲染，先看结构再抽两帧

这四条命令都很快，lint 甚至不启动浏览器：

hyperframes lint
hyperframes info
hyperframes compositions
hyperframes timeline

对照结果：

◆  Linting my-video/index.html

◇  0 errors, 0 warnings

◇  my-video
   Resolution    1920x1080
   Duration      10.0s
   Elements      2 (2 text)
   Tracks        1
   Size          17.7 KB

◇  my-video — 1 composition

   main   10.0s   1920×1080   1 element

timeline 10s

graphics (1)
  |████████████████████████████████████████| #title title 0-10s

再用 snapshot 只截指定时刻的画面：

hyperframes snapshot --at 0,5

对照结果（路径中的随机目录名每次不同）：

◆  Capturing 2 frames at [0s, 5s] from my-video
   Note: added an end-of-timeline frame at 9.75s. Short beats between your --at times may
       still be skipped — pass them explicitly.
[hyperframes] snapshot: frame 1/3 at 0s
[hyperframes] snapshot: frame 2/3 at 5s
[hyperframes] snapshot: frame 3/3 at 9.75s

◇  3 snapshots saved to …/my-video/.hyperframes/artifacts/snapshots/3c89ce3a-…
   …/frame-00-at-0s.png
   …/frame-01-at-5s.png
   …/frame-02-at-9.75s.png
   …/contact-sheet.jpg (grid view for AI review)

它默认会多截一张结尾帧（不想要就加 --no-end），并拼一张联系表 contact-sheet.jpg。打开看，三张都是黑底白字「Title」：空白模板确实只有一个标题。整段 10 秒视频一帧都没渲染，就已经确认了画面。

想在浏览器里边改边看，可以运行 hyperframes preview，它会在 http://localhost:3002 打开 Studio 预览并自动刷新；在没有图形界面的服务器上加 --no-open，结束时用 hyperframes preview --stop。本课测试机上它返回 HTTP 200，但没有进一步操作界面。

常见坑

• 看到 doctor 一排红叉先别慌：只要 Node.js、FFmpeg、FFprobe 是对勾就能继续，Chrome 缺了会在首次渲染时自动下载
• 首次渲染会自动下载 chrome-headless-shell（测试机解压后约 260 MB，渲染日志里显示 Browser: download，之后显示 Browser: cache），网络不通时可以先运行 hyperframes browser ensure，或把环境变量 HYPERFRAMES_BROWSER_PATH 指向已有的 chrome-headless-shell
• 不加 --non-interactive 时 init 会弹出交互向导；在脚本或 CI 里一定要加
• npx hyperframes 每次可能拉最新版，想和本课输出一致就写成 npx hyperframes@0.9.26

小结

你已经装好 HyperFrames 0.9.26，知道 doctor 里哪些是必需项，起了第一个项目，看懂了「根元素定时长、clip 定出场、暂停时间线管动画」三条约定，并且不渲染就抽到了帧。下一课自己写一段 7 秒中文片头，让 lint 和 check 帮你挑毛病。