🎤 Lyric Sync — Align

If you've ever tried to put on-screen lyrics over a ComfyUI video, you found out the hard way that ComfyUI is image-first and treats audio like an afterthought. LyricSyncAlign is the node that fixes the annoying middle step: you give it a real ComfyUI AUDIO value plus the lyrics pasted as plain text, and it hands back per-line (and per-word) timestamps that the pack's overlay and mosaic nodes turn into actual on-screen lyrics. It's the difference between captions that appear vaguely "around" the right time and captions that track the words as they're sung.

How it actually lines things up

This is the clever bit, and it's worth understanding before you judge it. The author doesn't ask WhisperX to transcribe your lyrics - Whisper famously mishears sung vocals. Instead, when you run the node it dumps your audio to a temp WAV and shells out to the WhisperX command-line tool, which builds a word-level timeline of what it thinks it heard. Then LyricSyncAlign matches your pasted lyrics (which it treats as ground truth) against that timeline with a sequence matcher. Words that line up get WhisperX's real timestamps; words WhisperX missed get linearly interpolated between the ones it caught.

That's the ideal path. If WhisperX isn't installed, can't run, or returns nothing usable, the node does not hard-fail: it just spreads your lyric lines evenly across the whole song duration. The README is refreshingly blunt that this fallback "is not measured vocal synchronization." If your captions are drifting off the beat, that's usually what you're looking at.

One practical consequence: WhisperX runs on CPU with float32 (--device cpu is baked into the call), so the medium default model is a sane middle ground. Going up to large-v3 gets better word timing on messy vocals but it'll feel slow.

The inputs that matter

The two required inputs are the whole job:

• audio (AUDIO) - any ComfyUI audio value. The pack is designed to sit in a VideoHelperSuite graph: VHS_LoadAudio feeds this, while VHS_LoadVideo feeds the overlay node downstream.
• lyrics (multiline STRING) - one line per on-screen caption box. Paste it as you'd expect it shown.

The optionals are mostly fine at defaults, but two are worth knowing:

• whisper_model - tiny through large-v3, default medium. CPU-bound, as above.
• whisperx_exe - path to the WhisperX executable if it isn't on PATH. The node also auto-detects the conventional Windows Python 3.13 location, which is a nice touch.
• language defaults to auto; set it explicitly for non-English songs so Whisper stops guessing.
• translation takes a parallel line per lyric line for bilingual caption rendering downstream.

Outputs

Two sockets: timing (LYRIC_TIMING, the custom type that wires straight into the pack's Caption Overlay and Word Mosaic nodes) and timing_json, a readable JSON STRING you can dump into a text preview node if you want to eyeball or save the alignment.

Installing it

This is the part that trips people up, because the README's requirement is honest about it: the node itself is light (numpy, Pillow, torch, plus arabic-reshaper and python-bidi for right-to-left text), but WhisperX is not in requirements.txt. It's an external CLI you install yourself:

cd ComfyUI/custom_nodes
git clone https://github.com/mariobilly/msch-lyric-sync.git
cd msch-lyric-sync
python -m pip install -r requirements.txt   # same Python env as ComfyUI

Then, separately, pip install whisperx in a Python 3.13 environment (the source targets that version on Windows) and make sure whisperx is on PATH or set whisperx_exe. WhisperX pulls model weights on first run and needs ffmpeg around.

Gotchas

Two things to flag. First: the README's own banner says this standalone repo is superseded by the unified MSCH Nodes pack - keep only one copy installed, and follow that migration guide before switching or you'll get duplicate node registrations. Second, this pack is brand new (v0.1.0, registry listing still pending), so Manager may not find it yet; the git clone route above works today. If your captions look synced but feel uniformly spaced, you're in the even-spread fallback - add WhisperX rather than fighting the lyrics.