OpenBMB VoxCPM2 — tokenizer-free 다국어 TTS와 음성 설계·복제

VoxCPM2는 OpenBMB가 공개한 tokenizer-free 다국어 text-to-speech 모델이다.[4] 저장소는 자연어 기반 voice design, 참조 오디오 기반 controllable voice cloning, prompt 오디오·전사 기반 continuation cloning, streaming API, LoRA/SFT fine-tuning, CLI·WebUI·서빙 경로를 하나의 Python 패키지로 제공한다.[4][5]

한눈에 보기

저장소: OpenBMB/VoxCPM, Python, Apache-2.0, 기본 브랜치 main.[1]
고정 snapshot: ee8161e9e1b7b082cb5721a3a9980da4204401e6 (2026-08-12T13:46:20Z, update readme, add MiniCPM Wiki link).[2]
고정 tree: commit-pinned recursive tree는 97 entries(75 files, 22 directories)다.[3]
VoxCPM2 모델: README 비교표는 2B backbone, 48kHz 출력, 6.25Hz LM token rate, 30개 언어, 약 8GB VRAM, RTX 4090 표준 PyTorch RTF 약 0.30을 제시한다.[4] 이 수치들은 저장소가 보고한 값이며 이번 조사에서 독립적으로 재측정하지 않았다.[4]
핵심 설계: AudioVAE V2 latent 공간에서 LocEnc → TSLM → RALM → LocDiT를 거치는 diffusion-autoregressive 파이프라인이다.[4][7]
검증 경계: 소스 compile, import, CLI help, focused tests는 실행했지만 2B 모델 weight 다운로드·GPU 추론·음성 생성·voice cloning·성능 벤치마크는 실행하지 않았다.[unverified]

무엇을 해결하는가

VoxCPM2는 고정된 음성 토큰화 파이프라인에만 의존하지 않고, 텍스트 의미·참조 음성·음성 스타일을 latent acoustic representation에서 함께 모델링하려는 TTS다.[4][7] 저장소 README는 이를 다국어 speech generation, creative voice design, true-to-life cloning을 한 모델 계열에 묶는 방향으로 설명한다.[4]

사용자 관점의 입력 모드는 네 가지다.[4][6]

기본 TTS: 텍스트만 넣어 음성을 생성한다.[4][6]
Voice design: 텍스트 앞에 (A young woman, gentle and sweet voice) 같은 자연어 음성 설명을 붙여 참조 음성 없이 목소리를 설계한다.[4][10]
Controllable cloning: reference_wav_path로 화자 음색을 참고하고, 텍스트의 제어 지시나 control 옵션으로 속도·감정·스타일을 조정한다.[4][6]
Ultimate cloning / continuation: prompt_wav_path와 정확한 prompt_text를 함께 주어 참조 구간의 vocal nuance를 이어 생성한다. README 예시는 더 높은 유사도를 위해 같은 오디오를 reference_wav_path에도 전달할 수 있다고 설명한다.[4][6]

저장소는 controllable voice design과 cloning 결과가 실행마다 달라질 수 있으므로 1~3회 재생성을 시도할 수 있다고 명시한다.[4] 따라서 “자연어 제어가 항상 동일한 목소리와 스타일을 보장한다”는 제품 해석은 피해야 한다.[4]

모델·음성 합성 파이프라인

1. AudioVAE V2가 오디오를 latent로 바꾼다

AudioVAEConfigV2의 기본값은 16,000Hz encoder input, 48,000Hz decoder output, latent dimension 64다.[8] encoder rate는 [2, 5, 8, 8], decoder rate는 [8, 6, 5, 2, 2, 2]이며, 구현은 causal encoder/decoder와 streaming decoder context를 제공한다.[8]

모델 내부에서 sample_rate는 AudioVAE 입력 샘플레이트, out_sample_rate는 생성 waveform의 출력 샘플레이트로 분리된다. VoxCPM2 모델은 후자를 self.sample_rate로 노출하므로 예제의 sf.write(..., model.tts_model.sample_rate)가 48kHz output을 사용하게 된다.[7][8]

2. LocEnc가 음성 feature를 인코딩한다

VoxCPM2Model은 AudioVAE가 만든 acoustic feature를 Local Encoder에 넣고, enc_to_lm_proj로 MiniCPM language-model hidden size에 투영한다.[7] 이 경로는 참조 오디오와 생성 중인 음성 feature를 텍스트 토큰과 같은 결합 표현으로 연결하는 역할을 한다.[7]

3. TSLM과 RALM이 의미·잔차 음향을 나눈다

