VoxCPM 텍스트 음성 변환은(는) 무엇을 하나요?
OpenBMB의 VoxCPM을 사용하여 중국어/영어/다국어 텍스트를 음성으로 합성합니다. 두 가지 모델 계층, 세 가지 입력 모드, 30개 언어, 9개 중국어 방언을 지원합니다. Apache-2.0 라이선스.
2026-07-04 검증 완료: PyPI에 voxcpm 2.0.3 게시, 의존성 그래프 정상 확인 (torch ≥ 2.5, transformers ≥ 4.36, gradio 6.x). PyPI 접근 가능. 모델 가중치는 Hugging Face에서 호스팅 (openbmb/VoxCPM2, openbmb/VoxCPM-0.5B).
이 환경 (QoderWork 샌드박스)에는 GPU가 없으며 huggingface.co에 직접 접근할 수 없습니다 — 따라서 여기서는 오디오 생성을 수행하지 않습니다. 실제 합성하려면 CUDA / Apple Silicon / HF 미러가 있는 머신에 배포하세요.
전제 조건
| 구성 요소 | 요구 사항 |
|---|---|
| Python | ≥ 3.10, < 3.13 (공식 테스트 완료) |
| PyTorch | ≥ 2.5.0 |
| CUDA | ≥ 12.0 (권장); MPS 또는 CPU도 작동함 (느림) |
| GPU VRAM | VoxCPM-0.5B의 경우 5GB, VoxCPM2 (2B)의 경우 8GB |
| 디스크 | 모델당 약 2GB (가중치가 HF에서 자동 다운로드됨) |
| 네트워크 | huggingface.co 접근 가능 (또는 HF_ENDPOINT를 미러로 설정) |
설치:
pip install voxcpm
중국 내 HF 속도가 느린 배포의 경우 ModelScope 미러 사용:
export HF_ENDPOINT=https://hf-mirror.com
# 또는 ModelScope 직접 사용:
pip install modelscope
빠른 시작
CLI (가장 간단함)
# 기본 합성 → WAV
voxcpm design --text "你好,欢迎收听三分钟 AI 快报。" --output greeting.wav
# 음성 스타일 자연어 설명 포함
voxcpm design --text "(年轻女声,温柔甜美) 今天天气真好,我们来聊聊 AI。" --output warm.wav
# 영어
voxcpm design --text "Welcome to today's AI briefing." --output en.wav
# 배치 처리
voxcpm batch --input-file lines.txt --output-dir out/
Python SDK (프로그래밍 방식)
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, # 확산 단계 (많을수록 품질 향상, 속도 저하)
seed=42 # 재현성
)
sf.write("demo.wav", wav, model.tts_model.sample_rate) # 24 kHz 출력
스트리밍 합성 (긴 텍스트용)
for chunk in model.generate_streaming(text="매우 긴 텍스트..."):
# chunk는 PCM 샘플의 np.ndarray입니다
process(chunk)
입력 모드
1. 디자인 (자연어 음성 제어)
텍스트 시작 부분에 음성 설명을 ()로 감싸세요:
"(年轻女声,语气甜美,稍快语速) 今天要给大家介绍一款有意思的 AI 工具。"
"(中年男声,稳重、专业) 欢迎收听本期节目。"
"(带四川口音的女生,轻松) 这个咋回事嘛!"
사용 가능한 단서 (조합 가능):
- 음성 유형: 男声 / 女声 / 童声 / 老年男声 / 中年女声 ...
- 어조: 温柔 / 严肃 / 兴奋 / 平静 / 忧郁 / 慵懒 ...
- 속도: 快语速 / 慢语速 / 稍快 / 稍慢
- 스타일: 播音腔 / 口语化 / 说书人 / 儿童剧 / 广告腔
- 방언: 四川话 / 粤语 / 吴语 / 东北话 / 河南话 / 陕西话 / 山东话 / 天津话 / 闽南话
2. 음성 복제 (제로샷)
3~30초 길이의 참조 오디오와 그 대본을 제공하세요:
wav = model.generate(
text="합성할 새 텍스트입니다.",
prompt_wav_path="reference.wav",
prompt_text="참조 오디오에 해당하는 원문 (정확히 필사)"
)
생성된 음성은 참조 화자의 음성과 일치합니다.
3. 결합 (복제 + 스타일 조정)
wav = model.generate(
text="(稍快,兴奋) 合成할 새 텍스트입니다.",
reference_wav_path="reference.wav" # 더 부드러운 복제 형태; 음색을 유지하지만 스타일이 우선함
)
일반적인 워크플로우
종단 간: 대본 → 오디오
podcast-scriptwriter와 함께 사용. 대본이 주어졌을 때:
A(轻松):欢迎收听《三分钟 AI 快报》。
B(认真):本周动作不小。
import re
from voxcpm import VoxCPM
import soundfile as sf, numpy as np
model = VoxCPM.from_pretrained("openbmb/VoxCPM2", load_denoiser=False)
voices = {
'A': "reference_female.wav", # 또는 "(年轻女声,语气理性犀利)" 접두사 사용
'B': "reference_male.wav",
}
segments = []
for line in open('script.txt', encoding='utf-8'):
m = re.match(r'^([AB])(([^)]+)):(.+)$', line.strip())
if not m: continue
speaker, tone, text = m.groups()
styled = f"({tone}) {text}"
wav = model.generate(text=styled, prompt_wav_path=voices[speaker], cfg_value=2.0, inference_timesteps=10)
segments.append(wav)
segments.append(np.zeros(int(0.4 * model.tts_model.sample_rate))) # 0.4초 일시 정지
full = np.concatenate(segments)
sf.write('episode.wav', full, model.tts_model.sample_rate)
다국어 팟캐스트
동일한 대본을 en/ja/ko/fr로 번역하여 입력; VoxCPM이 각 줄의 언어를 자동 감지합니다. 언어 간에도 호스트 정체성을 유지하기 위해 동일한 참조 오디오를 사용하세요.
높은 처리량 vLLM 서빙
대량 처리를 위해 OpenAI 호환 vLLM Omni 서버를 사용하세요:
vllm serve openbmb/VoxCPM2 --omni --port 8000
그런 다음 OpenAI TTS처럼 /v1/audio/speech를 호출하세요.
대체方案: edge-tts (GPU 없음)
환경에서 VoxCPM을 사용할 수 없는 경우 (GPU 부재, HF 차단, 시간 제약), Microsoft Edge TTS로 대체하세요 (무료, API 키 불필요, 400개 이상의 음성):
pip install edge-tts
edge-tts --voice zh-CN-XiaoxiaoNeural --text "你好世界" --write-media hello.mp3
단점: 음성 복제 불가, 고정된 음성 풀, 네트워크 의존적, 오픈 소스 아님. 허용 가능한 임시 방편입니다.
제한 사항
- GPU 강력 권장 — CPU도 작동하지만 약 10~50배 느림.
- 첫 실행 시 HF에서 약 2 GB 다운로드; 속도가 느리면
HF_ENDPOINT를 미러로 설정하세요. - CUDA 12+는 최신 드라이버 필요 — 구형 드라이버는 CUDA 11 빌드가 필요할 수 있음;
torch.cuda.is_available()확인. - 긴 텍스트 (> 2분):
generate_streaming을 사용하여 청크를 이어붙이세요; 순수generate는 VRAM 한계에 도달할 수 있음. - 영어 전용 복제: 작동하지만 중국어 원어민보다 샘플 품질이 약간 낮음.
- 방언은 접두사 형식 필요 —
(粤语) 早晨。처럼,粤语:早晨。이 아님. - 단어 수준 타이밍 출력 없음 — 노래방 기능을 위해 생성된 WAV에 whisper 스타일 STT 정렬을 사용하세요.
- 샘플레이트는 24 kHz 고정 — 필요시 다운스트림에서 리샘플링.
- Python 3.13+ 미테스트 — 3.10~3.12로 고정하세요.
오류 모드
| 증상 | 원인 | 조치 |
|---|---|---|
torch.cuda.OutOfMemoryError | GPU에 비해 모델이 너무 큼 | openbmb/VoxCPM-0.5B로 전환하거나 CPU 사용 |
| 모델 다운로드 중단 | HF 연결 문제 | HF_ENDPOINT=https://hf-mirror.com 설정 |
| 로봇/금속성 음성 | cfg_value가 너무 높음 | 1.5~2.5 시도; 최적값은 2.0 |
| 음성 복제가 일치하지 않음 | 참조가 너무 짧거나 잡음 | 5~15초 깨끗한 샘플 사용; load_denoiser=True 활성화 |
| 언어 자동 감지 실패 | 텍스트 혼합 | 언어별로 분할하여 세그먼트별 생성 |
CLI voxcpm: command not found | venv PATH에 없음 | 활성 환경에서 pip install voxcpm; 또는 python -m voxcpm ... |
참고 자료
- 저장소: https://github.com/OpenBMB/VoxCPM ⭐ 32.4k
- 문서: https://voxcpm.readthedocs.io/
- HF 모델: https://huggingface.co/openbmb/VoxCPM2 (2B) 또는 https://huggingface.co/openbmb/VoxCPM-0.5B (소형)
- 데모: https://openbmb.github.io/VoxCPM-demopage/
- 라이선스: Apache-2.0
- 대체方案: Microsoft Edge TTS (
pip install edge-tts) — API 키 불필요, 복제 불가