painted-animation

ペイントアニメーション

コードだけで短編アニメーションを制作する手法です。JohnHeibel/PDoomVideo（Claude Opus が描いた 156 秒のミュージックビデオ）と、その汎用キットである ClaudeAnimationBase（MIT）をもとにしており、後者はここに template/ として同梱されています。

仕組み： 各フレームは時間 t の純粋関数です。studio.html が p5.js と p5.brush、およびシーンファイルを読み込みます。各ショットは、水彩風の塗りと揺らめくインク線で 1920×1080 のフレーム全体を描きます。render.mjs はヘッドレス Chrome を動かし、確認用のコンタクトシート、または全フレームを並列でレンダリングし、ffmpeg が MP4 にエンコードします（音声があれば音声も含みます）。

ワークフロー

0. 雛形を作成する

bash ~/.claude/skills/painted-animation/scripts/new_project.sh <project-dir>        # add --keep-demo to keep the example scene hooked up

これによりテンプレートがコピーされ、デモシーンとの接続が解除され、npm install が実行され、node／ffmpeg／Chrome が確認されます。その後、何かを設計する前に <project-dir>/ANIMATION_GUIDE.md を最後まで読んでください。ここにはルール、アニメーションの原則、エンジンと Clawd API の全仕様が記載されています。Read ツールで docs/emotions.jpg と docs/views.jpg（モデルシート）を確認してください。

ミュージックビデオや約 20 秒を超える作品の場合は、references/music-video.md も読んでください。リリックビデオの場合は、まず曲ファイルと LRC を依頼し、scripts/beat_grid.py でテンポを測定してください。歌詞の行は、想像以上に速く進むことがよくあります。

1. コードを書く前にストーリーボードを作成する

プロジェクト内に STORYBOARD.md を作成します（形式はガイドを参照：ログライン、世界観とパレットの変化、モチーフ、キャラクターの感情の変化、続いて読み取り内容――つまり、視聴者が理解すべき内容を時間順に並べたリスト）。作成例：examples/xiaozhen/（31 秒のリリックビデオ：ストーリーボードとシーンコード一式）。

「そのまま進めて」と言われていない限り、ストーリーボードをユーザーに見せ、制作に入る前に意見を聞いてください。

2. ショットごとに制作する

• src/config.js で duration、bpm、offset（および audio）を設定します。
• src/scenes/ にシーン／章ごとに IIFE で囲んだファイルを 1 つ作成し、shots([[t0, fn], ...]) で終わらせます。その <script> を studio.html に追加します。
• まずキーとなるポーズを作成し、静止画で確認してから、その間の動きを追加します。

3. レンダリングして確認する — 各ショットを複数回

コードを読んでも動きは確認できません。プロジェクトディレクトリから次を実行します。

node render.mjs --sheet=0.1,0.8,1.6,2.4 --cols=4 --w=480 --out=out/check/a.jpg        # key frames
node render.mjs --strip=2.1:2.6 --out=out/check/strip.jpg                             # every frame of a moment
node render.mjs --sheet=2.3 --crop=760,420,500,400 --w=500 --out=out/check/face.jpg   # full-res detail

各画像を Read で開き、ガイドの確認リストに照らして実際にチェックしてください。出来事は明確か？ キャラクターは十分に大きいか？ 初見の視聴者にも内容が伝わるタイミングか？ 予備動作／フォロースルーはあるか、急な動きはないか？ 足や持っている小道具は接地しているか？ すべてのつなぎ目でトランジションは自然か？ 文字、3D、純粋な黒／白、濁った発光表現はないか？ 修正して、もう一度確認します。目安：ショットごとにシート 1 枚以上、キーとなる動きとトランジションごとにストリップ 1 枚、物語を担う顔ごとにクロップ 1 枚。

4. 動画をレンダリングする

node render.mjs --clip --out=out/video.mp4                                   # short videos, one worker
node render.mjs --frames --workers=4 && node render.mjs --encode --out=out/video.mp4 [--audio=assets/song.mp3]   # long ones, parallel + resumable

出力先、長さ、1 フレームあたりのミリ秒数を報告します。open out/video.mp4 を提案してください。

最も重要なルール

ガイドのルールを簡潔にまとめています。正式な情報としてはガイドを参照してください。

