makerjackie/short-film

プログラム短片（short-film）

一つのテーマを短片に変換します：約30秒（15～90秒可）、縦型1080×1920、24fps。手描きインク風の紙プレート（paper plate）レンズと、ダークブルーの設計図プレート（blueprint plate）レンズを交互に編集。各イベントはビートグリッド（bpm → 拍 → フレーム）上に配置されます。すべてのピクセルとオーディオサンプルは純粋なブラウザJavaScriptで計算されます。成果物は dist/<slug>.html（自己完結型プレイヤー）、exports/<slug>.mp4（およびそのスマホ版、プレビュー版のトランスコード）、さらに公開パッケージ（TikTok用カバー画像（HTMLスクリーンショット）、推奨タイトルと説明文）です。

このスキルは、検証済みのパイプラインをカプセル化しています。以下の3つの要素を同梱しています。

• foundation/ — エンジンとツール。新しいプロジェクトにコピーされます：src/core.js、src/lib.js、src/player.js、src/music.js（エンジン＋サンプル楽曲）、および tools/（ビルド、チェック、スクリーンショット、レンダリング、スタブ生成、音声分析、公開パッケージ、テストフィクスチャ）。すべては src/timeline.js によって駆動されるため、各作品でツールコードを変更する必要はありません。
• templates/ — 各作品の開始時に使用する4つの計画ドキュメント。
• reference/ — 必要に応じて参照：レンズタイプ、シーン解剖、音楽、プラットフォームプリセット。まずは3枚の参照図を見てください。

最初に reference/ をご覧ください：contact-sheet.jpg はサンプル作品（examples/llm-evolution、カスタム「地図帳ATLAS」スタイル）の全編コンタクトシートです。そのディテール密度と完成度が基準線です。paper-frame.jpg と blueprint-frame.jpg はデフォルト既存スタイルの2つのプレートの各1フレームで、tools/fixtures によってレンダリングされます。デフォルトスタイルを採用する作品はこれらをビジュアルターゲットとします。

完全なサンプルは examples/llm-evolution/ にあります：ニューロンから大規模AIモデルまでを描いた24レンズの作品で、計画ドキュメント、ソースコード、dist/、公開パッケージを含みます。これはカスタムスタイルの成果物（参照分析によりデフォルトの紙×設計図スタイルから逸脱）であり、本スキルの全能力を示しています。テンプレートを埋めた完成形に迷ったときは、そちらで対応物を参照してください。

ゲート（The gate）

node tools/check.cjs がゲートです：6つのチェック（メディアスキャン、決定性、ソーススキャン、タイムライン、描画、フレーム時間）を実行し、終了コード0で合格となります。スタブフェーズ以降、ゲートが赤の間はどのステップも完了とは見なされません。実際のシーンでは1分未満で完了しますので、必ず実行してください。

パイプライン

0. ブリーフ（Brief）

質問は一回だけ：テーマは何か、その作品に必ず含めるべき内容、長さ（デフォルト30秒）、公開プラットフォーム（アスペクト比とセーフゾーンを決定、reference/platform-presets.md 参照）。残りは自分で考案し、何を考案したかを説明します。

完了基準：テーマがユーザーが確認した言葉として書き出され、長さとプラットフォームが確定していること。

1. セットアップ（Setup）

作品のスラッグ名でプロジェクトフォルダを作成し、foundation/ をコピーします。tools/ 内で npm install（Playwright；ブラウザがない場合は npx playwright install chromium を追加）を実行し、ffmpeg が PATH にあるか、FFMPEG 環境変数にバイナリパスが設定されていることを確認します。テンプレートを docs/ にコピーし、テーマを docs/CONTRACT.md の Goal に書き込みます。

完了基準：node tools/smoke.cjs が成功、node tools/check.cjs --fixtures がグリーン、node tools/render.cjs --fixtures --scale 0.5 が音声付きの exports/fixtures.mp4 を生成すること。この fixtures ミニ作品は、計画に労力を費やす前にツールチェーンが機能することを証明します。

2. リサーチ（Research）

テーマのストーリーの各段階をリストアップし、未解決の質問ごとにWeb検索を1回行い、2～4つの信頼できる全文ソースを .tmp/research/ に保存します。リサーチは最終的に2つの下流の場所にのみ反映されます：アートバイブルのテーマリファレンス、および各レンズの Subject セクション。

