Back to Details

hyperframes-to-after-effects

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

HyperFrames to After Effects

HyperFrames 转 After Effects

A HyperFrames film is a paused GSAP timeline over HTML. This skill plays it in headless Chrome frame by frame, records what every element looks like, and rebuilds that in After Effects as native, editable layers:
HyperFramesAfter Effects
sub-composition (
data-composition-src
, nested 
data-composition-id
)		precomp at its start, trimmed to its visible window
text node (each rendered line)text layer, live font; changing strings become native recipes (below)
box with background / border / radius / outline / hard shadowshape layer (rounded rect, fill, stroke, dashes)
soft 
box-shadow
/ 
text-shadow
, 
filter: blur()
, 
mix-blend-mode
Drop Shadow, Gaussian Blur (keyed), blending mode
gradients, background images, inset or multiple shadows, mixed radiiPNG painted by Chrome (transform and opacity still keyed)
<img>
(
object-fit
, rounded corners), 
<video>
(trim, rate, volume)		footage layer with fit, crop mask, timing, audio level
inline 
<svg>
PNG at 4x (a few looks: one layer each; many: a sequence)
<canvas>
(2D, three.js, Lottie)		PNG sequence with time remap
overflow: hidden
, 
clip-path
(polygon, inset, circle, ellipse)		track matte (nested clips nest)
<audio>
audio layer at its start, with its volume
Changing text never becomes per-frame Source Text keys: After Effects slows down project-wide once any layer has them (one 150-key layer makes every later scripted edit ~200x slower, a 3,000-key film took hours). Instead: counters → a Count slider + expression (or pure 
time
expression when the number follows time), typing → Text Animator, a few strings or captions → one trimmed layer per string, scrambles → a small 
[time, text]
expression table, colour changes → Fill Color animator.
HyperFrames 影片本质上是一个基于 HTML 的已暂停 GSAP 时间轴。此 skill 会在无头 Chrome 中逐帧播放时间轴，记录每个元素的呈现效果，并在 After Effects 中将其重建为原生、可编辑的图层：
HyperFramesAfter Effects
子合成（
data-composition-src
、嵌套的 
data-composition-id
）		位于其起始位置的预合成（precomp），裁剪至可见窗口
文本节点（每个渲染行）文本图层，保持实时字体；字符串变更会转换为原生 recipe（见下文）
带背景、边框、圆角、轮廓或硬阴影的框形状图层（圆角矩形、填充、描边、虚线）
柔和的 
box-shadow
/
text-shadow
、
filter: blur()
、
mix-blend-mode
Drop Shadow、Gaussian Blur（已键控）、混合模式
渐变、背景图片、内阴影或多重阴影、混合圆角由 Chrome 绘制为 PNG（transform 和 opacity 仍设置关键帧）
<img>
（
object-fit
、圆角）、
<video>
（裁剪、帧率、音量）		footage 图层，包含适配、裁剪遮罩、时间轴点和音频电平
内联 
<svg>
4× PNG（外观较少时每个元素为一层；数量较多时生成序列）
<canvas>
（2D、three.js、Lottie）		带时间重映射的 PNG 序列
overflow: hidden
、
clip-path
（多边形、inset、圆形、椭圆）		track matte（嵌套片段会嵌套）
<audio>
从起始位置开始的音频图层，并保留音量
文本变更绝不会转化为逐帧的 Source Text 关键帧：只要任何图层存在此类关键帧，After Effects 的整个项目都会变慢（一个包含 150 个关键帧的图层会让之后每次脚本化编辑慢约 200 倍，一部包含 3,000 个关键帧的影片可能耗时数小时）。因此： 计数器 → Count 滑块 + 表达式（当数字随时间变化时，也可使用纯 
time
表达式），打字效果 → Text Animator，少量字符串或字幕 → 每个字符串一个裁剪图层，字符乱序效果 → 小型 
[time, text]
表达式表，颜色变化 → Fill Color animator。

Before you start

开始之前

Run the doctor and read it to the user in plain words:
bash
node <skill>/scripts/hf2ae.mjs doctor <project>
  • Node 18+, the project's HyperFrames CLI and its Chrome. The tool reuses what HyperFrames already installed (puppeteer-core, fontkit, sharp, Chrome) from the npx cache. If Chrome is missing, 
    npx hyperframes browser ensure
    downloads it: ask the user before running it.
  • After Effects (any recent version; 2023+ for the track-matte API) with Preferences → Scripting & Expressions → Allow Scripts to Write Files and Access Network switched on. Ask the user to check it; the build cannot set it.
  • ffmpeg for verification (HyperFrames rendering needs it anyway) and for converting WebM/OGG media.
