Communitygithub.com

leocosta/octopus

実際の稼働中のアプリをヘッドレスChromeで操作し、クリーンな静止画をキャプチャして、モーションデザインカット(キネティックタイポグラフィ、シネマティックなズームイン、スポットライトハイライト、電話フレーム、BGM)を合成して、高忠実度なプロモーションビデオを生成するスキルです。アプリに依存せず、プロジェクトごとの設定ファイルとビートリストを読み取り、ターゲットアプリのデザインシステムを自動抽出してオーバーレイをブランドに合わせます。16:9のマスターと9:16の縦型カットを出力します。

octopus とは?

このスキルは、開発中の実際のアプリケーションをヘッドレスブラウザ(Chrome)で駆動し、そのスクリーンショットをキャプチャして、プロフェッショナルなプロモーションビデオを自動生成します。単なる画面録画ではなく、キネティックタイポグラフィ、シネマティックなズームイン、スポットライトハイライト、スマートフォンフレーム、BGMなどを合成した、広告品質の動画を作成します。あらゆるアプリに対応し、`promo.config.mjs` と `beats.json` という設定ファイルを通じて、キャプチャする画面、ハイライトする要素、表示するコピーなどを柔軟に定義できます。さらに、ターゲットアプリのデザインシステム(背景色、アクセントカラー、フォントなど)を自動抽出し、生成されるオーバーレイ要素をアプリのブランドに自動適合させるため、手動調整の手間を大幅に削減します。このスキルは、HyperFrames + GSAP を使用して HTML を MP4 にレンダリングするため、再現性が高く、ブランド管理が容易で、ライブ画面録画によくある失敗(スピナーのキャプチャ、CORSエラーなど)を回避できます。最終的に、16:9の横型マスタービデオと、9:16の縦型(ショート動画用)カットの2種類を出力します。

対応~Claude Code~Codex CLI✓Cursor
npx skills add https://github.com/leocosta/octopus/tree/HEAD/skills/motion-promo

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

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

ドキュメント

Motion Promo Protocol

概要

このスキルは、実際の製品の動的で広告品質のプロモーションビデオをレンダリングします。画面録画やモックアップではありません。ヘッドレスブラウザで実際のアプリをデモ環境に対して駆動し、各画面のクリーンな静止画をキャプチャし、その上にモーションデザインカットを合成します。キネティックタイポグラフィ、シネマティックなズームイン、ズームに追従するスポットライトハイライト、モバイル画面用の電話フレーム、リズミカルなシーンの切り替え、そしてBGMが含まれます。出力は16:9のマスターと9:16の縦型カットです。

これは launch-feature のレンダリング版です。launch-feature は video-script.md(散文形式のスクリプト/ビート)を書き出し、motion-promo はビートリストを完成したスコア付きビデオに変換します。両方を実行する場合は、launch-feature のスクリプト → motion-promo のビートの順にチェーンしてください。

なぜHyperFrames(HTML→MP4)で画面録画ではないのか: 決定論的で、再実行可能で、ブランド管理が可能であり、ライブナビゲーションのキャプチャに伴う障害モード(ルールを参照)を回避できます。アプリは静止画 + デザイントークンの生成にのみ使用され、すべてのモーションはオーサリングされます。

使用すべきタイミング

  • ランディングページ/セールスページに製品デモやヒーロービデオが必要な場合。
  • 機能を発表する際に、スクリプトだけでなくレンダリングされたビデオが必要な場合。
  • 表示するのに適度にリアルなデータが含まれるデモ/サンドボックステナントがある場合。

使用すべきでない場合: 忠実度が重要でない内部ウォークスルー(生の画面キャプチャの方が安上がり)、または実行可能なデモ環境がないアプリ。

前提条件とシークレット

APIキー/シークレットは必要ありません。 HyperFrames render はキーレス(ローカルHTML→MP4)であり、フォント(Google Fonts)とデフォルトの音楽(incompetech)は公開URLです。唯一の認証情報はターゲットアプリのデモログインであり、これはターゲットリポジトリの promo.config.mjs に保存され、このスキルには決して保存されません。認証はプラグイン可能なレシピです。authInject() は注入する値(localStorageのトークン、Cookie、APIキー、複数ステップのテナント選択)を返すか、authFlow(page) はインタラクティブなログインUI(Azure AD / Entra、Okta、Google SSO)を駆動し、エンジンがセッション(localStorage + sessionStorage + cookies、HttpOnlyを含む)をスナップショットします。SSOの認証情報はファイルではなく環境変数から取得されます。ヘッドレスはインタラクティブなMFAを通過できません — MFAが免除されたデモアカウント(Conditional Accessの例外)またはアプリパスワードを使用してください。

システム依存関係(あなたがインストールするもので、スキルはインストールできません): Node 20+、システムChrome(google-chrome/Chromium)、ffmpeg + ffprobe。フォント/音楽のためのネットワーク出力。