구현에는 base_lm과 residual_lm 두 MiniCPM 계열 모듈이 있다.[7] base LM은 텍스트·오디오 결합 표현을 처리하고, residual LM은 fusion_concat_proj를 거친 표현에서 잔차 acoustic 정보를 계산한 뒤 두 hidden state를 LocDiT 입력으로 보낸다.[7]

이 구조는 “텍스트를 먼저 음성 토큰으로 직렬 변환한 뒤 vocoder가 재생한다”는 단순한 설명보다, semantic LM과 residual acoustic LM이 같은 latent 시퀀스에서 상호작용하는 diffusion-autoregressive 설계로 읽는 편이 정확하다.[7] 이는 코드 구조를 바탕으로 한 해석이며, 논문 수준의 독립적인 ablation 결론은 아니다.[7]

4. LocDiT가 conditional flow matching으로 latent를 복원한다

UnifiedCFM.forward()는 noise에서 시작해 n_timesteps개의 Euler step을 거치며 acoustic latent를 복원한다.[9] CFG 경로에서는 positive/negative estimator 출력을 분리하고, optimized_scale과 cfg_value를 사용해 guidance를 적용한다.[9]

복원된 latent는 AudioVAE decoder로 waveform이 된다. AudioVAE에는 streaming_decode() context가 있어 causal convolution state를 유지하면서 latent chunk를 순차적으로 decode할 수 있고, 상위 모델은 이를 generate_streaming() 경로에 연결한다.[8][7]

5. Prompt·reference 음성은 분리된 conditioning 경로다

core wrapper의 _generate() 시그니처는 prompt_wav_path·prompt_text와 reference_wav_path를 별도 인자로 둔다.[6] 전자는 오디오 continuation에, 후자는 구조적으로 분리된 reference audio 기반 voice cloning에 사용되며, 둘을 함께 전달할 수 있다.[6]

이 분리는 “참조 음성의 음색”과 “이어 말할 음성 구간의 내용·운율”을 하나의 prompt로 뭉개지 않고 조절하려는 API 설계로 볼 수 있다.[6] 실제 화자 유사도와 prosody 보존 정도는 모델 weight·입력 오디오·sampling 설정에 좌우되며 이번 조사에서 청취 평가하지 않았다.[6][4]

API·CLI·서빙

Python API

from voxcpm import VoxCPM
import soundfile as sf
 
model = VoxCPM.from_pretrained(
    "openbmb/VoxCPM2",
    load_denoiser=False,
)
 
wav = model.generate(
    text="VoxCPM2 is a multilingual speech synthesis test.",
    cfg_value=2.0,
    inference_timesteps=10,
    seed=42,
)
sf.write("demo.wav", wav, model.tts_model.sample_rate)

VoxCPM.from_pretrained()는 로컬 디렉터리면 그대로 사용하고, 경로가 아니면 Hugging Face snapshot_download()를 호출한다.[6] 기본 model id는 openbmb/VoxCPM2이며 cache_dir, local_files_only, device, optimize, LoRA path, denoiser loading을 설정할 수 있다.[6]

generate()는 완성 waveform을 반환하고 generate_streaming()은 waveform chunk generator를 반환한다.[6] 모델은 cfg_value, inference_timesteps, seed, max_len, normalize, prompt/reference 오디오 및 optional denoise를 입력으로 받는다.[6]

CLI

패키지 entry point는 voxcpm = voxcpm.cli:main이고 CLI subcommand는 design, clone, batch, validate다.[5][10]

# 참조 음성 없이 voice design
voxcpm design \
  --text "A multilingual TTS demonstration." \
  --control "Young female voice, warm and gentle" \
  --seed 42 \
  --output out.wav
 
# 참조 음성 기반 cloning
voxcpm clone \
  --text "This is a voice cloning demo." \
  --reference-audio path/to/voice.wav \
  --output out.wav
 
# prompt audio + transcript를 이용한 continuation cloning
voxcpm clone \
  --text "This is a continuation demo." \
  --prompt-audio path/to/voice.wav \
  --prompt-text "Reference transcript" \
  --reference-audio path/to/voice.wav \
  --output out.wav
 
# JSONL fine-tuning manifest 사전 검증
voxcpm validate --manifest train.jsonl

CLI에는 --device auto|cpu|mps|cuda|cuda:N, --no-optimize, --no-denoiser, --local-files-only, LoRA 옵션, stable-ts 기반 word/character timestamp 옵션이 있다.[10] 이번 환경에서 voxcpm --help는 정상 출력했지만 모델을 실제로 로드하지는 않았다.[10]

