| name | bustup-frame-gen |
| description | 音声ポップアップの疑似Live2Dアニメーション用フレームセット（表情×5フレーム）を、 grokのimage_editで既存bustupから生成しPIL合成で揃える手順。Animaのボイスチャットで 口パク・瞬きを動かしたい、新しいanimaにアニメーションフレームを追加したい、 「bustupをLive2D風に動かして」「口パクフレームを作って」と言われたときに使う。 リギング・Live2D SDKは使わない（AIアバター用途は別途ライセンス契約対象になり得るため不採用）。 |
Bustupアニメーションフレーム生成 — 疑似Live2D方式
音声ポップアップ（animaタブ長押し）のbustupを、静止画フレーム切替+CSS/JSで動かすための
アセット生成手順。2026-08-20にmeiで確立。
方式: リギングなし。口3段階×瞬きのフレーム切替 + CSS呼吸/揺れ + lerp視線追従 +
TTS音量(RMS)口パク。AI VTuberのデファクト（感情タグ→プリセット切替、Neuro-samaも同方式）。
成果物の契約（フロントエンドが期待する形）
配置先 <data_dir>/animas/<name>/assets/（通常 ~/.animaworks/animas/<name>/assets/）:
avatar_bustup_<expr>_frame_base.png # 目開き+口閉じ（その表情の口）
avatar_bustup_<expr>_frame_blink.png # 目閉じ
avatar_bustup_<expr>_frame_half.png # 口半開き
avatar_bustup_<expr>_frame_open.png # 口開き
avatar_bustup_<expr>_frame_blinkhalf.png # 目閉じ+口半開き
<expr> は voice-popup.js の VALID_EXPRESSIONS と同じ7種:
neutral / smile / laugh / troubled / surprised / thinking / embarrassed。
neutralも明示的に _neutral_ を含む（既存 avatar_bustup.png の命名特例は適用しない）- 5枚×7表情=35枚。フロントは
_frame_base.png へのHEAD 1発で存在判定するので
表情単位で5枚揃えて置く（中途半端に置かない）
- フレームが無いanima/表情は自動で静的bustupへフォールバック（mei以外は当面フレーム無しでよい）
- 描画側の実装は
server/static/pages/chat/bustup-animator.js（変更不要）。
仕様の正本は docs/issues/20260820_mei-pseudo-live2d-popup.md
手順
1. 作業ディレクトリ準備
scratchpadに表情ごとのサブディレクトリを作り、既存bustupを src.png としてコピーする。
W=<scratchpad>/bustup-frames; A=~/.animaworks/animas/<name>/assets
for e in neutral smile laugh troubled surprised thinking embarrassed; do
mkdir -p $W/$e
cp $A/avatar_bustup_${e}.png $W/$e/src.png
done
2. grok image_editで差分3枚を生成（表情ごと）
scripts/gen_one.sh <expr_dir> を直列実行する（grokのheadlessに image_edit ツールがある。
プロンプト全文はスクリプト内。要点: src.png と完全同一を保ち、指定の1変化だけ加える）。
for e in neutral smile laugh troubled surprised thinking embarrassed; do
bash .claude/skills/bustup-frame-gen/scripts/gen_one.sh $W/$e
done
各dirに eyes_closed.png / mouth_half.png / mouth_open.png ができる。
1表情10分程度（timeout 600）。
3. PIL合成で残り2枚を作る — ここが最大の罠
grok image_editは元画像と解像度・フレーミングが変わる（実測: 1024×1365→864×1152）。
ただし同一呼び出しで生成された差分3枚同士はピクセル一致する。したがって:
src.png（元bustup）とはいかなる合成もしない。frame_base すら src からは作れない- base（目開き+口閉じ）と blinkhalf（目閉じ+口半開き）は差分同士の口領域pasteで合成する
python3 .claude/skills/bustup-frame-gen/scripts/compose_frames.py $W/neutral $W/smile ...
口領域は mouth_half と eyes_closed の差分の行分布から自動検出（最下クラスタ=口、
マージン18px）。スクリプトがサイズ一致assertと検出失敗assertを持つ。
smile/laughの注意: 元絵が笑い目+開口の表情では「rest状態=元表情の見た目」になるよう
合成結果を目視確認する（口閉じフレームが不自然に真顔化していないか）。
4. 目視検証
配置前に必ず各表情5枚を実際に開いて確認する:
- 差分が目・口以外に漏れていないか（髪・服・背景が変わっていたらその表情を再生成）
- 5枚の間でフレーミングが揃っているか（1枚だけズレていると切替時にガタつく）
5. 配置
A=~/.animaworks/animas/<name>/assets
for e in neutral smile laugh troubled surprised thinking embarrassed; do
cp $W/$e/frame_base.png $A/avatar_bustup_${e}_frame_base.png
cp $W/$e/eyes_closed.png $A/avatar_bustup_${e}_frame_blink.png
cp $W/$e/mouth_half.png $A/avatar_bustup_${e}_frame_half.png
cp $W/$e/mouth_open.png $A/avatar_bustup_${e}_frame_open.png
cp $W/$e/frame_blinkhalf.png $A/avatar_bustup_${e}_frame_blinkhalf.png
done
ls $A/*_frame_*.png | wc -l
静的JSもアセットもサーバー再起動不要で即反映される。
6. 実機E2E確認
nginx経由は認証で503になるので localhost:18500 直結 + agent-browser を使う:
curl -s "http://127.0.0.1:18500/api/animas/<name>/assets/avatar_bustup_neutral_frame_base.png" \
-o /dev/null -w "%{http_code}\n"
agent-browser eval "openVoicePopup('<name>')"
agent-browser eval "document.querySelector('.bustup-animator-set.active') ? 'active-set' : 'no-active'"
確認項目: 常時の呼吸・揺れ・ランダム瞬き / TTS再生中の音量連動口パク /
感情タグでの表情クロスフェード / フレーム無しanimaが静的bustupのままであること。
罠まとめ
| 罠 | 対処 |
|---|
| image_editの解像度・フレーミング変化 | 差分同士だけで合成。src.pngとは絶対に混ぜない |
| Live2D Cubism SDK | AIアバター用途は規模問わず別途ライセンス契約対象になり得る。使わない |
| nginx経由のE2Eが503 | localhost:18500直結 + agent-browser eval |
| 表情フレームの部分配置 | _frame_base.png の存在=5枚全部あるとみなされる。5枚単位で置く |
| 笑い目表情のbase合成 | rest状態が元表情の見た目になっているか目視必須 |
