BeaverMakerLab/code-to-video

Code-to-Video Explainer Studio（汎用コード化アニメーションビデオエンジン）

📘 詳細な使用説明書はこちら：README.md（環境チェック、6つのスタイルガイド、ナレーション設定、クロスエージェントマウント方法、トラブルシューティングマニュアルを含む）

このスキルにより、ファイルの読み書きとコマンドライン実行が可能な AIコーディングエージェント（Claude Code、Codex、DeepSeek Harness、OpenHands/OpenClaw、Antigravity、Cursorなど）は、プロのビデオ総監督、アニメーションプログラマー、プロデューサーに変身します。ローカルのコード化ビデオレンダリングエンジンを駆動し、任意のテキスト、コードリポジトリ、論文、アイデアを、1080p 60fpsのインク・ペーパー質感の高精細アニメーション解説動画に迅速に変換します。

---

核となる3つの鉄則（全エージェントは厳守すること）

1. ストーリーボードを先に決定し、その後でコードを書く（Human-in-the-Loop）： ユーザーが storyboard.json を明確に承認するまで、具体的なページコードの作成や最終レンダリングの実行は一切禁止。
2. 時間は純粋関数 $Visual = f(t)$： ページコードは、時間変数 $t$ の純粋関数でなければなりません。Math.random()（乱数は PV.rng(seed) を使用）、Date.now()、CSS transitions / requestAnimationFrame の使用は禁止。
3. 字幕のための退避エリア（セーフゾーン）： キャンバスサイズは 1920×1080。下部エリア $y > 900$ は字幕専用帯であり、いかなる主体図形やテキストも配置禁止。コンテンツの主要活動エリアは x: 140~1780, y: 180~880 に維持すること。

---

制作パイプライン（標準5ステップワークフロー）

ステップ1：素材の消化とストーリーボードデザイン（Storyboard）

ユーザーが動画制作のリクエスト（または資料）を提出した場合：

1. 核となるメタファーの確立：動画全体を貫く1つの具体的なイメージを抽出します（例：注意機構の説明には「スポットライト」、キャッシュの説明には「机の上の付箋」、流体方程式の説明には「水槽とパイプ」）。
2. ナラティブ構造の計画：
   • フック（最初の3秒）：直感に反する質問や核心的な課題を提示。
   • 直感の構築：核となるメタファーを導入。
   • メカニズムの解説：核となる公式や手順を分解。
   • 事例と数値：具体的なデータで説明。
   • まとめと収束：冒頭のフックに答え、首尾一貫させる。
3. ストーリーボード構造の生成： 4〜8ページのストーリーボードアウトラインを出力し、各ページに id、section、say（ナレーションの概要）、および2〜4個の beats（具体的なアクションポイント：object、action、text、cameraを含む）を明記します。
4. ユーザー確認の依頼： ストーリーボードをユーザーに提示し、「ストーリーボードアウトラインが生成されました。各ページの構造とナレーションのリズムをご確認ください。問題がなければコード描画フェーズに進みます。」と確認を求めます。

詳細な仕様と構造テンプレートについては、STORYBOARD_RULES.md を参照してください。

---

ステップ2：スクリプトとタイムラインの生成（Script & Narration）

ストーリーボード確認後、script.js を確立します：

1. 各ページの具体的なナレーション台詞を抽出し、各文が16文字以内の cues（字幕用短文）に分割します。
2. 音声エンジン（ローカルの CosyVoice 3 ポート 9880、Edge-TTS、または環境変数 VOLCENGINE_TTS_API_KEY / ELEVENLABS_API_KEY で指定）を呼び出し、各文の音声を生成します。
3. 実際の読み上げタイムスタンプを抽出し、各 cue に物理的な時間ポイント（P.c(i) で開始時刻、P.cw(i, 'キーワード') で単語レベルのヒット時刻）を割り当てます。

---

ステップ3：ページごとのアニメーションプログラミング（Page Drawing Code）

各ページの画面は pages/pNN.js ファイルに対応し、エンジンの宣言的APIを使用して記述します：

ENGINE.visual('p01', (P) => {
  P.title('① コア原理の直感', { accent: 'orange' });
  // ナレーションの0番目のキューにバインドしてメインカードを展開
  P.card(200, 260, 700, 480, { title: '入力特徴', at: P.c(0) });
  // 特定の単語が発声された時に矢印とハイライトをトリガー
  P.arrow(920, 500, 1100, 500, { at: P.cw(1, '変換') });
  // 数式の段階的導出
  P.mathDecompose(1140, 400, 600, {
    title: '注意スコア',
    terms: [
      { latex: 'Q K^T', name: 'クエリとキーの積', color: 'blue', at: P.c(2) },
      { latex: '\\sqrt{d_k}', name: 'スケーリング係数', color: 'orange', at: P.c(3) }
    ]
  });
});

ヒント：サブエージェントや並列タスクをサポートするエージェント環境では、複数のサブエージェントを派遣して異なるページを並行して作成し、生成速度を向上させることができます。 完全なAPI構文とコンポーネント一覧については、API.md を参照してください。

---

ステップ4：幾何学的・視覚的自己チェックループ（Automated QA Loop）

コード作成後、必ず自己チェックを実行すること。スキップは禁止：

1. プロジェクトディレクトリでチェックツールを実行します：

   node engine/tools/check.mjs --only p01
   

2. フィードバックの処理：
   • Collision detected または Safe zone overlap が発生した場合：
   • 出力中の Fix suggestion: ... を抽出し、提案された座標を直接採用して pages/pNN.js の座標値を調整します。
3. すべてのページが緑色で通過（Passed）と表示されるまで、自己チェックを繰り返します。

---

ステップ5：1080p マルチコアヘッドレスレンダリング（Render）

全ページの自己チェック通過後、並列レンダリングコマンドを実行します：

# 16:9 横画面 1080p 60fps レンダリング（ハードウェアアクセラレーション対応）
node engine/tools/render.mjs --fps 60 --workers 4 --hw

• 出力先は <プロジェクトディレクトリ>/out/ です：
  • <プロジェクト名>-with-subtitles.mp4（正確なバイリンガル字幕付き）
  • <プロジェクト名>-no-subtitles.mp4（字幕なしクリーンバージョン）
  • 公開用文案と各チャプターのタイムスタンプ。

---

クイック実行モード：全自動ワンクリック動画出力（CLI Run）

ユーザーが全自動でエンドツーエンドの下書き動画を一通り生成したい場合は、プロジェクトルートディレクトリで統合された自動化CLIを直接呼び出すこともできます：

# エンドツーエンド自動実行（ドキュメント分析 -> ストーリーボード生成 -> ページ作成 -> 動画レンダリング）
node apps/cli/dist/cli.js run <資料ファイルパス> --style warm-story --duration 60

また、リアルタイムのタイムラインプレビューが必要な場合は、Webワークベンチを起動します：

node apps/cli/dist/cli.js serve

---

汎用エージェントクロスプラットフォーム呼び出しガイド（Universal Compatibility）

このスキルは特定のエージェント実行環境に依存せず、Node.js環境とファイル読み書き機能を満たしていれば使用できます：

• Claude Code：プロジェクトルートの CLAUDE.md でこのファイルを参照することでグローバルに有効化、またはカスタムコマンドとして使用できます。
• OpenHands / OpenClaw：このスキルディレクトリをプロジェクト内に配置し、AGENTS.md で宣言することで自動的にマウントされます。
• DeepSeek Harness / 自作エージェント：System Prompt または Skill Tool Context として直接大規模言語モデルに注入します。
• Cursor / Windsurf：会話中に @SKILL.md で呼び出します。