Chatterbox 설치 및 사용 가이드 (Mac)

개요

Chatterbox는 Resemble AI가 공개한 오픈소스 TTS(Text-to-Speech) 엔진으로, 고품질 음성 합성과 제로샷 음성 복제를 지원합니다. 이 가이드는 Mac(Apple Silicon M1/M2/M3/M4 포함) 환경에서 Chatterbox를 설치하고 사용하는 방법을 단계별로 안내합니다.

1. 사전 요구사항

권장 환경

macOS: 12.3 (Monterey) 이상 — MPS 지원을 위해 권장
Python: 3.11 (공식 권장 버전)
칩셋: Apple Silicon(M1/M2/M3/M4) 또는 Intel Mac
메모리: 최소 8GB RAM (16GB 이상 권장)
디스크: 모델 다운로드 포함 약 5~8GB 여유 공간

Homebrew 설치 확인

Homebrew가 없다면 먼저 설치합니다.

1/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Python 3.11 설치 (Homebrew)

시스템 Python 대신 Homebrew로 설치한 Python 3.11 사용을 권장합니다.

1brew install python@3.11

설치 확인:

1python3.11 --version2# Python 3.11.x

2. 설치 방법

가상환경 생성 및 활성화

프로젝트 전용 가상환경을 만들어 의존성 충돌을 방지합니다.

1# 작업 디렉터리 생성2mkdir ~/chatterbox-project && cd ~/chatterbox-project3 4# 가상환경 생성 (Python 3.11 명시)5python3.11 -m venv .venv6 7# 가상환경 활성화8source .venv/bin/activate

의존성 순서대로 설치 (권장)

Mac에서는 의존성 설치 순서가 중요합니다. 아래 순서를 따르세요.

1# 1. pip, setuptools, wheel 최신화2pip install --upgrade pip setuptools wheel3 4# 2. PyTorch 및 torchaudio 설치 (2.6.0 버전 권장)5pip install torch==2.6.0 torchaudio==2.6.06 7# 3. NumPy 먼저 설치 (pkuseg 빌드 의존성)8pip install numpy9 10# 4. 핵심 의존성 설치11pip install transformers diffusers conformer12 13# 5. Chatterbox 설치 (--no-deps 옵션으로 의존성 재설치 방지)14pip install chatterbox-tts --no-deps

간단 설치 (표준 방법)

의존성 충돌이 없다면 한 줄로 설치할 수도 있습니다.

1pip install chatterbox-tts

3. Apple Silicon(M-시리즈) MPS 가속 설정

Apple Silicon Mac은 Metal Performance Shaders(MPS)를 통해 GPU 가속을 사용할 수 있습니다. 단, Chatterbox의 일부 연산(aten::_fft_r2c 등)이 MPS에서 아직 완전히 지원되지 않아 **CPU 폴백(fallback)**이 필요합니다.

MPS 폴백 환경변수 설정

터미널 세션 또는 스크립트 상단에 아래 환경변수를 설정합니다.

1export PYTORCH_ENABLE_MPS_FALLBACK=1

영구 적용하려면 ~/.zshrc에 추가하세요.

1echo 'export PYTORCH_ENABLE_MPS_FALLBACK=1' >> ~/.zshrc2source ~/.zshrc

코드에서 디바이스 자동 감지

1import torch2 3def get_device():4    if torch.cuda.is_available():5        return "cuda"6    elif torch.backends.mps.is_available():7        return "mps"8    else:9        return "cpu"10 11device = get_device()12print(f"사용 디바이스: {device}")

참고: MPS를 사용해도 일부 연산은 자동으로 CPU에서 실행됩니다. PYTORCH_ENABLE_MPS_FALLBACK=1 없이 MPS 디바이스를 지정하면 NotImplementedError가 발생할 수 있습니다. 안정성을 우선한다면 device="cpu"를 사용하세요.

4. 기본 사용법 — 텍스트를 음성으로 변환

기본 TTS

1import torchaudio2from chatterbox.tts import ChatterboxTTS3 4# 모델 로드 (디바이스 지정)5device = "mps"  # 또는 "cpu"6model = ChatterboxTTS.from_pretrained(device=device)7 8# 텍스트를 음성으로 변환9text = "안녕하세요! Chatterbox TTS를 사용해 음성을 생성했습니다."10wav = model.generate(text)11 12# 파일로 저장13torchaudio.save("output.wav", wav, model.sr)14print("output.wav 저장 완료")

Chatterbox Turbo (저지연 영어 TTS)

1from chatterbox.tts_turbo import ChatterboxTurboTTS2import torchaudio3 4model = ChatterboxTurboTTS.from_pretrained(device="cpu")5text = "Hi there! This is Chatterbox Turbo, faster and lighter."6wav = model.generate(text)7 8torchaudio.save("turbo_output.wav", wav, model.sr)

5. 음성 복제 (Voice Cloning) — 참조 오디오 활용

