Communitygithub.com

1345AbhishekKumar/starter-supabase

HyperFrames CLI 开发循环。用于运行 npx hyperframes init、add、catalog、capture、lint、validate、inspect、layout、snapshot、preview、play、render、publish、lambda、doctor、browser、info、upgrade、skills、compositions、docs、benchmark、telemetry、transcribe、tts 或 remove-background,或排查 HyperFrames 构建/渲染环境问题时使用。也是 AWS Lambda 云端渲染(`hyperframes lambda deploy / render / progress / destroy / policies`)的入口点。

starter-supabase 是什么?

该技能为 HyperFrames CLI 提供了完整的本地开发循环和云端渲染能力。它专为 Node.js >= 22 和 FFmpeg 环境设计,支持从项目脚手架搭建(`init`)到最终高品质渲染(`render`)的端到端流程。技能核心工作流包括:编写 HTML 组合、通过 `lint` 检查缺失的 data-composition-id、通过 `validate` 在无头 Chrome 中运行时错误和 WCAG 对比度、通过 `inspect` 验证文本溢出和运动意图(结合 *.motion.json 侧车文件),以及通过 `preview` 启动可视化时间线编辑器 Studio 供用户手动调整。渲染支持本地草稿/交付模式、Docker 严格模式,以及通过 AWS Lambda 进行分布式云端渲染(适合长视频、4K 或大批量任务)。Lambda 子命令包括 deploy、sites create、render、progress、destroy 和 policies,并自动进行 IAM 策略验证和状态文件管理。技能还强调了代理约定(如 `--json` 输出、非 TTY 自动检测、渲染前用户确认、CI 门控 `--strict` 等)以及跨技能交接(如 Tailwind 项目、注册表块、资产预处理、参数化渲染)。

兼容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/1345AbhishekKumar/starter-supabase/tree/HEAD/.agents/skills/hyperframes-cli

在你喜欢的 AI 中提问

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

文档

HyperFrames CLI

所有操作通过 npx hyperframes 运行,除非项目说明指定了本地包装器。必须严格遵循本地包装器。需要 Node.js >= 22 和 FFmpeg。

工作流程

  1. 构建脚手架 — npx hyperframes init my-video(或从 URL 使用 capture)
  2. 编写 — 编写 HTML 组合(参见 hyperframes-core 技能)
  3. Lint — npx hyperframes lint
  4. Validate — npx hyperframes validate(运行时错误 + 对比度)
  5. 可视化检查 — npx hyperframes inspect
  6. 预览 — npx hyperframes preview 打开 Studio,这是一个时间线编辑器,用户可以在其中手动编辑任何内容(而不仅仅是观看)。在那里审查,然后在渲染前询问。
  7. 渲染 — 选择变体:
    • 迭代:npx hyperframes render --quality draft
    • 交付:npx hyperframes render --quality high --output out.mp4
    • CI / 跨主机复现:npx hyperframes render --docker --strict --output out.mp4
    • 云端(长 / 大):npx hyperframes lambda render ./my-project --width 1920 --height 1080 --wait(参见下方 Lambda)

在预览前运行 lint、validate 和 inspect。lint 捕获丢失的 data-composition-id、重叠轨道和未注册的时间线。validate 在无头 Chrome 中加载组合并报告运行时控制台错误以及 WCAG 对比度问题。inspect 遍历时间线并报告从气泡/容器或画布中溢出的文本——并且当存在 *.motion.json 侧车文件时,它会针对相同的遍历时间线验证运动意图(进入触发时间、交错顺序、在帧内、活跃度)。

对于运动密集型工作,首选基于快照的迭代和 *.motion.json 侧车文件——有关规则和运动验证规范,请参见 references/lint-validate-inspect.md。

代理约定

