VoxCPM2 사용법: 로컬 오픈소스 TTS·보이스 클로닝 완벽 가이드 (2026)

"내 목소리를 5초만 녹음해서 다른 언어로 말하게 할 수 있다고?"

📌 핵심 3줄 요약

• OpenBMB가 공개한 VoxCPM2는 토크나이저 없이 48kHz 음성을 만들어내는 오픈소스 TTS다. 공식 README 기준 30개 언어를 지원한다.
• 설치는 pip install voxcpm 한 줄, 추론은 VoxCPM.from_pretrained() 한 번으로 끝난다.
• 참조 음성 WAV 한 개만 있으면 화자 학습 없이 5초 샘플 보이스 클로닝이 가능하다.

1. VoxCPM2가 뭐가 다른가

기존 오픈소스 TTS는 대부분 텍스트를 음소나 BPE 토큰으로 잘라서 학습한다. VoxCPM2는 이 단계를 통째로 들어내고 텍스트에서 바로 오디오 잠재 표현으로 가는 tokenizer-free 디퓨전 자기회귀 구조를 쓴다. AudioVAE V2 잠재 공간 위에서 LocEnc → TSLM → RALM → LocDiT 네 단계로 흐른다.

결과적으로 16kHz 합성에 머물던 이전 세대와 달리 네이티브 48kHz로 뽑히고, 발음 사전을 만들기 어려운 소수 언어도 비교적 자연스럽게 처리된다. 한국어·영어·중국어·일본어·아랍어 등 30개 언어와 9개 중국 방언이 공식 지원 목록에 들어 있다.

💡 핵심 한 줄

"토크나이저가 없다"는 말은 별도 발음 사전을 안 만든다는 뜻이다. 새 언어를 붙일 때 G2P 파이프라인을 다시 짤 필요가 없어 다국어 확장에 유리하다.

2. 설치와 환경 준비

요구 사항이 의외로 까다롭지 않다. 공식 README 기준 Python 3.10 이상 3.13 미만, PyTorch 2.5.0 이상, CUDA 12.0 이상이면 된다. VRAM은 공식 안내에서 약 8GB 정도이므로 RTX 3060 12GB나 4070 정도면 여유 있게 돌아간다.

항목	권장값
Python	3.10 ~ 3.12
PyTorch	2.5.0 이상
CUDA	12.0 이상
VRAM	약 8GB

가상환경을 만든 뒤 패키지 한 줄과 오디오 입출력용 soundfile까지 같이 깔면 끝이다.

python -m venv .venv
.venv\Scripts\activate
pip install voxcpm soundfile

첫 실행 시 Hugging Face Hub에서 가중치를 자동으로 받기 때문에 대역폭과 디스크 여유가 있는 시간대에 시작하는 편이 낫다.

3. 첫 합성 5분 안에 끝내기

아래 스크립트를 그대로 저장해 실행하면 한국어 한 문장이 demo.wav로 떨어진다. 가중치를 처음 받는 동안만 시간이 좀 걸리고, 두 번째 실행부터는 캐시를 쓴다.

tts_hello.py · Python

from voxcpm import VoxCPM
import soundfile as sf

model = VoxCPM.from_pretrained("openbmb/VoxCPM2", load_denoiser=False)

wav = model.generate(
    text="안녕하세요. 보이스 합성 테스트입니다.",
    cfg_value=2.0,
    inference_timesteps=10,
)

sf.write("demo.wav", wav, model.tts_model.sample_rate)
print("saved demo.wav")

cfg_value는 텍스트 충실도, inference_timesteps는 품질과 속도 trade-off를 조정한다. 처음에는 기본값 그대로 두고 결과부터 들어보는 편이 빠르다.

4. 5초 샘플로 내 목소리 복제

참조 화자 음성 한 개만 있으면 추가 파인튜닝 없이 그 목소리로 합성이 가능하다. prompt_wav_path에 깨끗한 WAV를 넣고, prompt_text에 그 오디오의 정확한 전사를 적어주면 된다.

voice_clone.py · Python

wav = model.generate(
    text="새로운 문장을 같은 목소리로 만들어줘.",
    prompt_wav_path="ref_voice.wav",
    prompt_text="여기에 ref_voice.wav의 실제 발화 내용을 적는다.",
    cfg_value=2.0,
    inference_timesteps=10,
    denoise=True,
)
sf.write("clone.wav", wav, model.tts_model.sample_rate)

참조 음성은 배경 잡음·BGM 없이 5초 안팎이면 충분하다. 마이크가 좋지 않다면 denoise=True를 켜두는 편이 결과가 안정적이다.

5. 자주 막히는 지점과 품질 튜닝

처음 돌릴 때 가장 흔한 세 가지 함정만 짚어둔다.

• CUDA out of memory — VRAM이 빠듯하면 load_denoiser=False로 디노이저를 빼고 inference_timesteps를 5~7로 낮춘다.
• 발음이 깨질 때 — cfg_value를 2.5~3.0으로 올리면 텍스트 충실도가 올라간다. 너무 높이면 운율이 어색해진다.
• 속도가 너무 느릴 때 — README에 따르면 RTX 4090 기준 RTF 약 0.30, Nano-vLLM 가속 시 0.13까지 떨어진다. 실시간 응용이라면 가속 옵션 검토.

⚠️ 흔한 실수

prompt_text를 대충 채우면 클로닝 품질이 급격히 떨어진다. 참조 오디오의 실제 발화 내용을 한 글자도 다르지 않게 적어야 한다.

⚠️ 단점과 주의할 점

• 모델은 Apache-2.0이지만 타인 목소리 클로닝은 법적·윤리적으로 별개 문제다. 본인 동의 없는 합성은 금지.
• 한국어 음운 처리는 영어·중국어보다 학습 데이터가 적은 편이라 외래어·고유명사에서 발음이 흔들릴 수 있다.
• GPU 없이 CPU만 쓸 경우 실용적인 속도를 기대하기 어렵다. 최소 8GB급 NVIDIA GPU가 권장된다.

🚀 지금 바로 할 일

1. 가상환경에 pip install voxcpm soundfile로 패키지를 설치한다.
2. 위 tts_hello.py를 그대로 실행해 한국어 한 문장을 합성해본다.
3. 본인 목소리 5초를 녹음한 뒤 prompt_wav_path에 넣어 클로닝 결과를 직접 확인한다.

💬 의견

오픈소스 TTS를 실무에 써본 적이 있다면 어떤 모델과 비교했을 때 VoxCPM2의 한국어 품질이 어떻게 느껴지는지 댓글로 공유 부탁드립니다.

✅ 핵심 정리

• VoxCPM2는 토크나이저 없이 48kHz 음성을 만드는 30개 언어 오픈소스 TTS다.
• 설치는 pip 한 줄, 첫 합성은 코드 10줄로 끝난다.
• 참조 WAV 한 개로 보이스 클로닝이 되지만, 본인 동의 없는 사용은 안 된다.
• VRAM 8GB·CUDA 12 이상이 실용 권장선이다.

참고 자료

• OpenBMB/VoxCPM 공식 GitHub README
• Hugging Face — openbmb/VoxCPM2 모델 카드
• Hugging Face — openbmb/VoxCPM-0.5B 초기 버전 카드
• PyPI — voxcpm 패키지

---

작성자: AI·개발 도구를 직접 설치하고 코드 단위로 검증한 뒤 글로 정리하는 작업을 이어오고 있다. 공식 문서와 1차 소스를 우선 확인하고, 재현 가능한 명령어와 함정만 추려서 옮긴다.