Communitygithub.com

samyakiasonline-ctrl/hyperframe

使用 HyperFrames CLI 开发循环:初始化、添加、目录、捕获、检查、校验、快照、比较、评分对比、预览、播放、展示、节拍、关键帧、单幅或批量渲染、发布、云端、云端运行、反馈、Lambda、诊断、浏览器、信息、升级、技能、合成、时间线、历史记录、清理、文档、基准测试、遥测、转写、认证、文本转语音和移除背景。也可用于诊断构建或渲染失败。validate、inspect 和 layout 是已弃用的别名;请使用 check。涵盖本地、HeyGen 托管云、AWS Lambda 和 Google Cloud Run 渲染。

hyperframe 是什么?

HyperFrames CLI 是一款专为视频合成开发而设计的强大命令行工具,旨在帮助开发者和 AI 智能体高效地管理从项目初始化到最终交付的完整创作循环。它支持本地、HeyGen 托管云、AWS Lambda 和 Google Cloud Run 等多种渲染后端,并具备 lint、check、snapshot 等丰富的质量保证命令。该工具的核心优势在于其自动化开发流程:用户可通过 `init` 脚手架项目,通过 `catalog` 搜索现成动画基元,并使用 `keyframes`、`audio` 等子命令进行精细编辑。它还集成了项目历史管理 (`history`) 和基于 Studio 的上下文编辑功能,确保团队成员或 AI 智能体之间的协作不会相互覆盖。对于 AI 智能体(如 Claude Code、Codex),它提供了优化的 `--json` 输出和明确的开发循环步骤,包括强制性的最终检查、预览和渲染批准流程。此外,它内置了智能的目录搜索,支持本地词汇匹配和可选的设备端语义排名(bge-small-en-v1.5 模型),且默认不上传任何查询数据。通过 `feedback --search-miss` 机制,用户可以报告缺失的动画效果,帮助改进目录覆盖范围。

兼容平台✓Claude Code✓Codex CLI~Cursor
npx skills add https://github.com/samyakiasonline-ctrl/hyperframe/tree/HEAD/.claude/skills/hyperframes-cli

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

插件安装: 在设置或 freshness 命令之前,如果此技能位于 HyperFrames 插件内,请遵循 插件执行规则。独立安装则保留下面的更新说明。

HyperFrames CLI

以 npx hyperframes ... 的形式运行命令,除非项目说明提供了封装器。有封装器时,请遵守。CLI 需要 Node.js 22 或更新版本以及 FFmpeg。

开发循环

  1. 脚手架: npx hyperframes init <project>(居中空白)。或者捕获一个站点。仅当从命名示例开始时传递 --example=<name>。
  2. 找到动作: 如果请求指定了素材、声音、图像、语音或快速视觉编辑,请在提出计划之前通过 /media-use 解决。否则,在手动编写动作之前,先搜索是否已有执行该动作的基元:npx hyperframes catalog --query "逐行揭示标题"。描述你想要的效果,而不是你心中的机制。使用 npx hyperframes add <name> 安装(参见 /hyperframes-registry)。只有在没有合适的基元时才手动编写。
  3. 创作: 使用 /hyperframes-core 编写合成。要知道项目时间线上有什么(轨道、片段、开始、结束、播放内容),请运行 npx hyperframes timeline --json,而不是读取 index.html 和每个子合成文件:嵌套行带有绝对主时间线 absStart/absEnd 及其所属的 file,而不仅仅是它们在子合成内的本地时间。优先使用 --json 而非文本形式;它在相同或更好的正确性下消耗更少的 token。参见 references/upgrade-info-misc.md,其中包含回答常见问题的一行命令,无需阅读整个输出。
  4. 编辑时获取快速反馈: 在第一次 HTML 检查之后以及结构更改之后运行 npx hyperframes lint。
  5. 运行最终关卡: 运行 npx hyperframes check;它会在打开浏览器之前重新运行 lint。不要预先附加多余的独立 lint 调用。添加 --snapshots 以获取带注释的概览帧和查找裁剪区域。
  6. 检查子合成: 当 index.html 挂载 data-composition-src 时,捕获中间点快照并检查每个挂载的场景。
  7. 打开最终 Studio 预览: 运行 npx hyperframes preview --background,验证 URL 返回 HTTP 200,将时间线项目 URL 交给用户,并询问是否要修订或渲染。保持其存活直到审查结束。
  8. 仅在批准后渲染: 迭代时使用 --quality draft,首次真正编码时使用 --quality looks(CLI 默认值),最终交付时使用 --quality delivery。
  9. 将项目交给桌面应用(如有提供): 当渲染器的 Framey 行以 hyperframes open … 结尾时,提供 npx hyperframes open [dir]。它会在 HyperFrames 桌面应用中打开项目并将其添加到主页;在 Claude Code 或 Codex 下,其聊天将继承此对话。如果没有桌面应用,则退出并返回 1,并打印下载链接。--json 用于智能体。
  10. 验证输出: 确认文件存在且非空。读取渲染摘要的第二行(beginframe 与 screenshot、GPU、阶段时间)。Linux 上的 screenshot + software gpu 是慢速路径。ffprobe -v error -show_format -show_streams 并比较持续时间(以及如果简报设置了 fps)与根 data-duration。