Ask the user (only what you cannot infer):
  1. Where to save the 
    .aep
    (default 
    <project>/after-effects/project.aep
    ).
  2. If After Effects is open with a project: build into that open project (
    --into-open
    ), or save and close it first. Never close, save over or discard the user's open project yourself.
  3. Frame rate: the project's render rate if known (
    hyperframes render -f
    ), else 30. Use 60 for fast UI motion.
运行 doctor，并用通俗语言向用户说明结果：
bash
node <skill>/scripts/hf2ae.mjs doctor <project>
  • Node 18+、项目的 HyperFrames CLI 和 Chrome。 该工具会复用 HyperFrames 已从 npx 缓存中安装的内容（puppeteer-core、fontkit、sharp、Chrome）。如果缺少 Chrome，可通过 
    npx hyperframes browser ensure
    下载；运行前须征得用户同意。
  • After Effects（任意较新版本；track-matte API 需要 2023+），并在 偏好设置（Preferences）→ 脚本和表达式（Scripting & Expressions）→ 允许脚本写入文件和访问网络（Allow Scripts to Write Files and Access Network） 中启用相应选项。请用户自行检查；build 无法代为设置。
  • ffmpeg，用于验证（HyperFrames 渲染本身也需要它）以及转换 WebM/OGG 媒体。
仅询问无法推断的信息：
  1. .aep
    的保存位置（默认值为 
    <project>/after-effects/project.aep
    ）。
  2. 如果 After Effects 已打开某个项目：是构建到该打开的项目中（
    --into-open
    ），还是先保存并关闭它。绝不能自行关闭、覆盖保存或丢弃用户打开的项目。
  3. 帧率：如果已知项目的渲染帧率（
    hyperframes render -f
    ），则使用该值，否则使用 30。对于快速 UI 动效，使用 60。

Workflow

工作流

