{"slug": "turn-a-single-illustration-into-an-animated-2d-avatar-mesh-avatar-studio", "title": "Turn a single illustration into an animated 2D avatar: Mesh Avatar Studio", "summary": "Mesh Avatar Studio, a project from developer shinshin86, turns a single front-facing illustration into an animated 2D mesh avatar that blinks, talks, turns its head, breathes and sways its hair, with a coding agent (Claude Code or Codex) preparing the rig and layers from the image and a local editor used for fine-tuning. The tool requires Node.js 22.17+ and Git and is installed via `npx create-mesh-avatar-studio`, with uv and Python needed to rebuild layers and Playwright Chromium used to render the motion review when an agent creates an avatar. The project recommends Claude Opus 5.5 for Claude Code and GPT-6.1 Sol for Codex, and notes that best results come from a front-facing, head-and-shoulders PNG with a transparent background.", "body_md": "Turn a single illustration into an animated 2D mesh avatar: it blinks, talks, turns its head, breathes and sways its hair. A coding agent prepares the avatar from your image; you fine-tune it in a local editor with a live preview.\n\nSee it move on the [landing page](https://shinshin86.github.io/mesh-avatar-studio/).\nTo move it with your own face and voice without installing anything, open the\n[Player](https://shinshin86.github.io/mesh-avatar-studio/play/) in Chrome or Edge.\n\nRequires Node.js 22.17+ and Git.\n\n```\nnpx create-mesh-avatar-studio\ncd mesh-avatar-studio\nnpm run dev\n```\n\nThe first command downloads the repository, installs its packages and checks the tools\nStudio needs. If you cloned the repository yourself, run `npm install`, then\n`npm run doctor` for the same check. Only Node.js is needed for the editor and the Live\npage. uv and Python rebuild layers, and Playwright Chromium renders the motion review when\nan agent creates an avatar; the check warns about each one that is missing.\n\nOpen the URL printed in the terminal (for example `http://127.0.0.1:5173/`). The editor opens\nthe bundled sample, Miko in a qipao. Pick a part on the left, drag its dots on the image and\nwatch the preview on the right. The sample is read-only; when you change it, choose\n**Copy and keep editing** to continue in your own copy.\n\nUse `git clone` to download the repository when possible. If you use a ZIP, open its\nProperties in File Explorer and select **Unblock**, if shown, before extracting it.\n\nCreate `projects/` yourself under your Windows account before asking an agent to work in it\n(`npx create-mesh-avatar-studio` creates it for you).\nFolders created by another account or an agent running in a sandbox can have permissions\nthat prevent the editor from reading them. If a project cannot be read, use the folder's\n**Properties → Security** settings to grant your account access to the whole project,\nincluding its files and subfolders through permission inheritance.\n\nMaking an avatar from your own illustration takes four steps. Steps 1 and 4 are done by a coding agent (Claude Code or Codex) working in this repository; steps 2 and 3 happen in the editor.\n\nOpen Claude Code or Codex in this repository folder and give it your illustration:\n\nCreate an avatar from this image following docs/agent-guide.md: `/path/to/your-image.png`\n\nThe agent follows [the agent guide](https://github.com/shinshin86/mesh-avatar-studio/blob/main/docs/agent-guide.md): it checks how accurately it reads\ncoordinates, places the rig on zoomed grids, cuts the image into layers and reviews the\navatar in fixed poses. The project is saved in `projects/<name>/`, which is never committed.\nBest results come from a front-facing, head-and-shoulders PNG with a transparent background.\nWhen no project is open, the editor shows this request ready to copy.\n\nRecommended setups:\n\n| Agent | Model | \n|---|---|\n| Claude Code | Claude Opus 5.5 | \n| Codex | GPT-6.1 Sol | \n\nStart the editor (`npm run dev`), choose **Open project** and pick your project from the list.\nIn the preview, use **Pose test** to turn and tilt the head and close the eyes. In **Lip sync**,\nchoose a mouth style and try it with kana text. Open **Fine-tune** to adjust movement, size\nand closing, or preview a local audio file.\n\nSelect a part on the left. Its dots are highlighted on the image; drag them to fix the\nplacement. The preview follows your changes immediately. Some values also decide how the image\nis cut into layers: eye and hand outlines, and the head, hair and bun areas used for the hair\nmask. After changing those, a banner appears; choose **Save and rebuild layers** there. It takes\na few seconds.\n\nZoom with a pinch or Ctrl/Cmd+scroll, pan with two fingers or by dragging empty space, and use\n**Fit selected part** to jump to the current part.\n\nWithout drawings, the eyes and mouth move by mesh deformation alone. Drawn closed eyes and\nvowel mouths make blinking and talking look much more natural. In **Drawn variants**, check\n**Eyes**, **Mouth** or both, copy the message and paste it into Codex opened in this\nrepository folder. Codex draws them with its built-in image generation and imports them; the\neditor reloads them automatically. (Claude Code cannot generate images; its message prepares\nthe masks and prompts for you to hand to an image generator.)\n\n**Expressions** is optional: it adds drawn sad and surprised eyes and closed angry and sad\nmouths. The avatar switches to them for those expressions and emotion tags and still blinks\nand speaks; avatars without them look the same as before.\n\nChoose **Export .mavatar** in the editor to download one file containing the saved rig,\nbuilt layers, drawn expressions and avatar metadata. **Include source image** is on by\ndefault so the recipient can edit it in Studio. If you have unsaved edits, use **Save and\nexport**; changed outlines need a layer rebuild first. Read-only views export the original files.\n\nIn **Open project**, choose **Import .mavatar** or drop the file there. Studio creates a new\nfolder under `projects/`, using a new name if one already exists. Import requires `npm run dev`\nand accepts archives up to 128 MiB. Without the source image, the imported avatar can play but\ncannot be edited or rebuilt. Omitting the source does not remove the built images.\nSee the [avatar format](https://github.com/shinshin86/mesh-avatar-studio/blob/main/docs/format.md) for the file contents.\n\nOpen your project in the editor and choose **Live**. Start the camera, face forward with\nrelaxed eyes and a closed mouth, then choose **Calibrate**. You can adjust mirroring,\nsensitivity and smoothing, or enable microphone lip sync. Camera video and microphone\naudio stay on your machine; only numeric avatar motion values reach the stream view.\n\nChoose a background and **Copy OBS URL**, or **Open stream view in a new tab** to check it first. Keep the Live page open and add the URL as an\nOBS **Browser Source**, for example at **1080 × 1080**. The transparent background works\ndirectly in OBS. For other capture software, choose green and apply a chroma key.\nBoth pages use the local development server (`npm run dev`). The stream view shows idle\nmotion when the Live page stops sending updates.\n\nOptional **Lighting** adds shading that follows a light you drag over the avatar. It is off\nby default; open its section near the bottom of the Live page, or below the preview in the\neditor. The OBS URL includes the lighting settings. See [Lighting](https://github.com/shinshin86/mesh-avatar-studio/blob/main/docs/reference.md#lighting).\n\nKeep the Live page open in its own window. Open the OBS URL inside OBS or in another tab; do not paste it into the tab running Live. If the page reports that tracking has stopped or slowed while hidden, bring its window to the front.\n\nSwitch expressions such as a smile, surprise or a wink with the **Expression** buttons or\nkeys **1**–** 8** while tracking continues. A Stream Deck button or a keyboard shortcut can\nswitch them while another app such as OBS is in front; macOS Shortcuts keys do not work in\nevery app ([details](https://github.com/shinshin86/mesh-avatar-studio/blob/main/docs/reference.md#switching-expressions-from-other-apps)).\n\nSave up to eight lighting setups, such as a red light from below for a horror game, as\npresets, and switch them with **Shift**+** 1**–** 8** or the same kind of shortcut\n([details](https://github.com/shinshin86/mesh-avatar-studio/blob/main/docs/reference.md#lighting-presets)).\n\nThe camera is optional: with only the microphone on, the avatar keeps its idle motion and\nyour voice moves the mouth. To appear as the avatar in Zoom, Google Meet and similar apps, use\nOBS's Virtual Camera ([steps](https://github.com/shinshin86/mesh-avatar-studio/blob/main/docs/reference.md#video-calls)).\n\nStream view options, troubleshooting and privacy details are in the\n[reference](https://github.com/shinshin86/mesh-avatar-studio/blob/main/docs/reference.md#live-and-streaming).\n\nThe [Player](https://shinshin86.github.io/mesh-avatar-studio/play/) runs face tracking,\nmicrophone lip sync, expressions and lighting entirely in the browser. Open the sample or\nyour own `.mavatar` file; nothing is uploaded. It has no stream URL: choose **Open avatar\nwindow** (Chrome or Edge) and add that window to OBS with **Window Capture** on a green\nbackground and a Chroma Key filter. Transparency, the OBS Browser Source and switching\nexpressions from other apps need Studio's Live page.\n\nFor changes to `mesh-avatar`, run `npm run changeset` and include the generated file in your\nPR. On `main`, GitHub Actions opens or updates a `chore: version packages` PR with the next\nversion and changelog; merging it publishes `mesh-avatar` to npm with provenance. The Studio\nroot package stays private. Publishing uses npm trusted publishing: on npmjs.com, add a trusted publisher for\n`mesh-avatar` that names this repository and the `release.yml` workflow; no npm token is stored\nin the repository. A publish that npm cannot match to a trusted publisher waits in the\nStaged Packages tab until a maintainer approves it with 2FA. In repository\nSettings → Actions → General, enable **Allow GitHub Actions to create and approve pull requests**\nso the workflow can open version PRs. Run `npm run e2e`\nlocally before opening a PR; CI runs the other checks and does not install Playwright browsers.\n\n- [Agent guide](https://github.com/shinshin86/mesh-avatar-studio/blob/main/docs/agent-guide.md) : the step-by-step procedure agents follow\n- [Reference](https://github.com/shinshin86/mesh-avatar-studio/blob/main/docs/reference.md) : projects, building layers by hand, all editor controls, tests\n- [Rig fields](https://github.com/shinshin86/mesh-avatar-studio/blob/main/docs/rig-fields.md) : what every value in`rig.json` means\n- [Avatar format](https://github.com/shinshin86/mesh-avatar-studio/blob/main/docs/format.md) : folder and`.mavatar` layouts, metadata and validation\n\nThe code is released under the [MIT License](https://github.com/shinshin86/mesh-avatar-studio/blob/main/LICENSE).\n\nThe sample character Miko (`samples/miko-qipao/`) is not covered by the MIT License. Miko is the\ncharacter of AITuber OnAir, © Yuki Shindo (AITuber OnAir), and her images are provided under the\n[Miko Character Usage Guidelines](https://miko.aituberonair.com/#terms); see\n[samples/miko-qipao/MIKO_ASSET_TERMS.md](https://github.com/shinshin86/mesh-avatar-studio/blob/main/samples/miko-qipao/MIKO_ASSET_TERMS.md). They may be used\nand modified as part of your own works, but not redistributed on their own or as an asset\ncollection. This project is not an official AITuber OnAir product.\n\nFace tracking uses [MediaPipe](https://github.com/google-ai-edge/mediapipe) (`@mediapipe/tasks-vision`\nand the Face Landmarker model in `vendor/mediapipe/`), © The MediaPipe Authors, licensed under the\nApache License 2.0; see [vendor/mediapipe/LICENSE](https://github.com/shinshin86/mesh-avatar-studio/blob/main/vendor/mediapipe/LICENSE).", "url": "https://wpnews.pro/news/turn-a-single-illustration-into-an-animated-2d-avatar-mesh-avatar-studio", "canonical_source": "https://github.com/shinshin86/mesh-avatar-studio", "published_at": "2026-10-24 14:58:43+00:00", "updated_at": "2026-10-24 15:11:14.109309+00:00", "lang": "en", "topics": ["ai-tools", "ai-agents", "generative-ai", "developer-tools"], "entities": ["Mesh Avatar Studio", "shinshin86", "Claude Code", "Codex", "Claude Opus 5.5", "GPT-6.1 Sol", "Node.js", "Playwright"], "also_reported_by": [], "alternates": {"html": "https://wpnews.pro/news/turn-a-single-illustration-into-an-animated-2d-avatar-mesh-avatar-studio", "markdown": "https://wpnews.pro/news/turn-a-single-illustration-into-an-animated-2d-avatar-mesh-avatar-studio.md", "text": "https://wpnews.pro/news/turn-a-single-illustration-into-an-animated-2d-avatar-mesh-avatar-studio.txt", "jsonld": "https://wpnews.pro/news/turn-a-single-illustration-into-an-animated-2d-avatar-mesh-avatar-studio.jsonld"}}