表情差分PNG + 前髪 + 後ろ髪で、リッチに動くPNGTuberを作る。

Expression PNGs + front hair + back hair = a richer moving PNGTuber avatar.

ぷるぷるPNGTuberは、通常のPNGTuber向け表情差分PNGに「前髪」と「後ろ髪」の2枚を追加するだけで、髪揺れ・顔向き・口パク・まばたきに対応したリッチなPNGTuberアバターを作るためのローカルWebアプリです。

このリポジトリは、Codex / Claude Code などのAIコーディングエージェントに初期セットアップを依頼し、その後ユーザーがブラウザ上で微調整する ワークフローを前提にしています。

PuruPuru PNGTuber is a local browser app for creating expressive PNGTuber avatars. Add only front-hair and back-hair layers to ordinary PNGTuber expression images, ask Codex, Claude Code, or another coding agent to set up the initial character, then fine-tune it visually in the browser.

1. PNG素材を用意する
   • 通常のPNGTuber向け表情差分
   • front-hair.png 相当の前髪
   • back-hair.png 相当の後ろ髪
   • 任意でボディ、ヘアアクセサリ、リボンなどのPNGアイテム
2. Codex / Claude Code などに初期セットアップを依頼する
   • ファイル名整理
   • assets/ 配下への配置
   • キャラ設定・初期位置・髪束ライン・アイテム設定の作成
3. ローカルで起動して確認する
4. ブラウザ上で表情、顔向き、髪揺れ、アイテム位置を微調整する
5. .purupuru ファイルとして保存・バックアップする

English summary:

1. Prepare aligned transparent PNG assets.
2. Ask Codex, Claude Code, or another coding agent to create the initial character setup.
3. Run the app locally.
4. Fine-tune the avatar in the browser.
5. Export a .purupuru package for backup or transfer.

必須PNG:

back-hair.png                 後ろ髪 / back hair
front-hair.png                前髪 / front hair
eyes-open-mouth-closed.png    目開け・口とじ
eyes-open-mouth-half.png      目開け・口中間
eyes-open-mouth-open.png      目開け・口開け
eyes-closed-mouth-closed.png  目閉じ・口とじ
eyes-closed-mouth-half.png    目閉じ・口中間
eyes-closed-mouth-open.png    目閉じ・口開け

任意PNG:

body.png      ボディ
hairpin.png   ヘアアクセサリ
ribbon.png    リボン
その他アイテムPNG

重要:

• すべて透過PNGにしてください。
• 同じキャラ内のPNGは、同じキャンバスサイズ・同じ位置合わせにしてください。
• 顔、目、口、前髪、後ろ髪、ボディ、アクセサリの座標がズレていると、まばたき・口パク・顔向き・髪揺れ時にズレが目立ちます。
• 前髪と後ろ髪は、顔画像と同じキャンバス基準で書き出してください。

詳しい使い方は 使い方 / Usage を参照してください。

キャラ追加時は、次のような依頼文を使う想定です。

このフォルダ内のPNG素材を使って、PuruPuru PNGTuber用の新キャラとして追加してください。

条件:
- 素材は assets/ 以下にASCII名でコピーしてください。
- 表情差分、前髪、後ろ髪を対応するファイル名にリネームしてください。
- 追加アイテムがある場合は items/ 以下に保存してください。
- default-settings.json を作成し、顔中心、目、鼻、口、顎、首支点、髪束ラインを初期設定してください。
- ボディやアクセサリがある場合は、初期アイテムとして登録してください。
- キャラ固有の髪/顔補正が必要な場合は、既存キャラに影響しないようキャラ固有条件で分岐してください。
- 最後に node --check app.js と関連テストを実行してください。

詳しい依頼手順は 使い方 / Usage を参照してください。

• PNGだけで動くPNGTuberアバター
• 表情差分 + 前髪 + 後ろ髪によるリッチな見た目
• マイク音量またはデモによる口パク
• 自動まばたき
• マウス追従とカメラ顔トラッキング
• 前髪・後ろ髪のぷるぷる揺れ
• 顔向き、ハイライト、涙レンズ、影の調整
• PNGアイテムの追加、前後関係、追従、ロック
• OBS向け透過表示
• .purupuru avatar package import/export
• Advanced warp editor for face and hair adjustment

• Python 3.10 or later
• Google Chrome or Chromium recommended
• Camera permission for face tracking
• Microphone permission for microphone lip sync
• Internet access for MediaPipe face tracking assets unless they are vendored in a future release

.\run_local_server.bat

or:

python scripts\run_local_server.py

chmod +x ./run_local_server.sh
./run_local_server.sh

or:

python3 scripts/run_local_server.py

The app opens at a local URL such as:

http://127.0.0.1:8223/

Use the local server instead of opening index.html directly with file://. Browser permissions, CSP, and OBS helper APIs behave more consistently through the local server.

Bundled demo avatars are stored in:

assets/demo-avatar/
assets/demo-avatar02/
assets/demo-avatar03/

The bundled demo images are provided so the app can be tested immediately after cloning. Avatar PNGs can use different canvas sizes per character, as long as every required PNG in the same character uses the same size and alignment.

Bundled demo images, favicon, screenshots, thumbnails, and other visual assets are licensed separately from the software code. See ASSET_LICENSE.md.

詳しい使い方、素材準備、Codex / Claude Code への依頼例、OBS設定、トラブルシュートは1本にまとめています。

• 使い方 / Usage

node --check app.js
node tests/js_runtime_checks.mjs
python -m py_compile scripts/run_local_server.py
python -m unittest tests.test_project_static

PuruPuru PNGTuber runs locally in your browser. Camera and microphone data are processed locally for the app's features. Face tracking loads MediaPipe assets from external CDNs at runtime unless those assets are vendored in a future release.

Camera-based face tracking is powered by Google MediaPipe Tasks Vision, licensed under Apache License 2.0. See THIRD_PARTY_NOTICES.md.

Contributions are welcome. Please read CONTRIBUTING.md, SECURITY.md, and SUPPORT.md before opening issues or pull requests.

Software code and documentation text are licensed under the Apache License 2.0.

Bundled demo avatar images, favicon, screenshots, thumbnails, and other visual assets are not covered by the software license. They are governed separately by ASSET_LICENSE.md.

Third-party notices are listed in THIRD_PARTY_NOTICES.md.