README는 python app.py --port 8808 Web Demo와, Nano-vLLM·vLLM-Omni·llama.cpp-omni 기반의 고처리량·OpenAI 호환·온디바이스 경로도 소개한다.[4] 이 외부 프로젝트들은 VoxCPM 저장소가 직접 유지하는 동일 runtime이라고 간주하지 않았고, 이번 ingest에서 별도 checkout·서빙 실행도 하지 않았다.[4]

Fine-tuning과 보안 관련 코드

VoxCPM은 full fine-tuning(SFT)과 LoRA fine-tuning을 모두 제공하며, 저장소 예제는 LoRA를 parameter-efficient 방식으로 권장한다. conf/voxcpm_v2/voxcpm_finetune_lora.yaml은 LM·DiT LoRA 활성화, rank 32, alpha 32, dropout 0.0의 예시를 제시한다.[4][14]

LoRA checkpoint 로딩 테스트는 lora_config.json과 weight 파일을 읽고, checkpoint key가 모델 구조와 맞지 않을 때의 처리 경로를 검증한다.[14] test_torch_load_safety.py는 저장소와 script 전체의 torch.load 호출에 weights_only=True가 지정되는지 정적으로 검사하고, 악성 pickle payload가 실행되지 않아야 한다는 행동 테스트를 포함한다.[13][14]

이 안전성 검사는 checkpoint loading 경로의 pickle 실행 위험을 줄이기 위한 회귀 방어다.[13] 그러나 이것만으로 임의의 모델 weight, Hugging Face repository, ModelScope denoiser, 사용자 제공 WAV의 전체 공급망 안전성을 보증하는 것은 아니다.[13]

의존성·실행 조건

pyproject.toml은 Python >=3.10, PyTorch·torchaudio >=2.5.0, transformers, torchcodec, einops, gradio, modelscope, datasets, huggingface-hub, soundfile, librosa, funasr, safetensors 등을 요구한다.[5] 개발 의존성은 pytest·pytest-cov·black·flake8·pre-commit이고, timestamp extra는 stable-ts>=2.19.1이다.[5]

README의 Quick Start는 Python 3.10 이상, Python 3.13 미만, PyTorch 2.5 이상, CUDA 12 이상을 권장한다. 반면 소스의 device resolver는 CPU·MPS fallback을 노출하므로, CUDA 요구사항과 실제 CPU/MPS 호환성은 모델 weight·dtype·성능 목표별로 별도 확인해야 한다.[4][6][7]

기본 constructor는 optimize=True일 때 CUDA에서 torch.compile과 Triton 경로를 시도하고 실패하면 경고를 출력하며 compile을 비활성화한다.[7] 따라서 디버깅이나 CPU/MPS 실행에서는 optimize=False 또는 CLI --no-optimize가 중요한 재현성 옵션이다.[7]

저장소가 보고한 성능과 해석 경계

README의 모델 표는 VoxCPM2를 30-language, 48kHz, 약 8GB VRAM 모델로 제시하고 RTX 4090에서 표준 PyTorch RTF 약 0.30, Nano-vLLM에서 약 0.13을 보고한다.[4]

Seed-TTS-eval 표에서 VoxCPM2 행은 test-EN WER 1.84/SIM 75.3, test-ZH CER 0.97/SIM 79.5, test-Hard CER 8.13/SIM 75.3으로 표시된다.[4] CV3-eval 표는 zh 3.65, en 5.00, hard-zh 8.55, hard-en 8.48 등을 제시한다.[4]

README는 30개 언어 × 500 samples의 내부 ASR benchmark도 제시하며 평균 VoxCPM2 CER/WER를 1.68%로 기록하고, InstructTTSEval에서는 중국어 APS 85.2·DSD 71.5·RP 60.8, 영어 APS 84.2·DSD 83.2·RP 71.4를 보고한다.[4]

위 숫자는 저장소 README에 실린 source-reported benchmark snapshot이다.[4] 평가 데이터·오디오·ASR API 호출·hardware/precision 설정·실험 script를 이 ingest에서 재현하지 않았으므로, 독립 benchmark 결과나 현재 최신 성능으로 승격하지 않는다.[4]

실제 검증 결과

성공한 bounded checks

