PNGTuber Image Mouth Builder (static, transparent)

Not every PNGTuber starts as a talking video. The other common case is a single transparent character render - the art style where you draw one image and the mouth moves on top of it. That's what this node is for: PNGTuberImageMouthBuilder takes a transparent PNG, erases the original mouth into clean skin while preserving the alpha channel, generates the five mouth shapes (closed/half/open/e/u) with the local Qwen/eigen stack, and writes a runtime bundle with a static track. No video, no white matte, no fake background - the transparent mouthless PNG you get back is directly usable as your stream asset.

How it works

The pipeline is the static-image cousin of the video path, with one quality rule worth knowing: it refuses the cv2 inpaint fallback. If the Qwen/eigen erase fails, the node raises rather than ship a blurry CV patch - the author decided a failed run is better than a bad rig. That means this node is a hard dependency on the local Qwen image-edit stack (model, text encoder, VAE, TextEncodeQwenImageEditPlus), not an optional upgrade. Plan for that before you build a workflow around it.

Localization defaults to eigen_qwen_then_yolo: Qwen/eigen localization first, then a YOLO face model refine, with legacy_fallback as the older cascade path. For tricky art, skip the whole auto dance and pass manual_mouth_bbox as x0,y0,x1,y1 - it's a four-number string and it's deterministic, so it's usually faster than nudging detection settings.

Inputs and outputs

• image_path - your transparent character PNG.
• sprite_size (512), track_quad_scale (1.8), erase_scale (1.55) - sprite resolution, track quad size, and how far the erase region extends past the mouth. Bump erase_scale if mouth residue shows through.
• seed (42) - shared by the erase and shape-generation passes, so you can iterate on one run's results.
• mouth_localization - eigen_qwen_then_yolo (default), eigen_qwen, eigen_qwen_only, face_yolo_refine, legacy_fallback.
• manual_mouth_bbox - art-direction override.

Outputs: mouthless_png (the erased transparent character), mouth_track_json (a single static frame record with the mouth quad), and bundle_dir (the whole bundle - five sprites under mouth/, cover patches, manifest). Schema is pngtuber.imageMouthBundle.v1.

Install

Same pack as everything here - ComfyUI Manager search for ComfyUI-PromptMaker-PNGTuber, or:

cd /path/to/ComfyUI/custom_nodes
git clone https://github.com/hobi2k/ComfyUI-PromptMaker-PNGTuber.git
cd /path/to/ComfyUI
python -m pip install -r custom_nodes/ComfyUI-PromptMaker-PNGTuber/requirements.txt

Restart, and then satisfy the Qwen stack (see the pack README's generated-mouth section for the model list). The base requirements.txt here is just MediaPipe/OpenCV/Pillow/etc. - the Qwen models are separate, multi-GB downloads.

Common issues

• "Eigen/Qwen mouth erase failed; refusing local CV inpaint fallback" - the Qwen stack isn't there, or the model filenames don't match what the code loads. Fix the stack; there's no bypass on this node by design.
• "No mouth bbox resolved" - auto-detection missed. Feed manual_mouth_bbox; the exact four numbers from an image editor work fine.
• Mouth shape looks off-character - Qwen edit identity drift on stylized art. If your art style is far from Qwen's comfort zone, consider the frame sequence builder route instead, where mouth shapes come from actual frames of your character rather than generation.