Troubleshooting Guide

Camera & tracking

No camera image

Allow camera access when the browser asks. On macOS, also check System Settings → Privacy & Security → Camera for your browser. Chrome is recommended.

Movement is too small or jittery

Raise Sensitivity (too small) or Smoothing (jittery) on the Live page. Then calibrate again while facing the camera with a relaxed face — a good calibration beats slider tuning.

Left and right are swapped

Toggle Mirror.

Tracking stops or slows in the background

Tracking runs in a Web Worker and should continue with the Live page hidden — but if the page reports it stopped, bring its window to the front.

Streaming

The avatar flickers or an expression keeps flipping

The project is open in two Live tabs — the Live page warns when it is. The stream view follows one of them while app-switching reaches both. Close the tab you are not using.

The stream view stays idle

Keep the Live page open and running, and make sure both pages use the same project name.

Transparent background turns black in Zoom/Meet

That is the OBS Virtual Camera, not a bug — put a color or image source behind the avatar in your OBS scene. See the OBS guide's video-call section.

Installation & projects (Windows focus)

The editor cannot read a project

Classic cause on Windows: the project came from a ZIP without Unblock, or a folder created by another account or a sandboxed agent. Fix with the folder's Properties → Security: grant your account access to the whole project, including subfolders (permission inheritance). Create projects/ under your own account before involving agents.

Which tool is missing?

npm run doctor reports each one separately: Node itself, uv/Python (layer rebuilding), Chromium (agent motion review). Treat a warning as a blocker only for the step that needs that tool.

Editing & layers

Changed an outline — now what?

Eye and hand outlines and the head/hair/bun areas decide how the image is cut into layers. After editing them, click Save and rebuild layers in the banner; it takes a few seconds and keeps your selection, zoom and undo history.

A layer build failed

The previous layers are kept and a log is offered. The builder needs Python 3.10+ with uv — npm run doctor checks it.

Blinking leaves eye pixels behind

The eye opening outline probably includes lashes or skin. Re-drag it inside the lashes in the editor, rebuild layers, and check with Pose test. Faint lash-line remnants above the closed eye are what drawn variants remove — see the creation guide.

Hair mask has gaps

Bright hair highlights or multi-colored hair can defeat automatic mask inference. Adjust the hair/bun areas in the editor and rebuild.

Drawn variants

A generated variant was rejected

Import requires identical untouched pixels outside the mask and the same aspect ratio; the importer corrects up to 3 px shifts and uniform tints, and logs the exact rejection reason. Regenerate asking for identical size and untouched pixels outside the masked area.

Still stuck?

Check the official reference documentation or open an issue on the GitHub tracker — bug reports with your OS, browser and the failing step get fixed fastest.