PNGTuber以上、Live2D未満 — 動画ベースのリアルタイム口パク（リップシンク）システム

ループ動画を使うことで、従来のPNGTuberでは表現できなかった髪の毛の揺れや衣装のなびきをリッチに表現できます。Live2Dのような専門知識は不要で、MP4動画と口スプライトさえあれば始められます。

• 🎤 リアルタイム口パク: マイク入力に合わせてキャラクターの口が動く
• 🤖 AITuber対応: 仮想オーディオデバイスを使えばAITuberのアバターとしても利用可能
• 🎭 感情自動判定: 音声から感情（喜び・怒り・悲しみ等）を推定し、表情を自動切替
• 💨 髪・揺れ物の動き: ループ動画なので髪や衣装が自然に揺れる
• 🖼️ 高精度口消し: 元動画から口を自然に消去し、口スプライトを合成
• 🎯 簡単キャリブレーション: マウス操作で口の位置・サイズ・回転を調整
• 🖥️ GUIツール: ワンクリックで解析から実行まで

サンプルアセットを使って、すぐに試すことができます。

• Python 3.10: ダウンロード（インストール時に「Add Python to PATH」にチェック）
• uv: Pythonパッケージマネージャー（インストール方法）

  # Windows (PowerShell)
  powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# プロジェクトディレクトリで実行
uv sync

これだけで仮想環境の作成と全ての依存パッケージのインストールが完了します。

uv run python mouth_track_gui.py

1. 動画を選択: assets/assets03/loop.mp4 を選択
2. mouthフォルダを選択: assets/assets03/mouth を選択
3. ① 解析→キャリブ: クリックして口の位置を調整 → Space で確定
4. ② 口消し動画生成: クリックして待つ
5. ③ ライブ実行: マイクに向かって話すと口が動く！

💡 各アセットフォルダには パラメーター参考例XX.png が入っています。設定の参考にしてください。

• ループ再生できる短い動画（数秒程度）
• 顔が隠れていないもの（顔が隠れているとリップシンクが正しく動作しません）
• 髪の揺れや衣装のなびきがあるとリッチな表現に

キャラクターに合った口の画像を5種類用意します：

• 画像形式: PNG（透過対応・RGBA）
• 推奨サイズ: 幅128px程度

感情表現を使いたい場合は、感情ごとに口スプライトを用意します（Default / Happy / Angry / Sad / Excited）。

感情別スプライトがなくても1種類の口スプライトだけで動作します。 表現の幅を広げたい場合に追加してください。

• GPU（CUDA）使用時: 顔トラッキングが高速（約30FPS）
• CPUのみ: トラッキングは低速（約2-5FPS）だが動作可能。リアルタイム再生自体はCPUで十分

1. Python 3.10.x をダウンロード
2. インストール時に「Add Python to PATH」にチェック

# PowerShellで実行
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

詳細は uv公式ドキュメント を参照。

# プロジェクトディレクトリに移動
cd MotionPNGTuber

# 仮想環境の作成と依存パッケージのインストール（1コマンドで完了）
uv sync

uv sync を実行すると：

• .venv ディレクトリに仮想環境が自動作成される
• pyproject.toml と uv.lock に基づいて全ての依存パッケージがインストールされる
• PyTorch（CUDA 11.7対応）、mmcv-full、anime-face-detector など全て自動でインストールされる

uv run python -c "import cv2; import numpy; import sounddevice; from anime_face_detector import create_detector; print('OK')"

MotionPNGTuber/
├── mouth_track_gui.py              # メインGUI
├── mouth_erase_tuner_gui.py        # 口消しチューナーGUI（おまけツール）
├── mouth_sprite_extractor_gui.py   # 口スプライト抽出GUI（おまけツール）
├── mouth_sprite_extractor.py       # 口スプライト抽出コアモジュール
├── loop_lipsync_runtime_patched_emotion_auto.py  # リアルタイム実行（感情対応）
├── face_track_anime_detector.py    # 顔トラッキング
├── calibrate_mouth_track.py        # キャリブレーション
├── erase_mouth_offline.py          # 口消し処理
├── auto_mouth_track_v2.py          # 自動トラッキング
├── auto_erase_mouth.py             # 自動口消し
├── preview_mouth_track.py          # トラッキングプレビュー
├── realtime_emotion_audio.py       # 感情解析
├── pyproject.toml                  # uv依存関係定義
├── uv.lock                         # uvロックファイル
├── assets/                         # 動画アセット（サンプル）
│   ├── assets01/
│   │   ├── loop.mp4
│   │   └── パラメーター参考例01.png
│   ├── assets02/
│   │   ├── loop.mp4
│   │   └── パラメーター参考例02.png
│   └── assets03/
│       ├── loop.mp4
│       ├── mouth/                  # 個別の口スプライト
│       └── パラメーター参考例03.png
└── mouth_dir/                      # 感情別口スプライト
    └── Tomari/
        ├── Default/
        ├── Happy/
        ├── Angry/
        ├── Sad/
        └── Excited/

感情表現を使用するには、以下の構造で口スプライトを配置します：

