hyperframes-registry

用途

HyperFrames Registry 是 HyperFrames 视频管线中的一个技能，用于安装注册表中的可复用区块（blocks）与组件（components），并把它们接入 HyperFrames 合成。资料给出的触发场景包括：用户提到 hyperframes add、“block”、“component”或 hyperframes.json；会话中出现 hyperframes add 的输出（文件路径、剪贴板片段）；需要把已安装项接入现有合成；想了解注册表中可用的内容。

主要能力

注册表提供两类可安装项：

• 区块（Blocks）：独立的子合成，拥有自己的尺寸、时长和时间线，通过 data-composition-src 嵌入宿主合成。
• 组件（Components）：效果片段，没有自己的尺寸，直接粘贴进宿主合成的 HTML。

安装命令示例：

hyperframes add data-chart              # 安装一个区块
hyperframes add grain-overlay           # 安装一个组件
hyperframes add shimmer-sweep --dir .   # 指定目标项目
hyperframes add data-chart --json       # 机器可读输出
hyperframes add data-chart --no-clipboard  # 跳过剪贴板（CI/无头环境）

注意：hyperframes add 仅适用于区块和组件；示例需使用 hyperframes init <dir> --example <name>。

使用方式

安装后，CLI 会打印写入了哪些文件，以及一段可粘贴进宿主合成的片段。该片段只是起点；接入区块时还需补充 data-composition-id（必须与区块内部合成 ID 一致）、data-start、data-track-index 等属性。

默认安装位置：区块安装到 compositions/<name>.html，组件安装到 compositions/components/<name>.html。这些路径可在 hyperframes.json 中配置：

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

接入区块时，在宿主 index.html 中通过 data-composition-src 引入：

<div
  data-composition-id="data-chart"
  data-composition-src="compositions/data-chart.html"
  data-start="2"
  data-duration="15"
  data-track-index="1"
  data-width="1920"
  data-height="1080"
></div>

关键属性：data-composition-src 为区块 HTML 文件路径；data-composition-id 必须与区块内部 ID 一致；data-start 为区块在宿主时间线中出现的时间（秒）；data-duration 为播放时长；data-width / data-height 为区块画布尺寸；data-track-index 为图层顺序（数值越大越靠前）。

接入组件时，需读取已安装文件（如 compositions/components/grain-overlay.html），把 HTML 元素复制进合成的 <div data-composition-id="...">，把 <style> 块复制进样式，把 <script> 内容复制进脚本（位于时间线代码之前）；若组件提供 GSAP 时间线集成（见片段中的注释块），还需把这些调用加入时间线。

适用场景

适用于在 HyperFrames 视频合成中复用注册表提供的区块与组件，例如添加数据图表区块或颗粒叠加效果组件，并按项目需要调整安装路径与接入属性。

限制

资料仅涵盖上述安装与接入流程；注册表条目的具体数量、全部可用项清单、各组件/区块的详细效果说明、收费与授权信息暂未提供。hyperframes add 不用于安装示例，示例需通过 hyperframes init 获取。