HyperFrames 注册中心
注册中心提供可通过 hyperframes add <名称> 安装的可复用块和组件。
- 块 — 独立的子合成(有自己的尺寸、时长、时间线)。通过宿主合成中的
data-composition-src包含。 - 组件 — 效果片段(无自身尺寸)。直接粘贴到宿主合成的 HTML 中。
快速参考
hyperframes add data-chart # 安装一个块
hyperframes add grain-overlay # 安装一个组件
hyperframes add captions # 安装所有标记为 captions 的块
hyperframes add shimmer-sweep --dir . # 指定目标项目
hyperframes add data-chart --json # 机器可读输出
hyperframes add data-chart --no-clipboard # 跳过剪贴板(CI/无头模式)
安装后,CLI 会输出生成的文件以及要粘贴到宿主合成中的代码片段。该片段是一个起点——你需要添加 data-composition-id(必须匹配块的内部合成 ID)、data-start 和 data-track-index 属性来连接块。
位置值首先解析为精确的项目名称。如果没有匹配且该值是标签,则命令会安装具有该标签的所有块。注册依赖项在请求的项目之前安装。hyperframes add 仅适用于块和组件;对于示例,请使用 hyperframes init <目录> --example <名称>。
安装位置
默认情况下,块安装到 compositions/<名称>.html。组件安装到 compositions/components/<名称>.html。
这些路径可在 hyperframes.json 中配置:
{
"registry": "https://raw.githubusercontent.com/heygen-com/hyperframes/main/registry",
"paths": {
"blocks": "compositions",
"components": "compositions/components",
"assets": "assets"
}
}
详情请参阅 install-locations.md。
连接块
块是独立的合成——通过宿主 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— 图层顺序(数字越大越靠前)
详情请参阅 wiring-blocks.md。
连接组件
组件是片段——将它们的 HTML 粘贴到合成标记中,CSS 粘贴到样式块中,JS 粘贴到脚本中(如果有的话):
- 读取已安装的文件(例如,
compositions/components/grain-overlay.html) - 将 HTML 元素复制到合成的
<div data-composition-id="...">中 - 将
<style>块复制到合成的样式中 - 将任何
<script>内容复制到合成的脚本中(在时间线代码之前) - 如果该组件暴露了 GSAP 时间线集成(请参阅片段中的注释块),将这些调用添加到你的时间线中
详情请参阅 wiring-components.md。
发现
将 CLI 作为主要发现界面。在浏览之前先按意图搜索: 注册中心包含大量项目,靠肉眼扫描列表并根据名称或标签匹配是慢路径,并且当作者的措辞与你的不同时可能会失败。
# 根据节拍应该执行的操作对整个目录排序
npx hyperframes catalog --query "reveal a headline one line at a time"
npx hyperframes add caption-clip-wipe
搜索在本地进行,不会发送任何数据。默认情况下,它根据与项目名称、标题和描述共享的词汇进行排序,因此只能找到使用了你所用词汇的项目;--on-device 则根据含义进行排序(需一次性模型下载)。使用 --json 时,信封会标明哪个层进行了响应,所以请检查它,而不是假设排序已发生。
始终使用英语查询,无论视频使用什么语言。 目录使用英语编写,两个层都按这种方式索引(设备端模型也仅限英语)。使用其他脚本的查询不会产生可搜索的术语,并且不会返回任何结果。这在日语或中文项目中很容易出错,因为简介、字幕和叙述都使用该语言,查询自然会跟随:用英语描述 动作,然后用视频所需的语言编写屏幕上的文字。如果查询返回 No searchable words in query,这就是原因,而不是缺少组件,也不值得提交缺口报告。
可安装性在排序后应用,而不是之前:向量携带但此注册中心无法提供的名称会从结果中删除并计入 dropped,因此非零的 dropped 意味着两者属于不同代。有关离线层、同意门以及如何刷新过时索引的信息,请参阅 /hyperframes-cli。
要浏览或筛选而不是搜索:
npx hyperframes catalog
npx hyperframes catalog --type block
npx hyperframes catalog --type component
npx hyperframes catalog --type block --tag social
npx hyperframes catalog --json
npx hyperframes catalog --human-friendly
普通表格和 --json 模式仅列出匹配项;使用 hyperframes add <名称> 安装选定的名称。--human-friendly 打开交互式选择器并立即安装选定的项目。在 CI 或代理工作流中,建议使用 --json 后跟显式的 add。
报告目录中缺失的内容
当搜索返回但搜索结果中没有任何内容能满足需求时,在手动创作该动作之前请先说明:
npx hyperframes feedback --search-miss "<你运行的查询>" --wanted "<你需要的动作>" --tier on-device
catalog --query 会为你打印一行预填好的内容,而 --json 会将其作为 report_gap 携带——因此在你决定没有匹配时,它就已经在手边了。
只要结果中没有任何内容能满足需求,就在两个层上报告。 不要等待设备端层做出响应:它需要经过同意下载 33 MB 模型,除非显式选择加入,否则代理运行使用的是 words 级别,而仅限于 on-device 会几乎使所有报告沉默。--tier 值会随之传递,因此在读取时,词汇缺失仍可与含义缺失区分开来。描述你需要的效果,而不是你想象的项目名称:返回的结果是一个值得构建的移动列表,而报告一个不存在的项目没有任何指导作用。这是唯一一种将查询发送到任何地方的路径,这正是一个单独的有意命令而不是搜索自动执行的原因。它不携带任何评分,也永远不会进入评分指标。
这是目录的整个需求信号。跳过它意味着你遇到的缺口只能从安装计数中推测,而安装计数无法看到没有项目可安装的情况。
如果 CLI 无法访问配置的注册中心,请作为后备检查原始清单:
curl -s https://raw.githubusercontent.com/heygen-com/hyperframes/main/registry/registry.json
CLI 无法访问的注册中心不会使目录空掉以进行发现:当重新验证失败时,之前获取的清单会继续在 24 小时刷新窗口之外提供服务,因此 catalog 和 catalog --query 仍会根据磁盘上的最后一份副本进行列表和排序。
即使对于昨天安装的项目,add 仍然需要网络。 只有清单被缓存;项目的实际文件在每次安装时都会获取。因此,离线时可以搜索,也可以查看项目是什么,但安装会在文件获取时失败。不要向用户承诺离线安装。
每个项目的 registry-item.json 包含:名称、类型、标题、描述、标签、尺寸(仅块)、时长(仅块)和文件列表。
有关按类型和标签筛选的详情,请参阅 discovery.md。
贡献新的块或组件
要创作新的注册中心项目(字幕样式、VFX 块、过渡、下三分之一或可复用组件)并以上游 PR 形式发布——而不是安装现有项目——请按照 contributing.md 中的完整 创意→脚手架→构建→验证→预览→发布 工作流操作。起始模板(字幕/VFX/组件/registry-item.json)的复制粘贴版本在 templates.md 中。