适用于每个命令的横切规则:

  • --json 在每个命令上都可用,除了 render、preview 和 play。 对于任何代理 / CI 调用支持的命令,请使用它;输出包含一个 _meta 信封(cli 版本、最新可用版本、更新建议)。render 仅通过 stdout + 退出代码报告状态——使用下面的渲染后检查验证成功;preview / play 是服务器,不输出 JSON。
  • doctor --json 总是以 0 退出,即使环境已损坏。通过负载的 ok 字段进行门控:npx hyperframes doctor --json | jq -e '.ok' > /dev/null。这使管道免受 CLI 版本发布波动的影响。
  • 自动检测非 TTY 模式。 当 stdout 不是 TTY(CI、代理、管道输出)时,CLI 自动切换到非交互模式;此时 init 需要 --example。传递 --non-interactive 可在 TTY 上强制使用此模式。
  • CI 对渲染的门控:--strict 在 lint 错误时失败,--strict-all 在警告时也失败,--strict-variables 在未声明的 --variables 键上失败。
  • --json 中的路径会被处理 — $HOME 变为字面量 $HOME,因此输出可以安全地粘贴到错误报告和代理上下文中。
  • 渲染需要用户许可。 一旦检查通过,切勿自动渲染。在 preview 处暂停,告诉用户视频可以在 Studio 中编辑,并且只有在他们批准后才渲染。
  • 渲染后验证。 在 render 返回退出码 0 后,确认输出文件存在并且大小合理,然后再报告成功:[ -s "$OUTPUT" ] || echo "渲染未产生输出"。CLI 在成功时打印 ◇ <path>;对于长渲染,还使用 ffprobe -i "$OUTPUT" -show_format -v error 进行健全性检查时长。

路由

想要…阅读
构建项目(init、capture、skills)references/init-and-scaffold.md
检查正确性(lint、validate、inspect、snapshot)references/lint-validate-inspect.md
预览或渲染(preview、play、render、publish)references/preview-render.md
诊断环境(doctor、browser)references/doctor-browser.md
在 AWS Lambda 上云端渲染(lambda deploy / sites / render / progress / destroy / policies)references/lambda.md
其他所有内容(info、upgrade、compositions、docs、benchmark、telemetry、资源预处理器)references/upgrade-info-misc.md

跨技能交接

  • Tailwind 项目(init --tailwind)→ 在编辑类或主题令牌之前使用 hyperframes-core(Tailwind 参考)。
  • 注册表块/组件(hyperframes add、hyperframes catalog)→ 使用 hyperframes-registry 处理安装路径、子组合连接和代码片段合并。
  • 资源预处理(tts、transcribe、remove-background)→ 使用 hyperframes-media 处理语音选择、Whisper 模型规则、字幕以及 TTS 到字幕链。
  • 参数化渲染(--variables)→ 通过在 <html> 上声明的 data-composition-variables;完整模式请参见 hyperframes-core。

Lambda(云端渲染)

hyperframes lambda 将分布式渲染部署到 AWS Lambda,并从您的笔记本电脑或 CI 驱动渲染。端到端需要三个命令:

npx hyperframes lambda deploy                                             # 配置 SAM 堆栈(Lambda + Step Functions + S3)
npx hyperframes lambda render ./my-project --width 1920 --height 1080 --wait
npx hyperframes lambda destroy                                            # 拆除(保留 S3 存储桶)

当渲染对于一个主机来说时间过长 / 体积过大(多分钟视频、4K、大批量并行任务)并且您已配置 AWS 凭据时,请使用 Lambda。对于开发循环迭代,请继续使用本地 render。

有关先决条件、所有 6 个子命令(deploy、sites create、render、progress、destroy、policies)、IAM 策略验证、状态文件以及成本/清理规则,请参见 references/lambda.md。

最低完成门控

静态门控

npx hyperframes lint
npx hyperframes validate

对于布局敏感的工作添加 inspect,并在 CI 中添加 render --strict 以在 lint 错误时失败。

视觉冒烟测试 — 当项目使用子组合时必须执行

lint / validate / inspect 孤立地评估每个组合。它们从不加载 index.html 并通过 data-composition-src 挂载子组合,因此它们无法捕获跨文件挂载失败(参见 hyperframes-core → references/sub-compositions.md,"常见陷阱")。唯一能捕获它们的是实际加载 index.html 并遍历时间线的门控。

使用 hyperframes snapshot — 它与 render 加载项目的方式相同(因此它执行相同的挂载路径),但只捕获您请求的时间戳,因此只需几秒钟而不是完整渲染:

# 在每个子组合的中点捕获一帧。
# 中点 = index.html 中每个宿主槽的 data-start + data-duration/2。
npx hyperframes snapshot --at <t1>,<t2>,<t3>,...

# 或者,如果您不需要按场景定位,可以使用均匀间隔的样本:
npx hyperframes snapshot --frames 9

输出位于 snapshots/frame-NN-at-Xs.png。目视检查每一帧与场景计划。

每帧红色标记(每个都映射到静态门控遗漏的特定失败模式):

您看到的根本原因
文本在左上角显示为微小 + 无样式<style> 块留在了 <head> 中的 <template> 外部(陷阱 1)——没有 CSS 到达实时 DOM
SVG/图标元素放大到画布大小同上——未应用宽度/高度约束
场景的主角元素完全丢失;仅可见背景和水印宿主 id ≠ 模板 id(陷阱 2)——时间线从未运行,在初始状态捕获帧
快照命令记录 Sub-composition timelines not registered after 45000ms陷阱 2 —— 直接确认

snapshots/ 可以在目视检查后删除;面向用户的最终渲染是通过 npx hyperframes render 进行的单独过程。

Individual skills in this repo

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

1345AbhishekKumar/starter-supabase

Add captions to a talking-head video. ONE catalog (CATALOG.md) of 32 visual identities behind two engines: column-flow (captions composited INTO the scene — matte occlusion + mix-blend; cream/ink/editorial/keynote/documentary/loud/neon/glitch/chrome/velocity) and themed constitutions (anchor/ordnance/terminal/neonsign/stardust/stomp/scoreboard/transit/vhs/arcade/dossier/laser/thunder/hologram/biolume/aurora/spectrum/papercut/popup/chalkboard/graffiti/brush/inkwater/ransom/lastpage/nightcity — e.g. a glyph-decode climax, a neon sign WRITTEN stroke by stroke, or the quiet `anchor` rail default). Route by identity, never by mode. Trigger on "captions/subtitles", "embed/cinematic captions", "VFX captions", "炸/特效/酷炫字幕", a named identity, or top-tier motion-graphics asks. Embedding every word is wrong for most talking-head content — `anchor` is the verbatim default. Pipeline: transcription → hyperframes remove-background matting → HTML render → ffmpeg overlay. Requires hyperframes and a single-subject clip.

1345AbhishekKumar/starter-supabase

The fallback workflow for authoring custom HyperFrames video compositions at any length or format — longer or multi-scene pieces, brand / sizzle reels, montages, title cards, static loops, and freeform compositions. Input- and length-agnostic. If a specialized workflow clearly fits the input — a marketed product, a website, a topic explainer, a GitHub PR, existing footage, a short motion graphic, or a Remotion port — prefer it (see /hyperframes); use this only as the general fallback when none fit.

1345AbhishekKumar/starter-supabase

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). HyperFrames-native: single paused timeline, seek-safe, deterministic.

1345AbhishekKumar/starter-supabase

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.