回合中的项目历史

项目的每次写入都保存为可撤销的条目。仅在两个时刻使用,而非每个步骤:

  • 回合开始: npx hyperframes history begin --who <你的名字> --label "<你将要做什么>",然后运行 npx hyperframes history --since mine --who <你的名字> 以查看自你上一个回合以来此人更改了什么。建立在他们编辑的基础上;切勿覆盖。
  • 检查失败,或者此人说情况变糟: npx hyperframes history undo --who <你的名字> 撤销你最新的回合,并保留此人的编辑。不要手动恢复更改。如果发生冲突,则退出并返回 2,并打印两个选项。

以 npx hyperframes history end 结束每个回合,以便你的写入被识别为你的,而不是“在应用外更改”。当一个回合打开时,项目的每次写入都会计入你的名下,直到 10 分钟没有写入为止;之后回合自动结束。

强制性的创作者编辑交叉引用

  • 在创作或诊断缩放、切入/切出、重新构图、摄像机移动或任何关键帧动画之前,请先阅读 /hyperframes-keyframes。
  • 在 hyperframes keyframes 之前,请阅读 /hyperframes-keyframes;该命令显示动画轨迹,不诊断片段剪辑。
  • 对于剪辑、修剪、拼接、重新排序或源时间编辑,请阅读 /hyperframes-core 并使用其片段/时间线约定。
  • 对于淡入/淡出、交叉淡变、轨道增益、音量自动化、闪避、画外音雕刻或对已放置音频的 FX,请阅读 /hyperframes-audio。当片段放置或画面时间同时更改时,同时加载核心。
  • 指定素材、声音、图像、语音或快速视觉编辑的请求在提出计划之前通过 /media-use 解决。 从 /hyperframes-core → references/creator-editing-recipes.md 复制创作者编辑标记。
# 快速迭代检查;创作时可根据需要重复。
npx hyperframes lint

# 必需最终关卡;包含 lint。
npx hyperframes check
npx hyperframes preview --background
npx hyperframes render --quality looks --output out.mp4
test -s out.mp4
ffprobe -v error -show_format -show_streams out.mp4

check 首先运行 lint,然后使用一个浏览器会话和一个 seek 过程来审计运行时错误、失败的请求、布局、*.motion.json 断言和 WCAG 对比度。持续性的发现会阻止退出代码;临时性的进入或退出发现仅作信息提示。使用 --strict 将警告视为阻止。validate、inspect 和 layout 仍然是用于兼容性的别名,但不能出现在新的指令或脚本中。

渲染前预览

