Communitygithub.com

Army161/OpenMontage

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`)のエントリポイントです。

OpenMontage とは?

このスキルは、HyperFrames 動画エディタの CLI 開発ループ全体をカバーします。プロジェクトのスキャフォールディング、HTML コンポジションのリンティングと検証、Studio タイムラインエディタでのプレビュー、ローカルまたは AWS Lambda でのレンダリングなど、すべての主要コマンドを説明しています。主な利点は、AI エージェントと CI パイプライン向けに最適化された、統一された `--json` 出力と非 TTY モードの自動検出です。`doctor --json` コマンドは常に終了コード 0 を返しますが、環境の健全性はペイロードの `ok` フィールドで評価する必要があります。`snapshot` コマンドは、静的な lint/validate では見つからないクロスファイルマウントエラーを迅速に特定できるため、サブコンポジションを含むプロジェクトでは必須の視覚的スモークテストとして機能します。レンダリングはユーザー承認が必要であり、レンダリング後は出力ファイルの存在確認と `ffprobe` による期間の妥当性チェックが推奨されます。

対応~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Army161/OpenMontage/tree/HEAD/.agents/skills/hyperframes-cli

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

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

ドキュメント

HyperFrames CLI

すべての操作は、プロジェクトの指示でローカルラッパーが指定されていない限り npx hyperframes を介して実行します。ローカルラッパーがある場合は、それを厳密に守ってください。Node.js 22 以上と FFmpeg が必要です。

ワークフロー

  1. スキャフォールド — npx hyperframes init my-video(または URL からの capture)。init はインストール済みのスキルを GitHub 上の最新版と照合し、古いものがあればグローバルセットを更新します。--skip-skills フラグは現在無効化されています(一時的措置。skills.sh レジストリが追い付くまでの間)。そのため、すべての init でこのチェックが実行され、最新のスキルが強制的に pull されます。
  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 バケットは保持)

レンダリングが 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/アイコン要素がキャンバスサイズに拡大される同上 - 幅/高さの制約が適用されていない
シーンのヒーロー要素が完全に欠落し、背景と透かしのみ表示されるホスト ID ≠ テンプレート ID(落とし穴 2)- タイムラインが実行されず、初期状態のフレームがキャプチャされた
スナップショットコマンドが Sub-composition timelines not registered after 45000ms をログ出力落とし穴 2 - 直接確認

snapshots/ は目視確認後に削除して問題ありません。最終的なユーザー向けレンダリングは npx hyperframes render での別パスです。

Individual skills in this repo

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

Army161/OpenMontage

Generate AI videos from text prompts using multiple provider gateways. Use when: (1) Generating videos from text descriptions, (2) Creating AI-generated video clips for content production, (3) Image-to-video generation with a reference image, (4) Choosing between video generation providers (VEO, Kling, Sora, Runway, Seedance, MiniMax). Supports two gateways: HeyGen API and fal.ai API.

Army161/OpenMontage

Create AI avatar videos with precise control over avatars, voices, scripts, scenes, and backgrounds using HeyGen's v2 API. Use when: (1) Choosing a specific avatar and voice for a video, (2) Writing exact scripts for an avatar to speak, (3) Building multi-scene videos with different backgrounds per scene, (4) Creating transparent WebM videos for compositing, (5) Using talking photos as video presenters, (6) Integrating HeyGen avatars with Remotion, (7) Batch video generation with exact specs, (8) Brand-consistent production videos with precise control.

Army161/OpenMontage

Use p5.js/canvas for local procedural character effects: particles, weather, squash/stretch, walk cycles, and environmental motion.

Army161/OpenMontage

Review local character animation with schema checks, Playwright browser previews, frame sampling, and FFmpeg/ffprobe final output checks.

Army161/OpenMontage

Create videos from a text prompt using HeyGen's Video Agent. Use when: (1) Creating a video from a description or idea, (2) Generating explainer, demo, or marketing videos from a prompt, (3) Making a video without specifying exact avatars, voices, or scenes, (4) Quick video prototyping or drafts, (5) One-shot prompt-to-video generation, (6) User says "make me a video" or "create a video about X".

Army161/OpenMontage

Generate Mandarin and multilingual narration with Volcengine Doubao Speech 2.0. Use when creating Chinese voiceovers, when the user prefers Doubao/Volcengine/火山引擎/豆包 TTS, or when narration needs character-level timestamp metadata for subtitles.

Army161/OpenMontage

Video and audio processing with FFmpeg. Use for format conversion, resizing, compression, audio extraction, and preparing assets for Remotion. Triggers include converting GIF to MP4, resizing video, extracting audio, compressing files, or any media transformation task.

Army161/OpenMontage

Use when implementing Disney's 12 animation principles with Framer Motion in React applications

Army161/OpenMontage

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.

Army161/OpenMontage

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.

Army161/OpenMontage

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

Army161/OpenMontage

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.

Army161/OpenMontage

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

Army161/OpenMontage

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.

Army161/OpenMontage

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.

Army161/OpenMontage

Best practices for Remotion - Video creation in React

Army161/OpenMontage

Toolkit-specific Remotion patterns — custom transitions, shared components, and project conventions. For core Remotion framework knowledge (hooks, animations, rendering, etc.), see the `remotion-official` skill.

Army161/OpenMontage

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.

Army161/OpenMontage

Animate SVG character rigs with GSAP, CSS transforms, Remotion frame control, and HyperFrames-compatible browser previews.

Army161/OpenMontage

Three.js animation - keyframe animation, skeletal animation, morph targets, animation mixing. Use when animating objects, playing GLTF animations, creating procedural motion, or blending animations.

関連スキル