HeyGem AI Avatar

You've got a clip of a person and an audio track, and you want the person to lip-sync the audio - a talking-head avatar, the kind of thing HeyGen and Synthesia charge a subscription for. HeyGemRun is how you do that locally and for free. It's the ComfyUI front-end for HeyGem, the open-source digital-human project that showed up in early 2025 as the first genuinely good self-hostable answer to those paid services. People had lip-sync before this (LatentSync, Wav2Lip), but the quality wasn't there. HeyGem was the one that finally looked usable.

The thing you need to understand first

This node is not a model that runs inside ComfyUI. That's the whole trick, and the part that trips people up. The actual HeyGem engine lives in a Docker container - a ~14GB image that runs separately from ComfyUI. HeyGemRun is basically a remote control: it packages up your audio and video, hands them to the Docker service, waits for the render, and pulls the result back into your graph. So when you install this, the small part is the node itself; the real install is getting Docker running.

The upside of that design is you don't fight Python dependency hell - the container is a sealed environment, so it "rarely reports errors," in the author's words. The downside is you now have a Docker daemon to babysit. Start Docker before every run, or the node has nothing to talk to.

Inputs and outputs that matter

The wiring is short. You feed it two things:

• audio - the voice track you want lip-synced. Any AUDIO output (a Load Audio node, a TTS node, whatever).
• video - the driving footage, as an IMAGE batch (frames). This is the person whose face gets re-animated.

The one setting worth thinking about is mode, which is pingpong (default) or repeat, and it only matters when your driving video is shorter than your audio. HeyGem stretches the video to fill the audio's length: repeat loops it back to the start (which can cause a visible jump-cut), while pingpong plays it forward then reverse so the loop is seamless. For most footage, pingpong is the safer pick. If your video is longer than the audio, the node just trims it - no setting needed.

Two optional knobs: fps (default 24) sets the output frame rate, and there's a hard rule in the README - your input video's frame rate should match this, or the sync drifts. stop_heygem (default false) shuts the Docker service down after the run to free up resources; leave it off while you're iterating so you're not paying the container spin-up cost every time.

The output is VIDEO, delivered as an IMAGE frame batch. It's not a finished file - pipe it into a Video Combine / Save node (with the same fps) to get an actual video out.

Installing it

The node half is trivial:

cd ComfyUI/custom_nodes
git clone https://github.com/billwuhao/Comfyui_HeyGem.git

Restart ComfyUI, or search "Comfyui_HeyGem" in ComfyUI Manager. That part's done in a minute.

The Docker half is the real work. On Windows you install WSL 2 and Docker Desktop, then let it pull the HeyGem image - that's the ~14GB download, and the first run takes around 30 minutes depending on your connection. On Linux you need Docker plus the NVIDIA Container Toolkit so the container can see your GPU (nvidia-ctk runtime configure --runtime=docker, then restart the daemon). The README walks both paths step by step. Budget the disk space and the first-run wait; after that it's just "start Docker, run the node."

Where people get tripped up

Almost every failure is Docker, not the node. If a run hangs or errors instantly, check the container's actually running first. Watch the fps match between your input video, the fps input, and your final combine node - a mismatch there is the usual cause of lips drifting off the audio. And a fairness note on the "open source" label: the underlying HeyGem license carries derivative-naming and branding requirements, so it's free to run but not free in the strict sense. Doesn't change how you use it, but worth knowing before you build a product on top of it.