/bustup-frame-gen

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   # neutralは avatar_bustup.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   # 35 になること

静的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"   # 200

# agent-browserでチャットページを開き、ポップアップを直接呼ぶ
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状態が元表情の見た目になっているか目視必須 |