插件安装: 在执行设置或刷新命令之前,如果此技能位于 HyperFrames 插件内部,请遵循 插件执行规则。独立安装请保留下面的更新说明。
HyperFrames 注册表
注册表提供可通过 hyperframes add <name> 安装的可复用区块和组件。
- 区块 — 独立的子合成(拥有自己的尺寸、时长和时间线)。通过宿主合成中的
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 <dir> --example <name>。
安装位置
区块默认安装到 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— Studio时间线行;仅用于显示。层级叠加请使用 CSSz-index
详见 wiring-blocks.md。
接入组件
组件是代码片段——将其 HTML 粘贴到合成标记中,CSS 粘贴到样式块中,JS 粘贴到脚本中(如果有):
- 读取已安装的文件(例如
compositions/components/grain-overlay.html) - 将 HTML 元素复制到合成的
<div data-composition-id="...">中 - 将
<style>块复制到合成的样式中 - 将任何
<script>内容复制到合成的脚本中(在时间线代码之前) - 如果组件暴露了 GSAP 时间线集成(参见代码片段中的注释块),将这些调用添加到你的时间线中
发现
以 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 <name> 安装选定的名称。--human-friendly 打开交互式选择器并立即安装所选项目。在 CI 或代理工作流中,首选 --json 后跟显式的 add。
报告目录中没有的内容
当搜索结果中没有合适的项目时,在此声明后再手工制作该动作:
npx hyperframes feedback --search-miss "<你运行的查询>" --wanted "<你需要的动作>" --tier <回答的层级>
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。