bash
node <skill>/scripts/hf2ae.mjs export <project> --out <dir> [--fps 30]   # Chrome only, no After Effects
node <skill>/scripts/hf2ae.mjs build  --out <dir> [--aep <file>] [--into-open]
node <skill>/scripts/hf2ae.mjs verify <project> --out <dir> [--frames 8]
node <skill>/scripts/hf2ae.mjs all    <project> --out <dir> ...           # the three in a row
<skill>
is this skill's folder. Run steps one at a time the first time on a project, so problems surface at the step that caused them.
  1. Export writes 
    <dir>/manifest.json
    , 
    <dir>/comps/*.json
    , 
    <dir>/assets/
    , 
    <dir>/fonts/
    and 
    <dir>/export_report.txt
    . Read the report before building: its fonts list says which real face every CSS family resolves to (aliases such as 
    "Brand Sans"
    are read from the font files), and warnings lists what was approximated. Tell the user about warnings that affect what they will see.
  2. Build starts After Effects (or uses the open one), writes progress to 
    <dir>/ae_status.txt
    and a log to 
    <dir>/ae_build_log.txt
    , saves after every composition. Typical films build in under a minute. If it runs for minutes on one layer, stop and read the log rather than waiting: see 
    references/troubleshooting.md
    .
  3. Verify renders the 
    .aep
    with 
    aerender
    and puts After Effects and HyperFrames side by side in 
    <dir>/verify/compare.png
    , with SSIM per moment in 
    <dir>/verify/report.txt
    . Open the sheet and look at it. SSIM tells you where to look, your eyes tell you what is wrong: typical numbers are 0.98+ with the original fonts and 0.95–0.99 with substitutes. Fix causes in the export or build (not by hand in After Effects), rebuild, re-verify.
bash
node <skill>/scripts/hf2ae.mjs export <project> --out <dir> [--fps 30]   # 仅使用 Chrome，不使用 After Effects
node <skill>/scripts/hf2ae.mjs build  --out <dir> [--aep <file>] [--into-open]
node <skill>/scripts/hf2ae.mjs verify <project> --out <dir> [--frames 8]
node <skill>/scripts/hf2ae.mjs all    <project> --out <dir> ...           # 依次执行上述三项
<skill>
是此 skill 的文件夹。首次处理某个项目时，请一次只运行一个步骤，以便在导致问题的环节及时发现异常。
  1. Export 会写入 
    <dir>/manifest.json
    、
    <dir>/comps/*.json
    、
    <dir>/assets/
    、
    <dir>/fonts/
    和 
    <dir>/export_report.txt
    。构建前先阅读报告：其中的 fonts 列表会说明每个 CSS 字体系列实际解析到的字体（诸如 
    "Brand Sans"
    的别名会从字体文件中读取），warnings 列表则说明哪些内容采用了近似实现。应告知用户其中会影响最终显示效果的警告。
  2. Build 会启动 After Effects（或使用已打开的实例），将进度写入 
    <dir>/ae_status.txt
    ，将日志写入 
    <dir>/ae_build_log.txt
    ，并在每个合成完成后保存。典型影片通常不到一分钟即可构建完成。如果某个图层构建数分钟，应停止任务并阅读日志，不要继续等待：参见 
    references/troubleshooting.md
    。
  3. Verify 使用 
    aerender
    渲染 
    .aep
    ，并将 After Effects 与 HyperFrames 的结果并排放在 
    <dir>/verify/compare.png
    中，同时将每个时刻的 SSIM 写入 
    <dir>/verify/report.txt
    。打开对比图并亲自查看。SSIM 可以告诉你应该关注哪里，而你的眼睛能够判断具体问题：使用原始字体时，典型数值通常为 0.98+；使用替代字体时通常为 0.95–0.99。应在 export 或 build 阶段修复原因（不要在 After Effects 中手动修改），然后重新构建并再次验证。

Fonts

字体

After Effects only sees fonts installed for all users (on Windows a per-user install is invisible to it). The build uses the real face when After Effects has it; otherwise it picks the closest installed face of the same kind (sans / serif / mono), fits each line to the width it had in the film (so words placed side by side keep their spaces), and writes the original font into the layer comment. The files to install are in 
<dir>/fonts/
(Google Fonts are fetched as TTF). Offer the user that choice: install them for all users, restart After Effects, run 
build
again (no re-export needed). Installing fonts is the user's action, not yours.
After Effects 只能识别为所有用户安装的字体（在 Windows 上，按用户安装的字体对它不可见）。如果 After Effects 中存在实际使用的字体，build 会直接使用；否则，它会选择同类（sans/serif/mono）已安装字体中最接近的一个，将每一行调整为影片中的原始宽度（确保并排词语之间的空格得以保留），并把原始字体写入图层注释。需要安装的文件位于 
<dir>/fonts/
（Google Fonts 会以 TTF 格式下载）。向用户提供以下选择：为所有用户安装字体、重启 After Effects，然后再次运行 
build
（无需重新 export）。字体安装必须由用户完成。

Reporting back

汇报结果

Tell the user, briefly: where the 
.aep
is; what became what (precomps, text, shapes, footage); which fonts were substituted and how to get the originals; the warnings that matter; the verify result with the sheet. Mention what stays approximate (3D transforms flattened to 2D, CSS filters other than blur, painted PNGs for gradients, blend modes that After Effects mixes slightly differently) so nothing surprises them in After Effects.
简要告知用户：
.aep
的保存位置；各元素转换后的类型（precomp、文本、形状、footage）；哪些字体被替代以及如何获取原始字体；重要的警告；验证结果及对比图。同时说明哪些内容仍为近似效果（3D transform 被扁平化为 2D、blur 以外的 CSS filter、渐变被绘制为 PNG、After Effects 对混合模式的处理略有差异），避免用户在 After Effects 中遇到意外。

Going deeper

深入了解

  • references/how-it-works.md
    : the export format, keyframe reduction, text recipes, mattes, timing of precomps and media. Read it before changing the scripts.
  • references/troubleshooting.md
    : slow or stuck builds, After Effects not running the script, fonts, mismatched frames, macOS specifics.
  • references/how-it-works.md
    ：介绍 export 格式、关键帧缩减、文本 recipe、matte、precomp 与媒体的时间轴处理。修改脚本前应先阅读。
  • references/troubleshooting.md
    ：介绍构建缓慢或卡住、After Effects 未运行脚本、字体、帧不匹配及 macOS 特定问题。