自動/オンデマンドの依存関係: hyperframes は npx 経由でオンデマンドで取得されます(事前インストール不要)。puppeteer-core はスキャフォールドされたnpm依存関係であり、システムChromeを使用し、Chromiumをダウンロードしません。

セットアップ: templates/ を video/<slug>/ にスキャフォールドし(hyperframes.json を含む、meta.json はcompose-genによって生成されます)、gitignore を .gitignore にリネームし、npm install を実行してから npm run preflight を実行します(Chrome、ffmpeg/ffprobe、puppeteer-coreを検証し、欠落がある場合はエラーメッセージを表示します)。パイプラインをステップバイステップで実行するか、npm run build を実行します。

  • ターゲットアプリの実行可能なデモ/サンドボックス。

入力

プロジェクト固有のものはすべてターゲットリポジトリにあり、このスキルには決してありません。

  1. promo.config.mjs — 契約書(templates/promo.config.example.mjs を参照)。アプリURL / サーブ方法、認証レシピ、デモアカウント/テナント、出力パス、音楽の設定。デザイントークンは自動抽出されます(ステップ2)が、ここで上書きできます。
  2. beats.json — 順序付けられたショットリスト(templates/beats.schema.json を参照)。各ビート = 画面(ルートまたはキャプチャされた静止画)+ オプションのハイライトターゲット + コールアウトコピー + ビューポート(デスクトップ/モバイル)。

両方を templates/ からターゲットリポジトリの video/<slug>/ にスキャフォールドします。

プロトコル

ターゲットリポジトリの video/<slug>/ 内で作業します。各ステップには検証があります。

0. デモデータを修正する(最初にこれを行ってください — ビデオの成否を分けます)

デモ/サンドボックスのデータは通常、現在の期間に対して古いかゼロです(未払いの当月請求書、空のファネル)。これは 「自動操縦中」 の横に 「R$0の収益」 と表示され、明らかにミスマージです。キャプチャする前に、各ビートに健全な数値を与える冪等で現在日付に相対的なシードを作成してください(ルール → デモデータのゼロ を参照)。各ビートが表示するメトリクスをクエリして検証します。

1. アプリをデモAPIに対して、CORS許可されたオリジンでサーブする

アプリをデモAPIに向けてビルド/サーブします。サーブするオリジンはAPIのCORS許可リストに含まれている必要があります。そうでないと、すべてのデータフェッチがブロックされ、画面は空でレンダリングされます(ルール → CORSオリジン を参照)。APIの許可リストを調査し、許可されたポートでサーブします。検証:ディープルートが200を返し、そのオリジンからの認証された /api/... リクエストが2xxを返すことを確認します。

2. ターゲットアプリのデザインシステムを抽出する

templates/engine/extract-design.mjs を、サーブされ認証されたアプリに対して実行します。計算されたスタイル(ページ背景、ボタン/リンクからのプライマリ/アクセントカラー、見出し + 等幅フォントファミリー、半径)をサンプリングし、design.tokens.json に出力します。これらはCSS変数としてコンポジションに供給され、キネティックオーバーレイ、アクセント、フォントが自動的にアプリのブランドに一致するようにします。サンプリングされたトークンが間違っている場合は、promo.config で確認して上書きします。

3. ビートごとにクリーンな静止画をキャプチャする

templates/engine/capture.mjs を実行します。設定の authInject レシピを介して認証し、各ビートのルートをそのビューポートでナビゲートし、実際のデータが到着するのを待って(network-idle だけではありません — ルールを参照)、assets/<beat>.png にスクリーンショットを撮ります。各静止画にコンテンツが読み込まれていることを確認します(サイズ > ~10 KB、ターゲット要素が存在することをスポットチェックします)。

4. ビートを定義し、コンポジションを生成する

beats.json を記入します(ルート/静止画、ハイライト {x,y,w,h,label} を静止画ピクセル空間で — または {selector,label,padding?} はcapture.mjs によって自動測定され、手調整の座標よりも推奨されます、コールアウト {kicker,headline,sub}、ビューポート、持続時間)。templates/engine/compose-gen.mjs を実行し、templates/composition.html から index.html を生成し、トークンとビートを注入します。パンチの効いたものにします:ビートあたり3~5秒、ハードカット、ビートごとに1つのアイデア。

5. 無料の音楽トラックを取得する

templates/engine/fetch-music.mjs を実行し、assets/music.mp3 を取得します。デフォルトのソースはCC-BY(incompetech)です。CC-BYは帰属表示を必要とします(LPの説明文に記録しておいてください)。可能な場合はプロジェクト提供/CC0のトラックを優先します。

6. レンダリング