仅在 check 通过后打开最终合成预览(#project/<name>),以查看组装好的时间线。聊天中的计划和 storyboard.html 草图页面并非对最终视频的批准。渲染始终需要 hyperframes/references/review-loop.md 中定义的最终批准。

子合成冒烟测试

静态审计无法捕获所有挂载失败。当项目使用子合成时,为每个宿主槽捕获至少一个可见的中间点快照:

npx hyperframes snapshot --at <t1>,<t2>,<t3>

将微小的无样式内容、画布大小的图标、缺少的英雄元素或时间线注册超时视为阻止渲染的挂载缺陷。参见 hyperframes-core/references/sub-compositions.md 了解相应的修复方法。

智能体约定

  • 在手动编写动作之前,先搜索目录。 npx hyperframes catalog --query "<节拍,用简单的英文描述>"。搜索完全是本地的:没有托管层,没有账户,查询文本绝不被发送到任何地方。默认情况下,它根据与项目名称、标题、描述和标签共享的词汇进行排名,这会遗漏任何不重复目录自身措辞的表述。添加 --on-device 以通过含义进行排名(参见下面的离线层)。

  • 即使视频不是英文,也用英文查询。 两个层都索引了英文目录,因此使用其他脚本的查询不会产生可搜索的术语,并会返回无结果。用英文描述动作;屏幕上的副本保持视频所需的任何语言。查询中没有可搜索的词 正是此意,并非组件缺失,因此不要将其报告为目录空白。

  • 读取哪个层做出了回答;切勿根据结果出现来推断。 使用 --json 时,信封包含 query、tier(on-device 或 words)、tier_detail、dropped、unindexed、shown、total 和 results,以及当回答层产生 top_score 时,以及当要求某个层但无法运行,或搜索未返回任何结果且更好的层仍在等待某人同意时的 warnings。words 上结果较弱是预期的;on-device 上的相同结果是错误。top_score 仅限 on-device,其背后没有阈值:排名器对每个查询都会以某种顺序返回整个目录,因此将其视为证据,而不是通过或失败。

  • dropped 和 unindexed 是注册表和 on-device 索引之间的相反偏差,并且重新措辞查询都无法解决。 dropped 计算此注册表无法安装的排名名称,因此丢失的是最强匹配。unindexed 计算索引完全无法看到的注册表动作,任何查询都无法返回。刷新注册表不是解决这两者中任何一个的答案:其清单具有 24 小时 TTL 并会自我修复,而向量是单独发布并获取到 ~/.hyperfaces/catalog/ 中的工件。当 unindexed 大于零时,使用 --on-device 重新运行会重新获取该索引,因此这是给用户的解决方案。纯粹的超覆盖偏差(dropped 大于零而 unindexed 为零)不会触发重新获取;清除 ~/.hyperfaces/catalog/ 是摆脱该问题的唯一方法。两个计数都是名称计数,而非结果计数,因此任何一个都可能超过 total。

  • 当搜索返回的内容不值得安装时,请说明。 npx hyperframes feedback --search-miss "<你运行的查询>" --wanted "<你需要的动作>" --tier <回答的层>。你无需组装这行命令:catalog --query 会打印预填充的版本,并且每个 --json 搜索信封都将其作为 report_gap 携带,且查询和层已正确——填写 --wanted 并发送。这是唯一将查询发送到任何地方的路径,并且它是一个单独的、有意的命令,正是为了确保普通的 catalog --query 履行其不发送任何内容的承诺。在任一层上报告,只要结果不能满足需求;不要专等 on-device 层,它需要已同意的 33 MB 下载,因此在大多数智能体运行中是关闭的——等待它意味着永远不报告。层信息会记录在报告中,因此词汇失误与含义失误仍然可以区分,无需你判断自己遇到了哪一种。返回的是目录尚不存在的动作列表,直接读取而非从安装计数中猜测,因此重要的措辞是你想要的效果,而不是你想象的项目名称。它不携带评级,也永远不会进入评级指标。

  • 提供离线层;永远不要静默启用。 一次性约 33 MB 下载(bge-small-en-v1.5 的量化 ONNX 构建及其分词器,固定修订版本)以及注册表的目录向量,两者都缓存在 ~/.hyperfaces/ 下,不添加到项目或任何包中。缓存后,它按含义排名,不发送任何内容。说清楚大小,让用户决定,然后一旦他们同意,就传递 --on-device(加上 -y 以跳过提示)。交互式提供仅在 TTY 上触发。在 --json 下没有提示,但未找到任何内容的搜索会将相同的请求放在 warnings 中,因此读取该数组并自行向用户提出决策。当用户询问下载内容、为何使用此模型或哪些内容离开机器时,请指向 https://hyperframes.heygen.com/developers/catalog-search。

  • 优先为智能体和 CI 调用使用 --json。服务器模式的 render、preview 和 play 不提供普通的 JSON 输出;preview --selection --json 和 preview --context --json 是查询模式的例外。

  • doctor --json 始终退出并返回零。通过其有效负载进行判断:

    npx hyperframes doctor --json | jq -e '.ok' >/dev/null
    
  • 非 TTY 模式是自动的,并搭建居中的空白项目。仅当从命名示例开始时传递 --example。使用 --non-interactive 在 TTY 上强制使用仅标志模式。

  • 在同一次验证循环中对所有命令使用一个 HYPERFRAMES_RUN_ID。

  • 当磁盘空间不足时,运行 npx hyperframes clean(使用 --dry-run 先列出);它会删除死渲染留下的内容和会自行重建的空闲缓存,绝不会删除输出、源文件或任何正在运行的渲染使用的内容。将 QC 帧写入临时目录,而非项目。

  • 当相应的警告、变量或 CI 条件必须阻止渲染时,使用 --strict、--strict-all 和 --strict-variables。

  • JSON 路径将主目录编辑为 $HOME;不要试图逆转编辑。

  • 当托管云项目接近或超过 200 MB 上传限制时,使用 cloud render --dry-run --json 并遵循 references/cloud.md 中的 .hyperframesignore 调查。切勿仅仅因为素材很大而忽略它。

  • 切勿仅仅因为检查通过就渲染。在最终预览处暂停,等待批准。

Studio 导向的编辑

当用户提到“此元素”或当前选择时,查询 Studio 而不是猜测:

npx hyperframes preview --context --json --context-fields selection

可用时使用 selection.target.hfId,否则使用其选择器和源文件。如果结果报告 no-selection,请用户点击该元素并重新运行。仅请求你需要的上下文切片;仅对计算样式或可编辑文本元数据使用 --context-detail full。完整行为和失败代码位于 references/preview-render.md 中。

渲染选择

需求命令
快速本地迭代npx hyperframes render --quality draft
首次真正编码npx hyperframes render --quality looks --output out.mp4
最终本地交付npx hyperframes render --quality delivery --output out.mp4
可重现的容器渲染`npx hyperframes render --

Individual skills in this repo

This repo contains 20 individual skills — each has its own dedicated page.

samyakiasonline-ctrl/hyperframe

Add captions or subtitles to an existing single-subject talking-head video without editing the footage. Use for plain verbatim captions, cinematic captions embedded behind the subject, VFX captions, “炸/特效/酷炫字幕,” or a named identity from the 35-style catalog. Route by visual identity, not by backend engine. The quiet `anchor` rail is the default; embed every word only when the user explicitly wants a fully cinematic treatment. The workflow runs locally end to end, including transcription and subject matting; split multi-shot footage before applying it.

samyakiasonline-ctrl/hyperframe

Turn arbitrary text — an article, notes, a topic, a brief — into a faceless explainer video: there is no site or footage to capture, so the visuals are invented per scene (typography, abstract graphics, diagrams, data-viz). Use for topic explainers, concept breakdowns, how-tos, listicles. Not a video built from a website (/product-launch-video — promo or tour). Unclear → /hyperframes.

samyakiasonline-ctrl/hyperframe

Import Figma content into a HyperFrames composition — rendered assets, brand tokens, components, storyboard sections → reconstructed motion (frames read as states, not slides) (REST/CLI), connector-assisted motion when available, and shaders from a connector or native export. Use when the user pastes a figma.com link or asks to bring a Figma design, frame, logo, brand, or animation into a video/composition.

samyakiasonline-ctrl/hyperframe

Author or edit a custom HyperFrames composition when no specialized workflow fits, or when BRIEF.md sets flow: companion. Use for longer or multi-scene pieces, brand and sizzle reels, montages, static loops, static title cards, footage remixes, and freeform builds. Use motion-graphics instead for a short unnarrated motion-first unit, including an animated title. Route fresh creation through hyperframes before using this skill.

samyakiasonline-ctrl/hyperframe

All animation knowledge for HyperFrames — atomic motion rules, multi-phase scene blueprints, scene transitions, broader motion-design techniques, AND the seven runtime adapters (GSAP default, plus Lottie, Three.js, Anime.js, CSS keyframes, Web Animations API, TypeGPU). Use for any motion or animation task: pick 2-4 rules and compose, or load a blueprint, or look up runtime-specific API (e.g. GSAP eases / Lottie player / Three.js mixer). Also covers auditing an existing composition's choreography (animation map) and 24 named text-animation effects. HyperFrames-native: single paused timeline, seek-safe, deterministic.

samyakiasonline-ctrl/hyperframe

Use when audio already placed in a HyperFrames composition needs to be mixed: fade-in/fade-out, crossfade, track gain or volume, volume automation, ducking, a music bed that fights a voiceover (voiceover carve), effects on a track (EQ, compressor, limiter, gate, saturation, delay, reverb, chorus, phaser, bitcrush), automation envelopes drawn on a track's volume or any effect parameter, or one submix bus carrying a chain, a fader and an automation clock for several tracks at once (`<hf-audio-group>`). Don't use for sourcing or generating audio — finding BGM, SFX, or making a voiceover is `/media-use`. Don't use for clip timing or track layout, which is `/hyperframes-core`.

samyakiasonline-ctrl/hyperframe

The HyperFrames composition contract — build one renderable project. Use for composition structure, the `data-*` timing attributes, `class="clip"`, tracks, sub-compositions, variables, framework-owned media playback, deterministic-render rules, and validation. Read before writing composition HTML.

samyakiasonline-ctrl/hyperframe

Non-animation creative direction for HyperFrames videos. Use for design spec (frame.md / design.md) handling, palettes, typography, narration, beat planning, audio-reactive visuals, composition patterns, and brand / style decisions. For atomic motion patterns and scene blueprints, use `hyperframes-animation`.

samyakiasonline-ctrl/hyperframe

Use when a HyperFrames composition needs a punch-in, punch-out, zoom, reframe, Ken Burns treatment, camera move, visual match/whip handoff, or other seek-safe 2D/3D keyframes; also for GSAP, CSS keyframes, Anime.js, WAAPI, FLIP, paths, masks, SVG morph/draw, text trails, 3D depth, or `hyperframes keyframes` diagnostics. Don't use for broad scene strategy, brand design, media sourcing, captions, or general video planning.

samyakiasonline-ctrl/hyperframe

Search, install, and wire registry blocks and components into HyperFrames compositions. Use BEFORE hand-building any named visual — whenever a brief, a user, or a storyboard names a look, effect, treatment, or transition such as CRT scanlines, glitch, chromatic aberration, film grain, a shimmer sweep, a chart, a code or terminal window, a map, or a confetti burst — because roughly 400 hosted items already cover many of them and the search ranks all of them with nothing installed, no project, and no account. Also use when running hyperframes add or hyperframes catalog, installing one item or every block matching a tag, wiring an installed item into index.html, or working with hyperframes.json. Covers discovery, install locations, block sub-composition wiring, component snippet merging, and authoring a new block or component to contribute upstream (idea → scaffold → validate → PR).

samyakiasonline-ctrl/hyperframe

Mandatory entry point: read this first for any request to make, create, edit, animate, or render a video, animation, or motion graphic, including a promo, explainer, captioned clip, title card, overlay, slideshow or interactive deck, Remotion port, or any HyperFrames HTML composition. Also use it to inspect, diagnose, validate, preview, publish, or batch-render an existing HyperFrames project. Inputs may be a website URL, GitHub PR, Figma design or URL, text or brief, existing footage, or music. It resumes project state, captures intent when applicable, selects and installs the owning workflow, and routes domain capabilities. HyperFrames is the default output framework unless the user explicitly chooses another framework for the deliverable or asks only to record a browser session.

samyakiasonline-ctrl/hyperframe

Use when working with a person on a HyperFrames project in Studio: first, whether their message asks for a change at all (questions, loose ideas and "don't change anything" get an answer and a plan, not an edit); for a new film, the plan, storyboard and build order that the HyperFrames launch films follow; and how the timeline should be laid out so it reads well (one caption track, one element kind per track, every scene a sub-composition) and where captions and key content may sit (safe zones). Don't use for how to perform an individual edit (split, trim, retime, volume, copy, swap): that is `creator-editing-recipes.md` in `/hyperframes-core`.

samyakiasonline-ctrl/hyperframe

Agent Media OS, the single skill for every media need in a HyperFrames project. Resolve BGM, SFX, image, icon, brand logo, voice, color grade, or LUT into a frozen local file or paste-ready block + ledger record (one verb, `resolve`); generate via TTS / music / image models when the catalog misses; produce voiceover, transcription, captions, and background removal through one shared audio engine; operate on media (cut / reframe / transform); and reuse assets across projects. Also use for vague feedback that real footage looks dark, flat, boring, should feel retro/camcorder/print/ASCII, needs privacy, or needs a media reveal.

samyakiasonline-ctrl/hyperframe

A short, design-led motion graphic where motion is the message — kinetic typography, stat count-up, chart/data-viz hit, logo sting / brand lockup, lower-third / callout / social overlay, animated map (highlight regions, connect places, zoom to a location), animated tweet / news-article / headline, webpage / UI animation (scroll, cursor, callouts), or fusing a real image's geometry into a chart. Usually under 10s (up to ~30s), no narration or live-action subject; renders to MP4 or transparent overlay. Longer / narrated / multi-scene → /general-video. Unclear → /hyperframes.

samyakiasonline-ctrl/hyperframe

Turn a music track (an audio file, a video to pull audio from, or a track generated from a mood brief) into a beat-synced video — lyric video, slideshow, or kinetic promo. The music drives all pacing; any user-supplied images/videos are cut onto the same beat grid, and a complete video needs zero assets. Narrated pieces → the input-matched workflow (see /hyperframes). Unclear → /hyperframes.

samyakiasonline-ctrl/hyperframe

Turn a product or marketing URL, pasted script, or brief into a product launch / promo video — SaaS promos, feature reveals, product demos, app and company launches. Use when the user wants to market, launch, promote, or reveal a product; the default for any commercial URL. Site tours / showcases of a website route here too — the brief carries the show-it-as-is intent. Unclear → /hyperframes.

samyakiasonline-ctrl/hyperframe

Turn a GitHub pull request (a PR URL, owner/repo#N, or 'this PR' in a checked-out repo) into a code-change explainer video — changelog, feature reveal, fix, or refactor walkthrough built from the diff, commits, and files: the input is a code change, not a website. Not a product promo (/product-launch-video) or a no-PR topic explainer (/faceless-explainer). Unclear → /hyperframes.

samyakiasonline-ctrl/hyperframe

Port an existing Remotion (React) composition''s source to HyperFrames HTML. Use ONLY on an explicit ask to port/convert/migrate/translate a Remotion source — one-way, Remotion-only. A passing Remotion mention, reference-only code, or "make something like my Remotion video" is a fresh build (/general-video). Unclear → /hyperframes.

samyakiasonline-ctrl/hyperframe

Author a HyperFrames slideshow — a presentation, pitch deck, or interactive deck with discrete slides, fragment reveals, branching, hotspot navigation, and built-in presenter mode with speaker notes; also converts an existing page into a deck. Output is a navigable deck, not a rendered MP4. If the user didn't explicitly ask for a slideshow, confirm before authoring. Unclear → /hyperframes.

samyakiasonline-ctrl/hyperframe

Package an existing talking-head / interview / podcast video with timed, designed GRAPHIC OVERLAY cards — kinetic titles, lower-thirds, data callouts, quotes, side panels, picture-in-picture — synced to the transcript, on a 16:9 / 9:16 / 4:5 canvas of your choice; the clip plays untouched underneath. Trigger on "graphic overlays", "on-screen graphics", "package / dress up my video". Not plain subtitles (/embedded-captions). Unclear → /hyperframes.

相关技能