session-story

セッションストーリー

エージェントはユーザーとの会話履歴を読み、ユーザーの日常のパターンを見つけ、典型的なセッションのひとつを、実際に起きた順に40〜70秒の映像にします。

• ストーリー： ユーザーが実際に話した言葉がオブジェクトとして現れ、エージェント自身の返答が戻っていきます。ウィンドウと壁時計はセッションの実際の時刻に合わせて動きます。
• 部屋： エージェントが把握しているユーザーの情報をもとに装飾します。
• 楽曲： 映像そのもののタイムラインに合わせて、エージェントが作曲します。

story.jsonを書けば、あとはエンジンが振り付けを行います。画面上に表示されるものに、創作されたものはありません。すべてのセリフは引用であり、各フレームをレンダリングする前に、ユーザーがすべてのセリフを承認します。

使用する場合／使用しない場合

• 使用する場合： ユーザーがエージェントとの共同作業を映像にするよう依頼し、そのエージェントがユーザーとの実際の履歴を持っている場合。たとえば、ローカルのトランスクリプトや、ユーザーが貼り付けたメッセージです。
• 使用しない場合： 他人の履歴、チーム共有のログ、架空の引用を使ったマーケティング、またはユーザーが確認しないものには使用しないでください。履歴がまったくない場合は、セッションのメッセージをユーザーに求めてください。引用を決して作り出さないでください。

要件と副作用（完全な一覧）

• ツール： Node 22+、Python 3.9+（標準ライブラリのみ）、PATH上のffmpeg、およびnpx --yes [email protected]にバージョンを固定したHyperFrames CLI（初回使用時にnpmレジストリからダウンロード）。
• セットアップ（手動で一度だけ）： sh scripts/setup.shは、コミット済みのロックファイルからnpm ciを実行します。p5 2.3.3（LGPL-2.1）、p5.brush 2.2.3（MIT）、@fontsource/permanent-marker 5.3.0（Apache-2.0）がインストールされます。npmから読み取り専用でダウンロードします。
• 楽曲レンダラー： macOSでは、swift（Xcode Command Line Tools）でApple内蔵のGeneral MIDIバンクを使って楽曲を再生します。それ以外の環境では、SOUNDFONTに設定したGeneral MIDIサウンドフォントを使うfluidsynthが必要です。どちらも何もダウンロードしません。
• 読み取り（ローカルのみ、ユーザーの承認後）： エージェント自身のトランスクリプト、~/.claude/projects/<project>/*.jsonl（Claude Code）、および~/.codex/sessions（Codex）。ユーザーが--all-projectsを許可しない限り、現在のプロジェクトが対象です。また、部屋の装飾にはエージェントのメモリと指示ファイルも読み取ります。何もアップロードされません。
• 書き込み： session-story-candidates.json（抽出結果）と、作成するプロジェクトフォルダ内のすべてのファイル。どちらにもユーザーの言葉が含まれるため、決してコミットしたり共有したりしないでください。
• ビルド時のネットワーク通信： ありません。以下の例にあるように、すべてのsnapshotに--describe falseを渡してください。GEMINI_API_KEYが設定されている場合、これを指定しないとsnapshotがユーザーの言葉を含むフレームをGeminiに送信します。ローカルでレンダリングします。ページはWebGLで描画します。
• 認証情報不要。有料のAPI呼び出しもありません。

ワークフロー

1. セットアップ： sh scripts/setup.sh（一度だけ）。
2. まず確認します。 セッションを見つけるため、ユーザーと一緒にローカル履歴を読むことを伝え、承諾を待ちます。
3. 収集： python3 scripts/harvest.py --project <their project folder> --out <scratch>/candidates.json を実行すると、手順が表示され、セッションが一般的なものから順に一覧表示されます。同じ --project を指定して --session <id> を指定すると、ひとつのセッションが時系列順に、現地時刻とあなたの返信とともに表示されます。references/sources.md を参照してください。
4. ひな形の作成： node scripts/new-project.mjs <dir>。ここから作成するものはすべて <dir> に保存します。
5. ストーリー： 典型的なセッションを選び、references/story.md に従って、起きた順に各ビートの実際の時刻を含めて <dir>/story.json に記述します。ユーザーの発言は一字一句そのまま抜き出し、返信にはそのセッションでのあなた自身の言葉を使います。screen にはユーザーの作業画面の様子を設定し、セッションに合ったエンディングを選びます。node scripts/schedule.mjs <dir> で確認し、編集するたびに実行してください。
6. ルーム： references/room.md に従い、ユーザーについて知っていることをもとに各スロットを埋めます。ライブラリにユーザーに合うものがない場合は、<dir>/scenes/props-custom.js にカスタム小道具を描きます。Claude でない場合は、自分自身を描いてください：references/cast.md。
7. プライバシー確認： 画面に表示されるすべての文言（フック、ネームプレート、各引用、各返信、各小道具とその理由）と、その出典をまとめた表をひとつユーザーに提示します。ユーザーの修正を反映し、明示的な承諾を得てから "approved": true に設定します。それまでは、すべてのフレームに「DRAFT」のスタンプが表示されます。
8. デザイン確認： schedule.mjs に表示される snapshot コマンドを実行します。すべてのフレームを確認し、引用が読みやすいこと、小道具が適切な場所にあること、メッセージが何にも隠れていないことを確認します。コンタクトシートをユーザーに提示します。
9. スコア： references/score.md に従い、独自のテーマ、キー、パレットを使って <dir>/score/score.py を作成します。その後、sh <dir>/score/build.sh を実行します。無音がある場合は失敗します。
10. レンダリング： <dir> から npx --yes [email protected] check を実行し、続けて npx --yes [email protected] render --fps 24 --crf 12 -o renders/session-story.mp4 を実行します。
11. レンダリング結果の確認： 長さが schedule.mjs の表示と一致している必要があります。各重要なタイミングのフレームを切り出し（ffmpeg -ss <t> -i renders/session-story.mp4 -frames:v 1 renders/check-<t>.png）、確認します。その後、音声付きで視聴できるよう、ユーザーに渡します。

例（node scripts/new-project.mjs <dir> --example を実行し、その後 schedule.mjs <dir> --example を実行）は、Claude と、動画を制作するこのスキルの作者との実際のセッションをもとにした参考作品です。フォーマットを示すものであり、あなたの作品の構成を示すものではありません。schedule.mjs は --example を指定しないと例を受け付けないため、ユーザーのストーリーの代わりには使えません。

成功の確認

• schedule.mjs が終了コード 0 で終了し、警告を出力しないこと。hyperframes check が成功すること。p5.brush は WebGL の uniform 警告をログに出力しますが、無害です。
• デザイン確認用のフレームで、すべての引用が読みやすく、ビート表と一致していること。
• score/build.sh が ok: no dead air で終わり、スコアの長さが作品の長さと一致すること。
• レンダリング結果の長さが schedule.mjs に表示された長さと一致し、音声トラックがあり、重要なタイミングのフレームがデザイン確認時のものと一致すること。
• テストする失敗ケース：返信から始まるストーリー、または文字数制限を超える引用では、schedule.mjs が終了コード 1 で終了し、該当するビート名を表示すること。

エンジンが担当するもの

動きは物理に基づいてすでに調整されています。滑走経路、折りたたみ、投げる動作、揺れ、ぶつかる動作、羽ばたきが含まれます。変更するのはストーリー、ルーム、キャスト、スコアです。バグ修正の場合を除き、scenes/director.js と scenes/compile.js の振り付けには手を加えないでください。動きのルールについてはreferences/motion.mdを参照してください。