{"record":{"id":"821a7113514183ab","repo":"OpenBMB/VoxCPM","slug":"reference-wav-path-is-only-supported-with-voxcpm2","errorCode":null,"errorMessage":"reference_wav_path is only supported with VoxCPM2 models","messagePattern":"reference_wav_path is only supported with VoxCPM2 models","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"src/voxcpm/core.py","lineNumber":244,"sourceCode":"            otherwise yields a single array containing the final audio.\n        \"\"\"\n        if not isinstance(text, str) or not text.strip():\n            raise ValueError(\"target text must be a non-empty string\")\n\n        if prompt_wav_path is not None:\n            if not os.path.exists(prompt_wav_path):\n                raise FileNotFoundError(f\"prompt_wav_path does not exist: {prompt_wav_path}\")\n\n        if reference_wav_path is not None:\n            if not os.path.exists(reference_wav_path):\n                raise FileNotFoundError(f\"reference_wav_path does not exist: {reference_wav_path}\")\n\n        if (prompt_wav_path is None) != (prompt_text is None):\n            raise ValueError(\"prompt_wav_path and prompt_text must both be provided or both be None\")\n\n        is_v2 = isinstance(self.tts_model, VoxCPM2Model)\n        if reference_wav_path is not None and not is_v2:\n            raise ValueError(\"reference_wav_path is only supported with VoxCPM2 models\")\n\n        text = text.replace(\"\\n\", \" \")\n        text = re.sub(r\"\\s+\", \" \", text)\n        temp_files = []\n\n        try:\n            actual_prompt_path = prompt_wav_path\n            actual_ref_path = reference_wav_path\n\n            if denoise and self.denoiser is not None:\n                if prompt_wav_path is not None:\n                    with tempfile.NamedTemporaryFile(delete=False, suffix=\".wav\") as tmp:\n                        temp_files.append(tmp.name)\n                    self.denoiser.enhance(prompt_wav_path, output_path=temp_files[-1])\n                    actual_prompt_path = temp_files[-1]\n                if reference_wav_path is not None:\n                    with tempfile.NamedTemporaryFile(delete=False, suffix=\".wav\") as tmp:\n                        temp_files.append(tmp.name)","sourceCodeStart":226,"sourceCodeEnd":262,"githubUrl":"https://github.com/OpenBMB/VoxCPM/blob/f5a1c6a6b901bc732e20f0d59a369f6829ad717a/src/voxcpm/core.py#L226-L262","documentation":"reference_wav_path (a VoxCPM2 feature) is rejected when the loaded model is a v1 VoxCPMModel, determined via isinstance check in _generate.","triggerScenarios":"Loading arch='v1' (or a v1 checkpoint) then calling generate with reference_wav_path set.","commonSituations":"Copying v2 example code while running a v1 model, or upgrading code but not the model checkpoint.","solutions":["Use prompt_wav_path + prompt_text (v1 voice cloning) instead of reference_wav_path","Or load a VoxCPM2 model (arch='v2') to use reference_wav_path","Check which arch you actually loaded before choosing cloning API"],"exampleFix":"# before\nmodel = VoxCPM(arch=\"v1\", ...)\nmodel.generate(text, reference_wav_path=\"ref.wav\")\n# after\nmodel = VoxCPM(arch=\"v2\", ...)\nmodel.generate(text, reference_wav_path=\"ref.wav\")","handlingStrategy":"type-guard","validationCode":"from voxcpm.model.voxcpm import VoxCPM2Model\nif reference_wav_path and not isinstance(model.tts_model, VoxCPM2Model):\n    raise ValueError(\"reference_wav_path requires a v2 model\")","typeGuard":"def supports_reference(model) -> bool:\n    from voxcpm.model.voxcpm import VoxCPM2Model\n    return isinstance(model.tts_model, VoxCPM2Model)","tryCatchPattern":null,"preventionTips":["Branch your cloning code on model version","Keep model arch in app config next to feature flags"],"tags":["version-mismatch","voice-cloning","feature-support"],"backgroundTag":"unsupported-feature-for-version","analyzedSha":"f5a1c6a6b901bc732e20f0d59a369f6829ad717a","analyzedAt":"2026-08-27T05:54:30.617Z","schemaVersion":2},"datasetVersion":"2026-08-27T08:17:20.692Z"}