1. 手描きの画材。 使用するのは paint() / inkLine()（p5.brush）のみです。通常の p5 rect/ellipse/fill は使いません。平面的な 2D 表現に限ります。回転は描画したキービュー（turn()、spinView()）を経由し、3D 投影は使いません。光には glow()（加算合成）を使います。絵の具を混ぜると、黄色を青の上に重ねたとき緑になるためです。
2. テキストは使いません。 キャプション、ラベル、看板、吹き出しは使わず、映像で表現します。リアクションは描画したエモート（!、汗、ハートなど）で表します。例外は、歌詞動画のカラオケ表示と、大きな効果音を数個入れる場合です。
3. すべてのショットで何かが起こります。 出来事や、原因から反応への流れ、後の展開につながる仕込みを入れます。
4. 視聴者に考える時間を与えます。 各ショットの読み取り内容を列挙し、一度にひとつずつ見せます。動作は速く、意味は長く保ち、視線を誘導します。読み取り内容に合わせてショットの長さを決めます。ここが生成アニメーションで最も失敗しやすい部分です。
5. 生き生きとした表現にします。 静止するものはありません（feel() によるアイドル動作、カメラの移動、揺らぎを加えます）。顔の変化は差し替えではなく emotions() で表現します。キャラクターは大きく描きます（ミディアムショットでは u≈20〜28、クローズアップでは 40〜70）。すべてをビートに合わせます。
6. すべてのつなぎ目でトランジションを使います。 ストーリーに合ったものを選びます（ブラシワイプ、アイリス／形状付きアイリス、ウィップパン、マッチカット、動作に合わせたカット、カメラの動きを引き継ぐトランジション）。
7. ひとつの作品としてまとめます。 世界観を統一し、色彩の流れと感情の軸を設け、シーン同士をつなげます。冒頭と韻を踏むような結末にします。

エンジンの注意点

• t の純粋関数にします。 フレームは並列かつ順不同でレンダリングされるため、フレーム間で状態を保持しないでください。Math.random() やフレームごとの物理演算も使いません。安定した乱数には hash(i)、揺らぎには jit() を使います。
• 背景要素や小道具を個別に描く前に boilSeed(key) を呼び出します。 そうしないと、動くものの影響で、それ以降に描画するすべての要素が毎フレーム再び揺らぎます（ジッター）。
• グローバル変数に p5 の名前を使わないでください。 p5 は line、OVERLAY、text、color、scale などをグローバルとして定義しています。トップレベルで function line() を定義すると Cannot redefine property が発生し、ページの準備が完了しません（レンダラーがタイムアウトします）。ヘルパーはシーンの IIFE 内に置くか、重複しない名前を付けてください。
• 出入り口、窓、画面のレイヤー構成： 内側に見えるものを描いてから、その周囲の壁や枠を上から重ねます。開口部の外側が見えないようにしてください（電車の inDoor とドアの枠、テレビのベゼル部分が該当します）。
• 点のリストに NaN が含まれていると、Failed to construct 'OffscreenCanvas' が発生します。退化したジオメトリをチェックしてください。
• カメラのズームが ≳ 2 の場合、大きな図形の輪郭が失われます。輪郭線の太さはズームに応じて変わるため、クローズアップでは sw の値を小さくしてください。
• コストは塗りつぶしとストロークの数で決まります。1 フレームあたり ≤ 約 1.5〜2.5 秒を目安にしてください（ログに ms/frame が出力されます）。少数の大きな図形を優先します。実 GPU がないマシンでは水彩の塗りつぶしが遅くなります。fill 図形の数を減らすか、最終手段として --soft-gl を検討してください。
• macOS：レンダラーは --use-angle=metal を使用し、/Applications/Google Chrome.app を自動で見つけます。それ以外の場合は --chrome=<path> を指定してください。

カスタマイズ

• Clawd はデフォルトの主役ですが、必須ではありません。新しいキャラクター、小道具、感情も同じツール（paint、ribbon、through、glow）で描画し、すべてのショットでモデルを統一します。新しい感情は src/clawd.js の EMO に追加します。
• src/karaoke.js（テンプレート）は、core.js の window.overlayHook フックを使って、歌詞動画に単語ごとのカラオケ表示を追加します。
• LOOPS.name = t => {...}; LOOPS.name.len = 4; と設定し、node render.mjs --loop=name --png を実行すると、GIF 用のシームレスなループを作成できます（ffmpeg -i out/loop_name/f%04d.png …）。
• 推論により多くの労力をかけるほど、より華やかで詳細なシーンになる傾向があります。