VoxCPM Voice Clone:
VoxCPM2_Clone generates new speech that follows the voice in a reference recording. It supports two cloning methods with VoxCPM2 models: controllable cloning uses the recording alone, while ultimate cloning also uses a transcript of what was said in that recording. Earlier VoxCPM models support cloning only when a transcript is available. The node can apply an optional LoRA, prepare the reference with denoising, and retry generations that appear to be silence or babbling. This makes it useful when you want to create spoken audio in a particular voice while choosing between a simpler reference-only workflow and a transcript-guided workflow.
VoxCPM Voice Clone Input Parameters:
model_name
Selects the VoxCPM model used to generate speech. The available options come from the installed VoxCPM model list, and the default is the first model in that list; the exact names depend on that list. Your choice determines which cloning methods are available: VoxCPM2 supports both reference-only controllable cloning and transcript-guided ultimate cloning, whereas V1 models require a transcript.
lora_name
Selects an optional LoRA checkpoint to apply to the model. Options are None and the files listed in models/loras; the default is None. A selected checkpoint is loaded and enabled for this generation. Choosing None disables LoRA, so you can clone without an additional checkpoint.
voice_description
Provides an optional style instruction, such as “slightly faster, cheerful tone.” This is a multiline string with an empty default and no stated length limit. In reference-only controllable cloning, the node places the description in parentheses before the text to be spoken. It ignores the description when a transcript is provided or ASR is enabled, so use it for reference-only style control rather than transcript-guided cloning.
text
Contains the words you want the generated voice to say. This is a multiline string with the default This is a cloned voice generated by VoxCPM. and no stated length limit. It describes the new speech you want to create; it is not the transcript of the reference recording. The node passes it to the model for generation, with the optional voice description prepended in controllable mode.
reference_audio
Supplies the voice recording used as the cloning reference. This required input is AUDIO and has no default. The node saves it temporarily as a WAV file and checks its duration before generation; recordings over the configured maximum produce an error. The maximum duration is not specified in the provided source. Use a recording that captures the voice you want to reproduce.
prompt_text
Contains the transcript of the words spoken in the reference recording. This multiline string has no stated default or length limit. Providing nonblank text selects transcript-guided cloning; leaving it blank selects reference-only controllable cloning with a VoxCPM2 model. A V1 model cannot clone without a transcript. When both this field and ASR are supplied, the node uses your written transcript instead of running ASR.
cfg_value
Sets the classifier-free guidance scale, which controls how strongly generation follows its conditioning. The default is 2.0, the minimum is 1.0, the maximum is 10.0, and the step is 0.1. According to the node tooltip, higher values favor prompt adherence, while lower values allow more natural variation. Adjust it gradually when balancing those qualities.
inference_timesteps
Sets the number of diffusion steps used to generate the audio. The default is 10, the minimum is 1, the maximum is 100, and the step is 1. More steps can improve quality but take longer, so this setting offers a direct quality-versus-speed tradeoff.
max_tokens
Limits generation length in tokens and thereby controls the maximum audio duration. The default is 4096, the minimum is 64, and the maximum is 8192. Increase it when the requested speech needs more room to complete; a lower limit constrains how long generation can continue. The source does not specify a fixed number of seconds per token.
normalize_text
Controls automatic processing of numbers, abbreviations, and punctuation before generation. This boolean defaults to True (Normalize); False is labeled Raw. Keep normalization on for ordinary written speech. The node tooltip advises turning it off for phoneme input so that input is passed through without this text-processing step.
enable_denoiser
Controls whether the reference audio is denoised during cloning. This boolean defaults to False (Off); True is labeled Denoise and requires the modelscope package according to the node tooltip. When enabled, the node also attempts to normalize the generated audio to −20 LUFS. If that loudness-normalization step fails, it logs a warning and uses the unnormalized generated audio.
seed
Sets the random seed used for generation. The default is 42, the minimum is -1, and the maximum is 18446744073709551615. Reusing a nonnegative seed sets the same random starting state for comparable runs. Setting -1 makes the node choose a random seed each run; it does not guarantee identical results when other settings or the execution environment change.
force_offload
Controls whether the node unloads the model after a successful generation. This boolean defaults to False (Auto); True is labeled Force Offload. Enabling it removes the model from the node’s cache and offloads the ASR model, freeing resources at the cost of loading the model again on a later run. With it off, a matching model configuration can be reused.
dtype
Selects the model’s numerical precision. The options are auto, bf16, and fp16; the default is auto. The node tooltip says automatic selection uses native bf16, or fp16 on older GPUs. This choice is passed to the model loader and forms part of the cached model configuration; changing it can require a new load.
device
Selects where inference runs. The options are the devices available in your environment: cuda when CUDA is available, mps when Apple MPS is available, and cpu. The default is the first available option in that order. This setting affects where the model is loaded and is part of its cache configuration.
enable_asr
Controls automatic transcription of the reference recording with SenseVoiceSmall ASR. This boolean defaults to False (Off); True is labeled ASR. ASR runs only when prompt_text is blank, requires the funasr package, and may download a model of approximately 400 MB on first use. A successful transcript enables transcript-guided cloning. If transcription fails or returns nothing, the node proceeds without a transcript, which is valid for VoxCPM2 controllable cloning but not V1 cloning.
retry_max_attempts
Sets the maximum number of automatic retry attempts for a generation detected as silence or babbling. The default is 3, the minimum is 0, the maximum is 10, and the step is 1. Setting 0 disables this retry mechanism. Higher values allow more attempts to recover from a bad generation but can make a run take longer.
retry_threshold
Sets the audio-to-text length-ratio threshold used to identify a potentially bad generation for retrying. The default is 6.0, the minimum is 2.0, the maximum is 20.0, and the step is 0.1. It is passed to the model’s bad-generation retry mechanism; it does not set a duration or an audio-quality score. It has no practical retry effect when retry_max_attempts is 0.
torch_compile
Controls the optional torch.compile optimization. This boolean defaults to False (Standard); True is labeled Torch Compile. The node tooltip notes that the first run compiles kernels and later runs may be faster. Because this setting is part of the model cache configuration, changing it can require the model to load again.
VoxCPM Voice Clone Output Parameters:
Cloned Audio
The sole output is an AUDIO value containing the generated speech and its sample rate. Its waveform is the model’s generated audio, optionally passed through loudness normalization when denoising is enabled and that normalization succeeds. Connect it to a compatible audio preview, playback, or saving node to hear or export the result. The node also requests an audio preview in its own interface.
VoxCPM Voice Clone Usage Tips:
- For the simplest VoxCPM2 workflow, connect a suitable reference recording, enter the new words in
text, and leaveprompt_textblank. Addvoice_descriptionwhen you want to try a style instruction in this reference-only mode. - For transcript-guided cloning, put the words spoken in the reference recording in
prompt_textand the words you want generated intext. With a V1 model, a transcript is required; you can enter it yourself or enable ASR to attempt to obtain it. - If you already know the reference transcript, enter it directly even when ASR is enabled. The node will use your supplied
prompt_textand skip automatic transcription. - Start with the defaults of
cfg_valueat2.0andinference_timestepsat10. Increase the step count when you want to try a quality improvement and can allow a slower run; adjust guidance gradually to compare prompt adherence with natural variation. - If speech stops before your requested text is complete, check whether
max_tokensis too low. For repeated silence or babbling, keep retries enabled and adjustretry_max_attemptsorretry_thresholdcautiously. - Use
force_offloadwhen freeing model memory after each successful generation matters more than quick reuse. For repeated runs with the same settings, leave it off so the cached configuration can be reused.
VoxCPM Voice Clone Common Errors and Solutions:
Reference audio is required for voice cloning.
- Explanation: No audio reached the required
reference_audioinput. - Solution: Connect an
AUDIOoutput containing your voice reference and run the node again.
Reference audio is `{duration}`s — max allowed is `{maximum}`s. Trim the audio and try again.
- Explanation: The reference recording exceeds the node’s configured duration limit. The displayed numbers depend on the recording and configuration; the supplied source does not state the limit.
- Solution: Trim the reference audio below the maximum shown in the error, then reconnect it.
Model '`{model_name}`' does not support controllable cloning (no transcript). Provide prompt_text or enable ASR for ultimate cloning, or use a VoxCPM2 model.
- Explanation: A V1 model was selected, but no usable reference transcript is available. This can also happen when ASR returns an empty transcript or fails.
- Solution: Enter the reference recording’s transcript in
prompt_text, get a successful ASR transcript, or select a VoxCPM2 model for reference-only cloning.
LoRA file not found: {lora_name}
- Explanation: The selected LoRA name could not be resolved to a file in the configured LoRA location.
- Solution: Choose an available checkpoint from
lora_name, check that the file is in the configuredmodels/loraslocation, or selectNone.
Failed to load LoRA '`{lora_name}`': {error}
- Explanation: The LoRA file was found, but the model could not load or enable it. The underlying error supplies the specific cause.
- Solution: Check that the checkpoint is intended for the selected model and inspect the accompanying error. Try
Noneto confirm whether generation works without that LoRA.
Failed to load model '`{model_name}`'.
- Explanation: The requested model was not available after the node attempted to load it.
- Solution: Verify that the selected model is installed and available to the VoxCPM extension, then try another listed model or inspect the model-loading logs.
ASR failed: `{error}`. Proceeding without transcript. or ASR returned empty transcript. Proceeding without transcript.
- Explanation: Automatic transcription did not produce usable
prompt_text. These are warnings, but a V1 model will subsequently reject cloning without a transcript. - Solution: Enter the transcript manually, check that the optional
funasrdependency and ASR model are available, or use VoxCPM2 reference-only cloning.
Loudness normalization failed: `{error}`. Using raw output.
- Explanation: With denoising enabled, the attempt to normalize generated audio failed. This is a warning; the node retains the raw generated audio.
- Solution: Listen to the result before deciding whether action is needed. If consistent loudness is important, inspect the underlying error or normalize the audio in a later audio-processing step.
VoxCPM2 clone error: {error}
- Explanation: Generation raised an exception, and the node logged it with this prefix. The text after the colon is the important detail; the prefix alone does not identify one specific failure.
- Solution: Read the full error, confirm the reference audio, model, and optional dependencies are usable, and retry with optional features such as LoRA, denoising, and compilation disabled to narrow down the cause.