npx hyperframes render を実行し、サイレントMP4を生成します。最初に hyperframes lint/inspect を実行します。キャンバス外の装飾/終了アニメーションのオーバーフローはノイズとして扱い、実際のテキストのクリッピングは修正します。

7. フレームを確認し、ハイライトの位置合わせを修正する

各ズームインの開始時と終了時のフレームを抽出し、目視で確認します。最も一般的な欠陥:ズーム中にスポットライトハイライトがターゲットからずれる — これは、ハイライトボックスが拡大縮小されるコンテナの子要素である必要があるためです(ルール → ハイライトの追跡 を参照)。また、空/スピナー画面がないこと、モバイル画面が電話フレーム内にきれいに収まっていること、コピーが読みやすいことを確認します。

8. 音楽をミックスする

templates/engine/mux.mjs を実行し、最終的なスコア付きMP4を生成します(loudnorm、フェードイン/アウト、-shortest)。出力にオーディオストリームがあり、ビデオの長さと一致していることを確認します。

9. 9:16カットを派生させる

mux.mjs --reframe を実行すると、1080×1920のカットが生成されます。中央をクロップしないでください(下部に固定されたコールアウトが切り取られます) — 代わりに、フレーム全体を保持するぼかしレターボックスを使用します。モバイルビートは既に中央に配置されています。

ルール(苦労して得た教訓 — 再学習しないでください)

  • ハイライトの追跡。 ズームインする画面の上にあるスポットライト/ハイライト矩形は、静止画のピクセル座標空間において、scale 変換を受け取る同じ要素の子要素でなければなりません。兄弟要素の場合、画像がズームする間は固定されたままになり、ショット全体でターゲットからずれていきます。
  • デモデータのゼロ。 現在の期間は多くの場合、未払いまたは空です。冪等(決定論的なID、削除してから挿入)で、current_date に相対的なシードで修正し、期間ごとに自動修復されるようにします。
  • CORSオリジン。 ローカルでサーブされたビルドがデプロイされたデモAPIを呼び出すことは、クロスオリジンです。APIが許可リストに登録しているオリジンでサーブしてください(調査すること) — 決してブラウザのウェブセキュリティを無効にして回避しないでください。
  • 実際のデータを待つ。 networkidle2 は、アプリのデータリクエストが到着する前に解決される可能性があります。その結果、スピナーをキャプチャすることになります。スクリーンショットを撮る前に、成功した /api/... レスポンス(またはターゲットコンテンツセレクター)をさらに待ちます。
  • ライブキャプチャよりもHyperFramesを優先。 CDPスクリーンキャストは、視覚的に静的なページでフレームの出力を停止し、公称fpsを下回って実行されます。HTML(GSAP)でオーサリングすることで、両方を回避できます。どうしてもライブ録画する必要がある場合は、カーソルをジッターさせ、実効 fps でエンコードします。
  • 音楽ライセンス。 CC-BY(incompetech/Kevin MacLeod)はLPの説明文に帰属表示が必要です。CC0(Pixabayなど)は必要ありません。公開ページでライセンス未取得のスクレイピングクリップを決して公開しないでください。
  • セグメントのfpsが異なる場合は、デマルチプレクサではなくフィルタで結合 — デマルチプレクサはフレームを静かにドロップします。

デザインシステム抽出(アプリに依存しないブランディング)

コンポジションはブランドニュートラルです。extract-design.mjs が、ターゲットアプリ自体 からCSS変数を埋めます。--bg(本文背景)、--accent(プライマリ/リンク色)、--fg(見出し色)、--font-hero/--font-mono(計算されたフォントファミリー)、--radius。これにより、1つのスキルで、トークンを手動で選択することなく、あらゆるアプリのブランドに合ったプロモーションを生成できるようになります。サンプリングされたトークンは常に確認してください。コントラストが低い場合やアドホックな色が誤ってサンプリングされることがあります。その場合は promo.config.design で上書きします。

エラー

  • アプリがヘッドレスで認証されない → 設定の authInject レシピが間違っています。最初のナビゲーションの前に、トークンが localStorage/Cookie に配置されていることを確認します。
  • 画面が空でレンダリングされる → CORSオリジン(ステップ1)またはデータ待機(ルール)を見逃しています。
  • レンダリングのキャンバス外エラー → 実際のテキストクリッピングは、より小さいフォント/折り返しが必要です。装飾/終了オーバーフローはノイズです。
  • ハイライトの位置ずれ → 拡大縮小されるコンテナの子要素ではありません(ルール)。

マーケターロールとの連携

コピーにはマーケターロールを使用します。キッカー、ヘッドライン、ビートごとのバリューフレーミングは、プロジェクトのボイス(存在する場合は launch-feature の voice.md / marketer-hooks.md)に従う必要があります。画面上のコピーは、ビートごとにキッカー + 短いヘッドライン + 1行のサブラインに抑えます。

関連スキル