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 の開発ループ全体をガイドします。`npx hyperframes` を介して、プロジェクトのスキャフォールディング、HTML コンポジションの記述、lint/validate/inspect による静的チェック、Studio でのプレビュー、そしてローカルまたは AWS Lambda を使用したクラウドでのレンダリングまでをカバーします。各コマンドの使用方法、出力形式(JSON 対応など)、エージェントによる利用時の規約(非 TTY モードの自動検出、レンダリング前のユーザー承認の必要性など)が詳細に定義されています。特に、motion ファイルを用いたモーションベリファイアや、サブコンポジションのマウントエラーを検出するスナップショット機能など、高度なデバッグ手法も提供します。Lambda サブシステムは、大規模・長時間のレンダリングを AWS 上で分散処理するための完全なコマンドセット(deploy / render / progress / destroy / policies)を備えています。

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

お気に入りのAIに質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

ドキュメント

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. 検証 — 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。これにより、CI パイプラインが CLI リリースの変動から保護されます。
  • 非 TTY モードは自動検出されます。 stdout が TTY でない場合(CI、エージェント、パイプ出力)、CLI は自動的に非対話モードに切り替わります。この場合、init は --example を必須とします。TTY 上でも強制的にこのモードにするには --non-interactive を渡してください。
  • CI でのレンダリングゲート:--strict は lint エラーで失敗、--strict-all は警告でも失敗、--strict-variables は未宣言の --variables キーで失敗します。
  • --json 内のパスは秘匿化されます — $HOME はリテラル文字列 $HOME になるため、出力をバグレポートやエージェントコンテキストに安全に貼り付けることができます。
  • レンダリングはユーザーゲート付きです。 チェックが通ったら自動的にレンダリングしないでください。preview で止まり、ユーザーにビデオが Studio で編集可能であることを伝え、ユーザーの承認を得てからレンダリングしてください。
  • レンダリング後検証。 render が終了コード 0 を返した後、出力ファイルが存在し、妥当なサイズであることを確認してから成功を報告してください:[ -s "$OUTPUT" ] || echo "render produced no output"。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)→ 音声選択、Whisper モデルルール、キャプション、TTS-to-captions チェーンには hyperframes-media を使用してください。
  • パラメーター化レンダリング(--variables)→ <html> 上の data-composition-variables で宣言します。完全なスキーマは hyperframes-core を参照してください。

Lambda(クラウドレンダリング)

hyperframes lambda は分散レンダリングを AWS Lambda にデプロイし、ラップトップまたは CI からレンダリングを駆動します。エンドツーエンドは 3 つのコマンドです:

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 バケットは保持)

レンダリングが 1 台のホストでは長すぎる / 大きすぎる場合(複数分のビデオ、4K、大規模な並列バッチ)、かつ AWS 認証情報が設定されている場合に Lambda を使用してください。開発ループのイテレーションではローカルの render を使用してください。

前提条件、6 つのサブコマンドすべて(deploy、sites create、render、progress、destroy、policies)、IAM ポリシーの検証、ステートファイル、コスト / クリーンアップルールについては references/lambda.md を参照してください。

最小完了ゲート

静的ゲート

npx hyperframes lint
npx hyperframes validate

レイアウトに関わる作業では inspect を、CI では lint エラーで失敗させるために render --strict を追加してください。

ビジュアルスモークテスト — プロジェクトがサブコンポジションを使用する場合に必須

lint / validate / inspect は各コンポジションを独立して評価します。index.html を読み込んで data-composition-src 経由でサブコンポジションをマウントすることはありません。そのため、クロスファイルのマウント障害を捕捉できません(hyperframes-core → references/sub-compositions.md、「よくある落とし穴」を参照)。これらを捕捉できる唯一のゲートは、実際に index.html を読み込み、タイムラインをシークするものです。

hyperframes snapshot を使用してください。これは render と同じ方法でプロジェクトを読み込むため(同じマウントパスを実行)、完全なレンダリングではなく、要求したタイムスタンプのみをキャプチャするため、秒単位で完了します:

# 各サブコンポジションの中間点で 1 フレームをキャプチャ。
# 中間点 = 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> ブロックが <template> の外の <head> に残っている(落とし穴 1)— CSS がライブ DOM に届いていない
SVG/アイコン要素がキャンバスサイズに引き伸ばされている同上 — 幅/高さの制約が適用されていない
シーンの主要要素が完全に欠落し、背景と透かしだけが見えるHost-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.

関連スキル