Turn one illustration into an animated 2D mesh avatar with a coding agent and a local editor
Mesh Avatar Studio
1枚のイラストから、まばたき・口パク・首振り・呼吸・髪の揺れをする 2D メッシュアバターを作るツールです。アバターの作成はコーディングエージェントが行い、細かい調整はプレビューを見ながらローカルのエディタで行います。
実際に動く様子は紹介ページで見られます。 インストールせずに自分の顔と声で動かすなら、Chrome か Edge で Player を開いてください。
![]()
サンプルで試す
Node.js 22.17 以上と Git が必要です。
npx create-mesh-avatar-studio
cd mesh-avatar-studio
npm run dev
最初のコマンドで、リポジトリのダウンロード、パッケージのインストール、必要なツールの確認までを行います。自分でリポジトリを取得した場合は、npm install のあとに npm run doctor を実行すると同じ確認ができます。エディタと配信画面に必要なのは Node.js だけです。uv と Python はレイヤーの作り直しに、Playwright の Chromium はエージェントがアバターを作るときの動きの確認に使います。足りないものは警告で知らせます。
ターミナルに表示された URL(例: http://127.0.0.1:5173/)をブラウザで開くと、同梱のサンプル(チャイナドレスのミコ)が表示されます。左の一覧からパーツを選び、画像の上の点をドラッグすると、右のプレビューに結果が反映されます。サンプルは読み取り専用なので、編集すると「コピーして編集を続ける」ボタンが出ます。押すと自分用のコピーで作業を続けられます。
Windows で使うとき
リポジトリの取得には、できれば git clone を使ってください。ZIP を使う場合は、展開する前にエクスプローラーで ZIP のプロパティを開き、ブロック解除の項目があれば解除してください。
エージェントに作業を頼む前に、自分の Windows アカウントで projects/ フォルダを作っておいてください(npx create-mesh-avatar-studio を使った場合は作成済みです)。別のアカウントやサンドボックス内で動くエージェントが作ったフォルダは、アクセス権限の違いでエディタから読めないことがあります。読めない場合は、フォルダの「プロパティ → セキュリティ」で、自分のアカウントにプロジェクト全体へのアクセス権限を付け直してください。中のファイルやサブフォルダにも権限が引き継がれるように設定します。
使い方の流れ
自分のイラストからアバターを作る手順は4つです。1と4はこのリポジトリで動かすコーディングエージェント(Claude Code または Codex)が行い、2と3はエディタで行います。
1. エージェントにアバターを作ってもらう
このリポジトリのフォルダで Claude Code か Codex を開き、イラストを渡して次のように頼みます。
docs/agent-guide.ja.md に沿って、この画像からアバターを作って:
/path/to/your-image.png
エージェントはエージェント向けの手順書に従って作業します。座標を正確に読めるかを確認したうえで、目盛り付きの拡大図を見ながらリグを配置し、画像をレイヤーに切り出して、決まったポーズの画像で仕上がりを確認します。作ったプロジェクトは projects/<名前>/ に保存され、git にはコミットされません。正面向きのバストアップで、背景が透明な PNG がいちばんきれいに仕上がります。
エディタで何もプロジェクトを開いていないときは、この依頼文をコピーできる形で表示します。
![]()
推奨する組み合わせは次のとおりです。
| エージェント | モデル |
|---|---|
| Claude Code | Claude Opus 5.5 |
| Codex | GPT-6.1 Sol |
Codex でコマンド1つで作る
Codex CLI をインストールしてサインインしていれば、次のコマンド1つで プロジェクトの作成、Codex によるエージェントガイドの実行(途中の質問なし)、完成したアバターをエディタで開くところまで進みます。
npm run create -- /path/to/your-image.png
Codex は OpenAI の画像生成で、閉じ目・口の形・表情の描き分けも作ります。イラストの口が開いていれば、先に口を閉じた絵にします。画像とマスクが OpenAI に送られるため、
コマンドは最初に確認します。--yes を付けると事前に同意し、--no-variants を付けるとすべて手元のマシンの中で行います。
通常は数十分かかります。Codex のメモは projects/<name>/HANDOVER.md に書き出されます。
Codex は --approve-for-me 付きで動くため、ポーズ確認用の Chromium など sandbox の外でツールを動かす許可は、
あなたの代わりに自動レビューが判断します。オプションは npm run create -- --help で確認できます。
手元にイラストがなければ、--random を付けると Codex がアニメ調の女の子を新しく描き、そこからアバターを作ります。
見た目はランダムに決まります。--prompt で希望を伝えることも、--seed で同じランダムな組み合わせを再現することもできます。
描いた絵は work/random/ に、選ばれた見た目は projects/<name>/work/character.json に残ります。
npm run create -- --random
npm run create -- --random --prompt "銀髪のショートヘア、制服"
2. プロジェクトを開いて確認する
エディタを起動し(npm run dev)、「プロジェクトを開く」の一覧から作ったプロジェクトを選びます。一覧の鉛筆ボタンを押すと、プロジェクトの名前を projects/ のフォルダ名ごと変えられます。眼鏡などの重ねるレイヤー(built/overlays/)があるアバターでは、プレビューの「重ねるレイヤー」で表示を切り替えられます。「ポーズ確認」で顔の向きや傾き、目の開閉を確かめ、「口の動き」では「ゆったり」「キビキビ」などを選んで口パクを試します。「細かく調整する」で口の大きさや閉じ方を調整し、音声ファイルでも確認できます。
![]()
3. おかしいところをドラッグで直す
左の一覧でパーツを選ぶと、画像の上にそのパーツの点が強調して表示されます。点をドラッグして位置を直してください。変更はプレビューにすぐ反映されます。ただし、目や手の輪郭と、髪のマスクに使う頭・髪・お団子の範囲は、画像をレイヤーに切り出すときにも使います。これらを変えると画面の上に帯が出るので、「保存してレイヤーを作り直す」を押してください。数秒で終わります。
![]()
![]()
拡大・縮小はピンチか Ctrl/Cmd+スクロール、移動は2本指のスクロールか、点のない場所のドラッグで行います。「選択中のパーツに合わせる」を押すと、選んでいるパーツまで拡大します。
4. 目と口の描き分け画像を作る
描き分け画像がない間は、目と口をメッシュの変形だけで動かしています。閉じた目や母音ごとの口の絵を用意すると、まばたきと口の動きがかなり自然になります。「描き分け画像」の欄で「目」「口」の片方または両方にチェックを入れ、表示された文章をコピーして、このリポジトリのフォルダで開いた Codex に貼り付けてください。Codex が組み込みの画像生成で絵を作って取り込み、エディタが自動で読み込み直します。Claude Code は画像を生成できないため、Claude Code 向けの文章では、マスクと依頼文を用意して画像生成に渡すファイルを案内するところまでを頼みます。
「表情の目と口」は任意です。悲しい目・驚いた目と、怒った口・悲しい口(閉じた口)を描き分けると、その表情や感情タグのときに描いた絵へ切り替わります。まばたきや話すときの口はそのまま動きます。描いていないアバターの見た目は今までと変わりません。
![]()
アバターを共有する
エディタの「.mavatar を書き出す」で、保存済みの設定・レイヤー画像・目と口の差分画像・アバターの情報を1つのファイルにまとめてダウンロードできます。「元画像を含める」は初期状態でオンです。受け取った人がStudioで編集する場合は、そのまま書き出してください。未保存の編集は「保存して書き出す」で反映できます。輪郭を変更した場合は、先にレイヤーを作り直してください。読み取り専用の画面では元のファイルを書き出します。
受け取ったファイルは「プロジェクトを開く」の「.mavatar を取り込む」から選ぶか、その欄にドロップします。projects/ の中に新しいフォルダが作られ、同名のフォルダがある場合は別の名前になります。取り込みには npm run dev が必要で、上限は128 MiBです。元画像を含めなかった場合は再生専用となり、編集やレイヤーの作り直しはできません。元画像を除いても、レイヤー画像はファイルに残ります。詳しくはアバターの形式(英語)を参照してください。
カメラで動かして配信する
![]()
エディタでプロジェクトを開き、「配信」を選びます。カメラを開始し、目と口の力を抜いて口を閉じ、正面を向いた状態で「正面の姿勢を登録」を押してください。左右反転、感度、動きのなめらかさを調整できます。マイクで口を動かすこともできます。映像と音声は端末内で処理し、配信用画面に渡すのはアバターの動きの数値だけです。
「体の動きを認識(実験的)」は、初期状態ではオフです。オフのときは、これまでどおり顔だけを追跡します。オンにすると、映っている肩・腰・肘・手首も使い、読み込んだアバターで追従する部位を表示します。上半身は常に追従し、脚と腕は rig に設定がある場合だけ動きます。カメラで捉える体の位置は顔よりもぶれやすいため、スカートなどの布が余分に揺れることがあります。詳しくはリファレンス(英語)を参照してください。
背景を選んで「OBS用URLをコピー」を押し(先に見た目を確かめたいときは「OBS用の画面を別タブで開く」)、操作画面を開いたまま、OBSの「ブラウザ」ソースにURLを貼り付けます。サイズは 1080 × 1080 などに設定してください。背景が透明なら、そのままOBSで重ねて表示できます。ほかのソフトで取り込む場合は、緑の背景にしてクロマキーで抜く方法も使えます。
どちらの画面もローカルの開発サーバー(npm run dev)で使います。操作画面からの更新が止まると、配信用画面は待機動作に戻ります。
「ライティング」を有効にすると、ドラッグで動かせる光源に合わせてアバターに陰影が付きます。初期状態はオフです。配信の操作画面の下のほう、またはエディタのプレビューの下にある欄で設定でき、設定はOBS用URLにも含まれます。詳しくはリファレンス(英語)を参照してください。
眼鏡などの重ねるレイヤー(built/overlays/)があるアバターでは、配信の操作画面の「重ねるレイヤー」で表示を切り替えられます。配信画面にもすぐ反映され、表示中のレイヤーはOBS用URLにも含まれます。
操作画面は専用のウィンドウで開いたままにしてください。OBS用URLはOBSの中か別のタブで開き、操作画面のタブには貼り付けないでください。画面が隠れて追跡が停止・低速になったという表示が出た場合は、操作画面のウィンドウを前面に戻してください。
![]()
「表情」のボタンか、キー1〜8で、笑顔、驚き、ウインクなどに切り替えられます。切り替えている間も、まばたきや口の動きはカメラとマイクに合わせて動きます。Stream Deck のボタンやキーボードショートカットを使えば、OBS など他のアプリを操作中でも切り替えられます。macOS の「ショートカット」アプリで割り当てたキーは、前面のアプリによっては効かないことがあります(設定方法、英語)。
ライティングの設定は、プリセットとして8つまで保存できます。ホラーゲーム用に下から赤い光を当てる設定などを保存しておき、Shift+1〜8 や同じ仕組みのショートカットで切り替えられます(詳しく、英語)。
カメラは使わなくてもかまいません。マイクだけをオンにすると、アバターは待機動作を続けながら、声に合わせて口を動かします。Zoom や Google Meet などの Web 会議にアバターで参加するときは、OBS の仮想カメラを使います(手順、英語)。
配信用画面の URL で指定できる項目、うまく動かないときの確認点、プライバシーについてはリファレンス(英語)にまとめています。
インストールせずに使う
Player では、顔の追従、マイクでの口パク、表情、ライティングをすべてブラウザ内で動かせます。サンプルか自分の .mavatar ファイルを開いて使い、ファイルはアップロードされません。OBS用URLはないため、「アバターウィンドウを開く」(Chrome か Edge)を押し、そのウィンドウを緑の背景にして OBS の「ウィンドウキャプチャ」で取り込み、クロマキーで抜いてください。透明な背景、OBS の「ブラウザ」ソース、他のアプリからの表情の切り替えを使うときは、Studio の配信画面を使います。
実験的なネイティブ版
Rust版のランタイム、PNGレンダラー、macOS向けの透明なデスクトップアバターを開発しています。
JavaScript版と同じ .mavatar ファイルとビルド済みプロジェクトフォルダを読み込めます。
ビルド方法と操作はネイティブ版のガイドを参照してください。
実験的な機能のため、APIや操作方法は変更されることがあります。
リリース
mesh-avatar を変更するときは npm run changeset を実行し、生成されたファイルをPRに含めてください。main に変更が入ると、GitHub Actionsが次のバージョンと変更履歴を含む chore: version packages PRを作成・更新します。そのPRをマージすると、mesh-avatar がprovenance付きでnpmに公開されます。Studioのルートパッケージは非公開のままです。公開にはnpmのtrusted publishingを使います。npmjs.comの mesh-avatar の設定で、このリポジトリと release.yml ワークフローをtrusted publisherとして登録してください。npmのトークンをリポジトリに保存する必要はありません。trusted publisherに一致しない公開は、メンテナーが2FAで承認するまでStaged Packagesタブで待機します。ワークフローがバージョン更新のPRを作成できるよう、リポジトリの Settings → Actions → General で Allow GitHub Actions to create and approve pull requests を有効にしてください。PRを作る前に、手元で npm run e2e を実行してください。CIはその他の検証を実行し、Playwrightのブラウザはインストールしません。
詳しい資料
- エージェント向けの手順書: エージェントが作業するときの手順
- リファレンス: プロジェクトの扱い、レイヤーを手作業で作る方法、エディタの全操作、テスト
- リグの項目:
rig.jsonの各値の意味 - アバターの形式: フォルダと
.mavatarの構成、メタデータ、検証方法
いずれも英語です。
ライセンス
コードは MIT License で公開しています。
サンプルのキャラクター「ミコ」(samples/miko-qipao/)は MIT License の対象外です。ミコは AITuber OnAir のキャラクター(© Yuki Shindo (AITuber OnAir))で、画像はミコ キャラクター利用ガイドラインに従って提供しています。概要は samples/miko-qipao/MIKO_ASSET_TERMS.md を参照してください。自分の作品の一部として利用・改変できますが、画像だけを単体で配布したり、素材集として配布したりすることはできません。このプロジェクトは AITuber OnAir の公式製品ではありません。
顔の追跡と実験的な体の追跡には MediaPipe(@mediapipe/tasks-vision と、vendor/mediapipe/ の Face Landmarker と Pose Landmarker lite のモデル)を使っています。© The MediaPipe Authors、Apache License 2.0 です。vendor/mediapipe/LICENSE を参照してください。