mouth_dir/
└── Tomari/              # キャラクター名（任意）
    ├── Default/         # デフォルト表情
    │   ├── open.png     # 口を開けた状態
    │   ├── closed.png   # 口を閉じた状態
    │   ├── half.png     # 半開き
    │   ├── e.png        # 「え」の口（open/closed/halfとは異なる形状なら何でも可）
    │   └── u.png        # 「う」の口（open/closed/halfとは異なる形状なら何でも可）
    ├── Happy/           # 嬉しい
    │   ├── open.png
    │   ├── closed.png
    │   ├── half.png
    │   ├── e.png
    │   └── u.png
    ├── Angry/           # 怒り
    ├── Sad/             # 悲しみ
    └── Excited/         # 興奮

重要事項:

• 各フォルダに必ず open.png, closed.png, half.png, e.png, u.png の5ファイルを配置
• e.png と u.png は、open.png / closed.png / half.png とは異なる形状であれば何でも構いません（「え」「う」の口に限らず、任意の口の形状でOK）
• 画像形式: PNG（透過対応・RGBA）
• 推奨サイズ: 幅128px程度（アスペクト比 約1.5）
• 感情フォルダ名: Default, Happy, Angry, Sad, Excited（大文字小文字どちらでも可）

uv run python mouth_track_gui.py

1. 動画を選択: 「選択…」ボタンで元動画（loop.mp4など）を選ぶ
2. mouthフォルダを選択: 口スプライトがあるフォルダを選ぶ
3. キャラクターを選択: 複数キャラがある場合はドロップダウンで選択
4. ① 解析→キャリブ: クリックすると顔トラッキング→キャリブレーション画面へ
5. ② 口消し動画生成: 口を消した動画を生成
6. ③ ライブ実行: マイク入力でリアルタイム口パク開始

「① 解析→キャリブ」実行後、キャリブレーション画面が表示されます。

「口消し範囲プレビュー」ボタンで、口消しの範囲を事前確認できます。

• 赤色: 実際に消去される領域（中心マスク）
• 黄色: 陰影推定に使う外周領域（ring）
• 緑枠: トラッキングされた口の四角形

uv run python mouth_erase_tuner_gui.py

画像の口部分を削除できる単体ツールです。MotionPNGTuber本体とは独立して使用できます。

uv run python mouth_sprite_extractor_gui.py

動画から口スプライト（5種類のPNG）を自動抽出するツールです。口スプライトを自分で描く必要がなくなります。

1. 動画を選択: 元動画（loop.mp4など）を選ぶ
2. 解析: 10枚の候補フレームが表示される（バリエーション別）
3. 割り当て: 各候補の下のテキストボックスに1-5を入力
   • 1=open, 2=closed, 3=half, 4=e, 5=u
4. 調整: 切り取り範囲とフェザー幅を設定
5. プレビュー更新: 設定を確認
6. 出力: 動画と同じフォルダに mouth/ が作成される

10枚の候補は以下からバリエーション豊かに選ばれます：

• 開いた口（高さ最大）: 2枚
• 閉じた口（高さ最小）: 2枚
• 半開き（高さ中央）: 2枚
• 横長の口（e候補）: 2枚
• すぼめた口（u候補）: 2枚

uv run python face_track_anime_detector.py \
    --video assets/assets01/loop.mp4 \
    --out assets/assets01/mouth_track.npz \
    --device auto \
    --pad 2.1

uv run python calibrate_mouth_track.py \
    --video assets/assets01/loop.mp4 \
    --track assets/assets01/mouth_track.npz \
    --sprite mouth_dir/Tomari/Default/open.png \
    --out assets/assets01/mouth_track_calibrated.npz

uv run python auto_erase_mouth.py \
    --video assets/assets01/loop.mp4 \
    --track assets/assets01/mouth_track_calibrated.npz \
    --out assets/assets01/loop_mouthless.mp4 \
    --coverage 0.6

uv run python loop_lipsync_runtime_patched_emotion_auto.py \
    --loop-video assets/assets01/loop_mouthless.mp4 \
    --mouth-dir mouth_dir/Tomari \
    --track assets/assets01/mouth_track_calibrated.npz \
    --emotion-auto \
    --emotion-preset snappy

# GPU使用（自動選択）
--device auto

# 特定のGPU
--device cuda:0

# CPUのみ
--device cpu

1. Python 3.10 がインストールされているか確認
2. uv が正しくインストールされているか確認（uv --version）
3. キャッシュをクリアして再試行：

   uv cache clean
   uv sync

uv run python -c "import torch; print(torch.cuda.is_available())"

False の場合：

• NVIDIA ドライバが最新か確認
• CUDA Toolkit 11.7 がインストールされているか確認

オーディオデバイスが認識されない場合、Windowsのサウンド設定でマイクが有効か確認。

1. 「キャリブのみ（やり直し）」でキャリブレーションをやり直す
2. pad の値を調整（大きくすると追跡領域が広がる）

「影なじませ」をOFFにする（GUIのチェックボックス）

音声から以下の5つの感情を自動判定します：

MIT License

• anime-face-detector
• MMDetection
• MMPose