VoxCPM_SM_KSampler

This is where VoxCPM stops being a model and becomes audio. Feed it the model from VoxCPM_SM_Model, type the line you want spoken, and out the audio socket comes a real WAV that PreviewAudio or SaveAudio can play. It's the node at the end of every workflow in this pack, and for a TTS pack it's refreshingly close to "just works": type, click, listen.

The mechanism underneath is the same diffusion-autoregressive engine from the OpenBMB paper - the KSampler is a thin wrapper over the model's generate(). That's why steps and cfg exist. steps is the number of LocDiT inference timesteps (10 is the default and honestly fine); cfg is the LM guidance scale, where higher means the output sticks closer to the prompt but can get a little rigid. Start at 2 and only nudge it.

The inputs that matter

• text - what to say. The node raises "Please input text" if you leave it blank, and that's the error you'll hit first.
• voice_design - a natural-language style tag that gets wrapped around your text, e.g. "A young woman, gentle and sweet voice". This is the free prosody/emotion lever, and it's easy to sleep on. Try "(slightly faster, cheerful tone)".
• audio (optional) - drop a reference clip in for zero-shot voice cloning. This is the headline feature: a few seconds of someone talking and the model reproduces timbre, accent, pacing. Wire a LoadAudio node into it.
• ref_text - the transcript of that reference clip, used for prosody matching. If you don't feed audio, the node nulls ref_text for you, so no need to clear it by hand.
• seed - exists for rerolling. The README is honest that it doesn't always fully take, because the language model isn't running greedy decode. Think soft reroll button, not reproducibility guarantee.
• retry_badcase / retry_badcase_ratio_threshold / retry_badcase_max_times - a built-in safety net that detects when the audio-to-text ratio looks wrong (the model stuck or running on) and re-rolls up to retry_badcase_max_times times. Leave them on; the threshold is a length guard, not a quality dial.

Cloning modes

• Plain cloning: audio in, ref_text in, done. The community consensus is that VoxCPM's zero-shot clone is genuinely good - more accurate and skipping fewer words on long text than its more-hyped cousins.
• controllable_cloning - two-pass: it clones your reference voice, then re-synthesizes with voice_design styling on top. Needs an audio input; enable it without one and it will assert at you.
• ultimate_clone - VoxCPM2 only (the node checks version == "v2"), uses the reference as both prompt and target for maximum similarity. The "put this exact voice in the room" option.
• streaming - emits audio in chunks as it generates. Real-time-ish on a 4090 (the model's RTF is around 0.15), fun to watch, but for a normal "render me a line" job, off is simpler.

The output is audio in ComfyUI's native AUDIO format - the {waveform, sample_rate} dict - so any standard preview/save audio node works. save_wav also writes a copy into ComfyUI/output/ with a seed-tagged filename, which is handy for keeping every take.

Install and wiring

Shared with the whole pack: clone https://github.com/smthemex/ComfyUI_VoxCPM_SM into ComfyUI/custom_nodes, pip install -r requirements.txt, restart. Then load a model via VoxCPM_SM_Model first - you need a VAE and a backbone, and remember v2's VAE means 16 kHz output. The dependency stack (torch>=2.5, transformers, funasr, modelscope, datasets<4) is heavy enough that a clean venv is the answer when other packs start fighting at import time.

Where people get burned

• The classic accent complaint: clone from an accented or noisy reference and the clone inherits it. That's the model working as designed, not a bug - clean reference audio is the fix.
• VoxCPM 1.5 has a known tendency toward a metallic tail at the end of longer sentences, per community reports. Chunking long text or using v2 sidesteps it.
• Sample-rate confusion: v1.5 outputs 44.1 kHz, v2 outputs 16 kHz. If a downstream video track expects one or the other, that's why.
• If errors happen at import rather than at generation, it's the dependency fight, not your workflow.

VoxCPM is quietly one of the better-kept TTS secrets around. This node is how you reach it from ComfyUI.