完了基準：ストーリーの各段階が、保存されたソースにトレース可能であること。

3. アートバイブル（Art bible）

テンプレートに従って docs/art-bible.md を記入します。セクション1～9は既存スタイルで、固定されています。セクション2.2（テーマパレット、各色は名前付きhexで、src/lib.js 内の注釈ブロックにミラーリング）、2.3のアイデンティティ色調、セクション10（テーマリファレンス）は各作品ごとに書き換えます。セクション10は「避けるべき間違い」で終わり、各間違いには正しい描き方が添えられます。

ユーザーが既存スタイルと異なる外観を希望する場合は、まず templates/reference-analysis.md の方法で参照分析を行い、それに応じてセクション1～9を更新します。

完了基準：ストーリーボードで描画される各要素に描画ルールとパレット名があること。src/lib.js とセクション2.2が一致していること。間違いリストが存在すること。node tools/snap.cjs --fixtures --shot palette --samples 5 --sheet を確認済みであること。

4. ストーリーボード（Storyboard）

reference/shot-types.md を読み、テンプレートに従って docs/storyboard.md を記入します：ログライン、数字（最初にbpmを選び、拍 = 60/bpm 秒、長さは整数小節に収まる）、サマリーテーブル、小節にマッピングされた幕、各マッチカットをまたいで生き残る形状の共有ジオメトリテーブル、そして各レンズのエントリ（1～3秒、境界はビートグリッド上、2つのプレートが交互）——8つのサブセクションすべてを含み、Sound ヒントはグリッド上のタイムスタンプ付き。

完了基準：各レンズが正確に [0, duration] を隙間なく埋めること。各レンズに8つのサブセクションすべてがあること。各マッチカット形状に共有ジオメトリテーブルがあること。ドキュメントが批評家の目による自己チェックに耐えられること（本文の数字と各テーブルが一致、必須コンテンツはすべてセーフゾーン内、算術コンテンツも含む）。ストーリーボードの誤りはすべてのシーンに増幅されるため、ここでの修正が最もコストが低いです。

5. タイムライン（Timeline）

ストーリーボードに従って src/timeline.js を記述します（形状はストーリーボードテンプレート参照）：タイトル、bpm、長さ、shots 配列（id、file、start、end、mode、title、transitionIn、brief）、および各Soundサブセクションから収集したフラットなcues。スタブフェーズはこのステップのテストです——タイムライン形式の誤りは大声で失敗します。

6. スタブフェーズ（Stub pass）

node tools/stubgen.cjs が各レンズのプレースホルダシーンを生成し、ゲートを実行します。その後 node tools/render.cjs --scale 0.5 --out exports/draft-stubs.mp4 を実行し、最初から最後までドラフトを視聴します。これはトレーサー弾です：実際のシーンが描画される前に、タイムライン、シーン、ゲート、レンダリング、オーディオがすべて機能することを証明します。

完了基準：ゲートがグリーン、ドラフトMP4が各レンズを順番に表示し、各トランジションがグリッド上にあること。

7. シーン（Scenes）

各シーンファイルは1エージェント——ファイル所有権は法律です（docs/CONTRACT.md）。各シーンエージェントは reference/scene-anatomy.md、そのストーリーボードエントリ、アートバイブル、共有ジオメトリを読み、src/scenes/NN-<id>.js を書き、コンタクトシートを取得し（node tools/snap.cjs --shot <id> --samples 6 --sheet）、各フレームを確認し、ブリーフに合うまで反復します。snap --only は兄弟ファイルが半分しか書かれていないときに単一レンズをレンダリングできるため、シーンエージェントは自由に並行作業できます。

レンズは描画モジュールを共有することもできます（集中型レイアウト、docs/CONTRACT.md「シーンコードの2つのレイアウト」参照）——その場合、各 src/scenes/NN-*.js は数行の登録ラッパーであり、描画は FILM.art に集中します。サンプル examples/llm-evolution はこれを使用しています。レンズが同じジオメトリを共有し、パラメータのみが異なる場合、こちらの方が効率的です。

