msch-puppet-face
Legacy component. Install MSCH Nodes instead: github.com/mariobilly/msch-comfyui-nodes
Nodes (3)
The boring front door to the Puppet Face pack (and why its video loader is the part that matters)
Landmarks on a face plus a grab-ring pointer that tracks it
The unglamorous MP4 saver that finishes every PuppetFace chain
Superseded by MSCH Nodes: one install for the complete collection.
This standalone repository is retained for historical links and existing installations. New nodes and updates belong to the unified pack. Follow the migration guide before switching to avoid duplicate nodes.
MSCH Puppet Face
Face landmark and animated cursor overlays with self-contained OpenCV video loading and MP4 saving.
Node reference · Example workflows and results · Publishing guide
<!-- MSCH SHOWCASE -->
View the showcase: videos, images and workflows
<!-- /MSCH SHOWCASE -->Included nodes
| Node | What it does | |---|---| | PuppetFace ▸ Landmark + Cursor Overlay | Draw facial landmark dots, optional connecting mesh and an animated mouse cursor over each frame. | | PuppetFace ▸ Load Video | Decode a selected video into RGB IMAGE frames using OpenCV. | | PuppetFace ▸ Save Video | Encode an IMAGE batch as a uniquely numbered MP4 in ComfyUI's output directory using OpenCV's mp4v writer. |
Installation
Clone into ComfyUI/custom_nodes:
git clone https://github.com/mariobilly/msch-puppet-face.git
Open a terminal in the cloned folder and install requirements using the same Python environment as ComfyUI:
python -m pip install -r requirements.txt
Windows portable, from ComfyUI_windows_portable:
.\python_embeded\python.exe -m pip install -r .\ComfyUI\custom_nodes\msch-puppet-face\requirements.txt
Restart ComfyUI and refresh the browser. Load a JSON workflow from examples/ and select the supplied demo input or your own media. Keep only one installed copy of each package to avoid duplicate node registrations.
Requirements and behavior
Includes three nodes: load video, overlay and save video. Optional ONNX tracking uses onnxruntime plus SCRFD and 106-point landmark models in ComfyUI/models/insightface/models/antelopev2. No models are bundled. Without a usable precise tracker the overlay falls back to approximate face-box geometry. The included video loader/saver does not preserve source audio. Consult the model distributor's license before using optional model weights.
Optional ONNX inference dependency: python -m pip install onnxruntime. Supply compatible model files separately.
Documentation and examples
docs/NODES.md documents every input, default, range, choice and output. examples/README.md explains which inputs and other nodes each workflow needs and how the included results were produced.
ComfyUI Manager
The release includes Comfy Registry metadata and a GitHub publishing action. Version 0.1.0 was uploaded successfully to Comfy Registry under publisher mariobilly on 2026-09-06. Registry reported Pending at verification; Manager installation availability is not yet confirmed. A separate ComfyUI Manager node-list registration has been submitted; listing is pending maintainer acceptance. Git installation works independently. See PUBLISHING.md.
Validation
Imports and input schemas were checked against the local ComfyUI environment with Python 3.12.10, PyTorch 2.10 and CUDA available. Example render coverage is documented per workflow; this is not a claim of compatibility testing on every platform or of full MiniMax H3 model-generation validation.
License
Project code: MIT. Third-party assets and optional model weights keep their own licenses.