Communitygithub.com

1345AbhishekKumar/starter-nextjs

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-nextjs とは?

このスキルは、HyperFrames CLI の完全な開発ループを定義し、AI エージェントがビデオ合成プロジェクトを効率的にスキャフォールド、リント、検証、プレビュー、レンダリングできるようにします。Node.js >= 22 と FFmpeg が必要です。ワークフローは、プロジェクトのスキャフォールドから始まり、作成、検証(lint、validate、inspect を使用)、プレビュー(Studio タイムラインエディタで編集可能)、そしてドラフト品質または高品質でのレンダリングへと進みます。CI パイプラインとエージェントの自動化をサポートしており、JSON 出力、非 TTY モードの自動検出、厳格なゲート(--strict, --strict-all, --strict-variables)を備えています。主な機能には、モーションヘビーな作業のためのスナップショット駆動型反復、AWS Lambda を使用したクラウドレンダリング、サブコンポジションのクロスファイルマウント障害をキャッチする視覚的スモークテストが含まれます。このスキルは、HyperFrames エコシステム内の他のスキル(hyperframes-core、hyperframes-registry、hyperframes-media)と連携し、Tailwind の統合、コンポーネントレジストリ、アセット前処理(TTS、文字起こし、背景除去)を処理します。

対応~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/1345AbhishekKumar/starter-nextjs/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. リント — 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。これにより、パイプラインを 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 からキャプションへのチェーンには 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 バケットは保持されます)

Lambda は、1 台のホストではレンダリングが長すぎる/大きすぎる場合(数分の動画、4K、大規模な並列バッチ)に、AWS 認証情報が設定されている場合に使用します。開発ループの反復では、ローカルの 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 と同じ方法でプロジェクトを読み込むため(同じマウントパスを実行します)、要求したタイムスタンプのみをキャプチャするため、フルレンダリングの代わりに数秒で完了します:

# 各サブコンポジションの中間点で 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/アイコン要素がキャンバスサイズに拡大されて表示される同上 — 幅/高さの制約が適用されていない
シーンのヒーロー要素が完全に欠落しており、背景とウォーターマークのみ表示されるホスト 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-nextjs

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-nextjs

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-nextjs

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-nextjs

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-nextjs

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-nextjs

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-nextjs

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-nextjs

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-nextjs

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-nextjs

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-nextjs

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-nextjs

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-nextjs

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.

関連スキル