OpenBMB/VoxCPM · error · ValueError

reference_wav_path is only supported with VoxCPM2 models

Error message

reference_wav_path is only supported with VoxCPM2 models

What it means

reference_wav_path (a VoxCPM2 feature) is rejected when the loaded model is a v1 VoxCPMModel, determined via isinstance check in _generate.

Source

Thrown at src/voxcpm/core.py:244

            otherwise yields a single array containing the final audio.
        """
        if not isinstance(text, str) or not text.strip():
            raise ValueError("target text must be a non-empty string")

        if prompt_wav_path is not None:
            if not os.path.exists(prompt_wav_path):
                raise FileNotFoundError(f"prompt_wav_path does not exist: {prompt_wav_path}")

        if reference_wav_path is not None:
            if not os.path.exists(reference_wav_path):
                raise FileNotFoundError(f"reference_wav_path does not exist: {reference_wav_path}")

        if (prompt_wav_path is None) != (prompt_text is None):
            raise ValueError("prompt_wav_path and prompt_text must both be provided or both be None")

        is_v2 = isinstance(self.tts_model, VoxCPM2Model)
        if reference_wav_path is not None and not is_v2:
            raise ValueError("reference_wav_path is only supported with VoxCPM2 models")

        text = text.replace("\n", " ")
        text = re.sub(r"\s+", " ", text)
        temp_files = []

        try:
            actual_prompt_path = prompt_wav_path
            actual_ref_path = reference_wav_path

            if denoise and self.denoiser is not None:
                if prompt_wav_path is not None:
                    with tempfile.NamedTemporaryFile(delete=False, suffix=".wav") as tmp:
                        temp_files.append(tmp.name)
                    self.denoiser.enhance(prompt_wav_path, output_path=temp_files[-1])
                    actual_prompt_path = temp_files[-1]
                if reference_wav_path is not None:
                    with tempfile.NamedTemporaryFile(delete=False, suffix=".wav") as tmp:
                        temp_files.append(tmp.name)

View on GitHub (pinned to f5a1c6a6b9)

Solutions

1. Use prompt_wav_path + prompt_text (v1 voice cloning) instead of reference_wav_path
2. Or load a VoxCPM2 model (arch='v2') to use reference_wav_path
3. Check which arch you actually loaded before choosing cloning API

Example fix

# before
model = VoxCPM(arch="v1", ...)
model.generate(text, reference_wav_path="ref.wav")
# after
model = VoxCPM(arch="v2", ...)
model.generate(text, reference_wav_path="ref.wav")

from voxcpm.model.voxcpm import VoxCPM2Model
if reference_wav_path and not isinstance(model.tts_model, VoxCPM2Model):
    raise ValueError("reference_wav_path requires a v2 model")

def supports_reference(model) -> bool:
    from voxcpm.model.voxcpm import VoxCPM2Model
    return isinstance(model.tts_model, VoxCPM2Model)

When it happens

Trigger: Loading arch='v1' (or a v1 checkpoint) then calling generate with reference_wav_path set.

Common situations: Copying v2 example code while running a v1 model, or upgrading code but not the model checkpoint.

Related errors

• prompt_wav_path does not exist: {prompt_wav_path}
• reference_wav_path does not exist: {reference_wav_path}
• prompt_wav_path and prompt_text must both be provided or bot

AI-assisted analysis of OpenBMB/VoxCPM@f5a1c6a6b9 (2026-08-27). Data as JSON: /api/errors/821a7113514183ab. Report an issue: GitHub.