Chatterbox는 약 10초 분량의 참조 오디오를 기반으로 해당 화자의 목소리로 텍스트를 읽어줍니다.

참조 오디오 준비 기준

길이: 5~15초 (10초 권장)
형식: WAV 또는 MP3
품질: 배경 잡음이 적고 목소리가 명확한 클립

음성 복제 코드

1import torchaudio2from chatterbox.tts import ChatterboxTTS3 4model = ChatterboxTTS.from_pretrained(device="cpu")5 6text = "이 음성은 참조 오디오의 목소리를 복제하여 생성되었습니다."7audio_prompt_path = "reference_voice.wav"  # 참조 오디오 경로8 9wav = model.generate(10    text,11    audio_prompt_path=audio_prompt_path12)13 14torchaudio.save("cloned_voice_output.wav", wav, model.sr)15print("음성 복제 완료!")

6. 감정 파라미터 조절 (exaggeration, cfg_weight)

Chatterbox는 두 가지 핵심 파라미터로 음성 표현력과 속도를 제어합니다.

파라미터 설명

파라미터	범위	기본값	설명
`exaggeration`	0.25 ~ 2.0	0.5	표현 강도. 높을수록 드라마틱하고 강렬한 음성
`cfg_weight`	0.2 ~ 1.0	0.5	텍스트 충실도 및 속도. 낮을수록 느리고 여유로운 발화

사용 예시

1import torchaudio2from chatterbox.tts import ChatterboxTTS3 4model = ChatterboxTTS.from_pretrained(device="cpu")5text = "오늘은 정말 놀라운 하루였어요! 믿을 수가 없어요."6 7# 1. 기본 설정 (자연스러운 음성)8wav = model.generate(text, exaggeration=0.5, cfg_weight=0.5)9torchaudio.save("natural.wav", wav, model.sr)10 11# 2. 드라마틱한 표현 (나레이션, 감정적 연기)12wav = model.generate(text, exaggeration=0.8, cfg_weight=0.3)13torchaudio.save("dramatic.wav", wav, model.sr)14 15# 3. 차분하고 느린 음성 (오디오북, 안내 음성)16wav = model.generate(text, exaggeration=0.3, cfg_weight=0.2)17torchaudio.save("calm.wav", wav, model.sr)18 19# 4. 크로스 언어 음성 복제 (cfg_weight=0.0 권장)20wav = model.generate(21    "Hello, this is a cross-language voice clone test.",22    audio_prompt_path="korean_voice.wav",23    exaggeration=0.5,24    cfg_weight=0.025)26torchaudio.save("cross_lang.wav", wav, model.sr)

파라미터 조절 가이드

빠른 말투 참조 오디오 사용 시: cfg_weight를 0.3 이하로 낮춰 속도 조절
강렬한 감정 표현 원할 때: exaggeration을 0.7 이상으로 올리고 cfg_weight는 낮게 유지
크로스 언어 복제: cfg_weight=0.0으로 설정하면 언어 간 전이 품질 향상

7. 자주 발생하는 오류 및 해결 방법

오류 1: CUDA 디바이스 역직렬화 오류

RuntimeError: Attempting to deserialize object on a CUDA device
but torch.cuda.is_available() is False.

원인: 모델 가중치가 CUDA 기준으로 저장되어 있어 Mac에서 로드 불가.

해결: map_location 지정 또는 CPU 모드 사용.

1# 해결 방법: CPU로 명시적 로드2model = ChatterboxTTS.from_pretrained(device="cpu")

오류 2: MPS 미구현 연산 오류

NotImplementedError: The operator 'aten::_fft_r2c' is not currently
implemented for the MPS device.

원인: MPS에서 지원하지 않는 PyTorch 연산 사용.

해결: PYTORCH_ENABLE_MPS_FALLBACK=1 환경변수 설정.

1export PYTORCH_ENABLE_MPS_FALLBACK=12python your_script.py

오류 3: pkuseg 빌드 실패

error: Failed building wheel for pkuseg

원인: NumPy가 pkuseg 빌드 전에 설치되지 않아 발생.

해결: NumPy 먼저 설치 후 재시도.

1pip install numpy2PIP_NO_BUILD_ISOLATION=1 pip install pkuseg

오류 4: MPS 플레이스홀더 오류

RuntimeError: Placeholder storage has not been allocated on MPS device

원인: 참조 오디오 파일 문제 또는 MPS 메모리 할당 실패.

해결: 다른 참조 오디오 파일을 사용하거나 device="cpu"로 전환.

오류 5: 모듈을 찾을 수 없음

ModuleNotFoundError: No module named 'chatterbox'

원인: 가상환경이 활성화되지 않았거나 설치가 올바르게 되지 않음.

해결:

1# 가상환경 활성화 확인2source .venv/bin/activate3 4# 재설치5pip install chatterbox-tts --no-deps

개요