Python 3.11 격리 환경(/tmp/vox-cpm-venv)을 만들고 pytest·NumPy·PyTorch 및 import/테스트에 필요한 일부 패키지를 설치했다.[unverified] 전체 pyproject.toml dependency graph를 완전히 설치한 것은 아니다.[unverified]
python -m compileall -q src scripts app.py lora_ft_webui.py: exit 0.[unverified]
PYTHONPATH=src python -m voxcpm.cli --help: exit 0.[unverified] design, clone, batch, validate와 device/LoRA/timestamp 옵션이 출력됐다.[unverified]
PYTHONPATH=src python -c 'import voxcpm; from voxcpm import VoxCPM': exit 0.[unverified]
scripts/test_pick_runtime_dtype.py: 22/22 passed.[unverified]
tests/test_torch_load_safety.py, test_lora_checkpoint_loading.py, test_model_utils.py, test_timestamps.py, test_cli.py focused run: 41 passed.[unverified]

테스트 파일 자체가 CLI·manifest 경로를 어떤 범위에서 검사하는지는 commit-pinned test sources에서 확인했다.[11][12] checkpoint safety·LoRA 경로를 어떤 범위에서 검사하는지도 별도 test sources에서 확인했다.[13][14]

미실행으로 남긴 항목

전체 pytest -q tests/는 optional argbind·datasets를 보완 설치한 뒤 56 passed였다.[unverified]
CUDA는 torch.cuda.is_available() == False였다.[unverified] CPU에서 2B 모델을 실제로 로드·생성하는 실행은 시도하지 않았다.[unverified]
Hugging Face openbmb/VoxCPM2 snapshot, ModelScope ZipEnhancer, reference WAV, model weight, audio output을 다운로드하거나 생성하지 않았다.[unverified]
voxcpm design, clone, batch, Web Demo, Nano-vLLM, vLLM-Omni, llama.cpp-omni, fine-tuning, timestamp alignment의 end-to-end 실행은 미실행이다.[unverified]
README의 RTF·VRAM·WER/CER/SIM·30-language ASR·voice cloning similarity 주장은 이번 환경에서 재현하지 않았다.[unverified]

실무적 위치와 주의점

VoxCPM2의 가장 뚜렷한 위치는 다국어·고품질 TTS의 단일 API라기보다, semantic LM·residual acoustic LM·flow-matching decoder·AudioVAE를 결합해 voice design과 cloning 제어까지 한 모델 안에서 시도하는 연구 지향 runtime이다. 48kHz 출력과 isolated reference path는 Pocket TTS처럼 CPU edge에 초점을 둔 모델과 다른 선택점이며, 약 8GB VRAM·CUDA 12·2B backbone은 로컬 GPU 운영 비용을 함께 고려하게 한다.[4][7][8]

음성 복제는 본인 음성 또는 명시적 허가를 받은 음성에만 사용해야 한다. 저장소도 impersonation·fraud·disinformation을 금지하고 AI-generated content를 명확히 표시하라고 권고한다.[4]

활용 시 권장 순서

먼저 --no-optimize --no-denoiser --device cpu로 작은 manifest/CLI 경로와 파일 쓰기를 확인한다.[6][10]
그다음 합법적으로 확보한 짧은 reference WAV로 기본 cloning과 prompt continuation을 분리해 비교한다.[6]
동일 seed·cfg·inference timesteps로 재현성을 확인하고, controllable voice design은 여러 샘플을 청취해 변동성을 기록한다.[4][6]
운영 배포가 필요하면 표준 PyTorch 단일 요청, Nano-vLLM, vLLM-Omni, C++ backend를 latency·VRAM·동시성·라이선스 기준으로 별도 벤치마크한다.[4]
음성 샘플의 동의 기록·보존 기간·AI 음성 표시 정책을 inference pipeline과 분리하지 않는다.[4]

고정 snapshot과 provenance

공식 저장소: OpenBMB/VoxCPM[1]
고정 commit: ee8161e9e1b7b082cb5721a3a9980da4204401e6[2]
README pinned raw: README.md[4]
선택 파일과 raw body hash: raw source: github-openbmb-voxcpm[unverified]
raw body SHA-256: 4955e1c05ad6a37ceb32a6390fa5da7e18dd875c0ab724789e24ca3372655a0d[unverified]
고정 snapshot의 source code·모델 weight·reference audio는 위키에 복제하지 않았으며, 원문과 실행 경계를 분리해 기록했다.[unverified]

Sources

description	AudioVAE latent 공간에서 MiniCPM·LocEnc·TSLM·RALM·LocDiT를 결합해 48kHz 음성을 생성하는 OpenBMB의 다국어 TTS 모델 저장소.
tags	multimedia, tts, voice-ai, python, open-source
aliases	VoxCPM, VoxCPM2, OpenBMB VoxCPM

LLM Wiki

탐색기