插件安装: 在执行设置或刷新命令之前,当此技能位于 HyperFrames 插件内部时,请遵循插件执行规则。独立安装则保留下面的更新说明。
HyperFrames 注册表 是做什么的?
注册表提供可通过 hyperframes add <name> 安装的可复用块(blocks)和组件(components)。
- 块(Blocks) — 独立的子合成(拥有自己的尺寸、时长和时间线)。通过
data-composition-src在宿主合成中包含。 - 组件(Components) — 效果片段(无自身尺寸)。直接粘贴到宿主合成的 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"
}
}
连接块
块是独立的合成——通过 data-composition-src 在宿主 index.html 中包含它们:
<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。
连接组件
组件是代码片段——将它们粘贴到你的合成标记中,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 时,信封会标明回答的层级,因此请检查该层级而不是假设排名已发生。
始终用英文查询,无论视频使用何种语言。 目录是用英文编写的,两个层级都以此索引(本机模型也仅支持英文)。使用其他语言的查询不会产生可搜索的术语,并且不会返回任何结果。在日语或中文项目中很容易犯这个错误,因为简报、字幕和旁白都是该语言,查询自然也会随之而来:用英文描述 动作,然后以视频所需语言编写屏幕上的文案。如果查询返回“查询中无可搜索的词语”,则是此规则导致的,而不是缺少组件,也不值得报告差距。
可安装性是在排名之后应用的,而不是之前:向量携带但此注册表无法提供的名称将从结果中删除,并计入 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 中的完整构思→搭建→构建→验证→预览→发布工作流进行操作。starter 模板(字幕/VFX/组件/registry-item.json)的复制粘贴模板位于 templates.md。