1345AbhishekKumar/starter-supabase

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`.

1345AbhishekKumar/starter-supabase

Audio and media assets for HyperFrames compositions, produced by one shared audio engine (`scripts/audio.mjs`) — multi-provider TTS (HeyGen / ElevenLabs / Kokoro local), background music + sound effects (HeyGen audio-library retrieval by default, with local Lyria / MusicGen BGM generation and a bundled SFX library as the no-credential fallback), Whisper transcription, background removal, and caption authoring. Use for voiceover / TTS, BGM, SFX / sound effects, transcription, captions / subtitles / lyrics / karaoke / per-word styling, voice + provider selection, and music-mood prompting.

1345AbhishekKumar/starter-supabase

Install and wire registry blocks and components into HyperFrames compositions. Use when running hyperframes add, installing a block or component, wiring an installed item into index.html, or working with hyperframes.json. Covers the add command, install locations, block sub-composition wiring, component snippet merging, registry discovery, and authoring a new block or component to contribute upstream (idea → scaffold → validate → PR).

1345AbhishekKumar/starter-supabase

Use when the user wants a short, design-led motion graphic where motion is the message: kinetic typography, stat or number count-up, chart/data-viz hit, logo sting, brand lockup, lower-third, callout, social overlay, animated headline/tweet/news item, motion poster, or quick captured-page highlight. Usually under 10s and up to ~30s, with no narration arc, voice-over, or live-action subject. Can render to MP4 or transparent overlay. Not for longer, multi-scene, narrated, or brand-reel pieces (use general-video), narrated website videos (website-to-video), topic explainers (faceless-explainer), product promos (product-launch-video), PR videos (pr-to-video), or captions on existing footage (embedded-captions). When unsure whether it's a quick motion-first piece or a longer / narrated treatment, see /hyperframes.

1345AbhishekKumar/starter-supabase

Use when the user has a music track (an audio file, or a video to pull audio from) and wants a beat-synced HyperFrames video, calm to hard-hitting. The music drives everything: one analyzer reads it once, the orchestrator lays out the frames and fills a per-frame plan, and one sub-agent builds each frame. Typography and templates are the floor — a complete video needs zero assets — but any images or videos the user supplies are cut into the frames on the same beat grid (beat-cut / ken-burns). The genre (lyric video, slideshow, kinetic promo) falls out of the per-frame choices; the pipeline never branches on it.

1345AbhishekKumar/starter-supabase

turn a product or marketing URL, pasted script, or brief into a product launch video, including SaaS promos, feature reveals, app launches, company promos, and product marketing videos. Use this skill when the user wants to market, launch, promote, or reveal a product. Do not use it for general non-launch website tours, non-product topic explainers, GitHub pull requests, captioning existing footage, or short unnarrated motion graphics. If the intent is unclear, route through /hyperframes first. This is the new shot-sequence architecture: every visual frame is authored as a time-coded shot sequence picked from a menu of golden blueprints, so frames develop over their full duration instead of freezing after entrance.

1345AbhishekKumar/starter-supabase

turn a GitHub pull request (a PR URL like github.com/<owner>/<repo>/pull/<N>, an <owner>/<repo>#<N> ref, or 'this PR' in a checked-out repo) into a code-change explainer video, up to ~3 min (sweet spot 30-90s) — changelog, feature reveal, fix, or refactor walkthrough, rendered from the diff / commits / files. The input is a CODE CHANGE read via the gh CLI; there is no website capture. Use this skill for a GitHub PR. Do not use it for a product launch/promo (use /product-launch-video), a tour of a real website (use /website-to-video), a topic explainer with no PR (use /faceless-explainer), captions on existing footage (use /embedded-captions), or a short unnarrated motion graphic (use /motion-graphics). If the intent is unclear, route through /hyperframes first.

1345AbhishekKumar/starter-supabase

Port an existing Remotion (React) composition to HyperFrames HTML. Use ONLY when the user explicitly asks to port/convert/migrate/translate a Remotion source. Do NOT use: (a) authoring a new HyperFrames composition; (b) Remotion mentioned in passing; (c) Remotion code shared as reference only; (d) "same video as my Remotion one" without explicit migrate request — treat as fresh build. Doubt → `/general-video`. One-way, Remotion-only: no reverse export (HyperFrames→Remotion or any framework), no non-Remotion source (After Effects, Framer Motion, plain React/CSS) → out of scope, re-create via `/general-video`. Flags unsupported patterns (useState, useEffect, async calculateMetadata, third-party React libs, `@remotion/lambda`) and recommends runtime interop over lossy translation. Unsure whether to port vs. build fresh, or only a passing Remotion mention? → /hyperframes.

1345AbhishekKumar/starter-supabase

Capture a general website/URL and turn it into a HyperFrames video (site tour, showcase, or social clip from the site's own visuals). Uses headless Chrome screenshots + brand assets. Use when intent is general — portfolio/blog/landing-page showcase or social clip from the site. NOT for: product/SaaS launch or promo (→ /product-launch-video, even from a URL); topic explainer with no site (→ /faceless-explainer); GitHub PR (→ /pr-to-video); adding captions to existing video (→ /embedded-captions); short unnarrated page-highlight motion graphic (→ /motion-graphics). Unclear launch-vs-general-site? Ask one question or start at /hyperframes.

相关技能