🔧 Viseme Mouth Shape Options

This is a niche corner of the suite, and it's honest about being experimental. The pack has a Silent Speech Analyzer that watches a video of someone's mouth moving and tries to work out the timing - and rough phonetic shape - of what they're "saying," so you can build a base SRT for silent footage. A viseme is the visual shape a mouth makes for a sound (the "oo" shape, the "mm" closure). This options node is where you tune how sensitive and confident that mouth-shape detection is.

It's a settings node, full stop. It doesn't analyze anything itself - it outputs a VISEME_OPTIONS bundle that plugs into the video-analysis node and shapes how that node reads mouths. Set your reasonable-analysis expectations first: the README is upfront that viseme detection is an experimental approximation, and you should expect to hand-edit both the timing and the text it produces.

How it works

The analyzer detects mouth movement frame by frame, groups it into syllable-like chunks, and (optionally) guesses words. This node controls the thresholds on that pipeline: how strong a movement has to be to count, how confident a shape match must be to be accepted, how much to smooth jittery frames, and whether to attempt consonant detection, temporal analysis, and word prediction on top of raw vowel shapes. Turn features on for more (noisier) detail, off for cleaner but sparser output.

The inputs and outputs that matter

• viseme_sensitivity (default 2) - how readily it registers a mouth shape. Too high and it sees phantom movements; too low and it misses real ones. This is the first dial to try.
• viseme_confidence_threshold (0.4) - the bar a detection must clear to be kept. Raise it for fewer, surer detections; lower it to catch more (at the cost of false ones).
• viseme_smoothing (0) - smooths frame-to-frame jitter. Bump it up if results flicker.
• enable_word_prediction (off) - attempts to guess words from the shapes. Remember the README's warning: predicted "words" are phonetic placeholders, not meaningful sentences. Leave off unless you specifically want rough placeholders to edit.

enable_viseme_detection, enable_consonant_detection, and enable_temporal_analysis toggle the stages of the pipeline. Output is viseme_options (VISEME_OPTIONS) → into the silent-speech / mouth-movement analysis node.

Installing it

Comes with the pack. ComfyUI Manager → search "TTS Audio Suite" → install → restart. Manual:

cd ComfyUI/custom_nodes
git clone https://github.com/diodiogod/TTS-Audio-Suite.git
cd TTS-Audio-Suite
python install.py

The analysis itself relies on MediaPipe (Google's face/mouth-tracking framework) as the stable backend. Note a real compatibility catch: MediaPipe doesn't support Python 3.13 - on 3.13 the suite falls back to OpenSeeFace, which the README flags as experimental and not recommended for production. So if you're on the latest Python, expect the shakier provider.

Common issues & troubleshooting

Results are noisy or full of phantom detections. Lower viseme_sensitivity and raise viseme_confidence_threshold so only strong, confident mouth shapes register. Add a little viseme_smoothing to calm frame flicker.

It missed obvious mouth movements. The opposite - raise sensitivity and/or lower the confidence threshold. There's no perfect setting; this is approximate detection and you're trading false positives against misses.

The predicted text is nonsense. By design. enable_word_prediction produces phonetic placeholders, not real sentences - the intended workflow is to take the timing it gives you and write the actual words yourself before sending the SRT to a TTS node.

On Python 3.13 it's using OpenSeeFace and results are worse. That's the MediaPipe-incompatibility fallback. MediaPipe is the stable path; if quality matters, run the suite on a Python version where MediaPipe is available.