完了基準：各レンズのコンタクトシートが目視でチェックされ、ブリーフに適合していると判断され、ゲートがグリーンであること。

8. 音楽（Music）

reference/music.md に従って src/music.js を記述します：エンジンはそのままに、CH コード表、MIX.ride オートメーション、score() 関数全体を置き換え、トランジションにアクセントが来るようにし、FILM.TIMELINE.cues の正確な時間に各cueを実装します。

完了基準：node tools/audio/render-audio.cjs 実行後、node tools/audio/analyze.cjs .tmp/audio/score.wav --cues で開始点とヒントが10ms以内に一致すること、node tools/audio/peaks.cjs .tmp/audio/score.wav でヘッドルームがリミッター上限を下回っていること、ゲートがグリーンであること。

9. 批評波（Critic waves）

まず全編を1枚のシートに：node tools/snap.cjs --samples 24 --sheet --scale 0.25。このサイズで読めないレンズはP1——詳細ではなく構図を修正します。

次に、レンダリングされたフレームに基づいて各レンズをレビューします。コンタクトシートを再取得し、批評サブエージェントが構図、ストーリーボードへの忠実度、動き、密度を採点します。批評家は測定を行います：ピクセルレベルの比率、キージオメトリ（バンドスコア、三分割法、セーフゾーン演算、共有ジオメトリ位置）を目だけではなく評価し、各マッチカットの両側を切り出して比較します。

波単位で修正します——P1優先、各修正はエビデンスフレームを引用、ファイル所有権を維持（該当エージェントが復旧）、修正ごとに再スクリーンショット。ディレクターが新しいフレームで各P1修正をサンプリングチェックします。2つの異なる順序で同じフレームをスクリーンショットし、ファイルハッシュを比較して決定性をチェックします。

完了基準：各P1およびP2修正が新しいフレームで検証され、ゲートがグリーンであること。

10. デリバー（Deliver）

node tools/render.cjs でマスター（crf 16）を書き出します。その後トランスコード：

ffmpeg -i exports/<slug>.mp4 -vf scale=720:1280 -c:v libx264 -crf 23 -preset medium -c:a aac -b:a 128k exports/<slug>-phone.mp4
ffmpeg -i exports/<slug>.mp4 -c:v libx264 -crf 23 -preset medium -c:a copy exports/<slug>-preview.mp4

node tools/build.cjs で dist/<slug>.html を書き出します。その後、音声付きでマスターを最初から最後まで視聴し、HTMLプレイヤーを一度開きます（クリックまたはスペースで再生、矢印キーでフレームステップ、?shot=<id> で単一レンズループ）。

exports/<slug>-shots.md を書きます：各レンズ1行、その内容を説明します。

完了基準：マスター、スマホ版トランスコード、HTMLファイル、exports/<slug>-shots.md がすべて存在し、ゲートがグリーン、最終視聴で修正点が見つからないこと。

11. 公開パッケージ（Publish pack）

tools/publish.cjs を使用して、公開に適したカバー画像とコピー用の足場を生成します：

node tools/publish.cjs                          # デフォルトで最初のレンズのフックフレームをカバーに使用
node tools/publish.cjs --at 2.5 --title "一つのニューロンから、言語機械へ" --platform tiktok

これは2つのことを行います：

1. カバー画像（HTMLスクリーンショット、デフォルト1080×1920）：--at 時点のフレームをメインビジュアルとしてレンダリング、タイトル/サブタイトル/ウォーターマークを重ね、exports/<slug>-cover.png として出力。カバーページではシステムフォントと画像の使用が許可されます（配信HTMLには含まれず、「メディアなし」ルールに違反しません）。
2. コピー用足場 exports/<slug>-publish.md：タイトル候補、説明文、ハッシュタグ、レンズリスト、長さ/アスペクト比/プラットフォームなど。タイトルと説明文は出発点であり、reference/publish.md のルールに従って最終推奨にブラッシュアップします。

完了基準：exports/<slug>-cover.png が生成され目視確認済み（タイトルがセーフゾーン内、可読、フックあり）。exports/<slug>-publish.md のタイトルと説明文が最終推奨にブラッシュアップ済み。プラットフォームとアスペクト比がステップ0のブリーフと一致すること。