Snowiki
로그인회원가입

snow · 2026.5.18 00:05 · 조회 2

XTTS-v2 설치 및 사용 가이드 (Mac)

XTTS

개요

이 가이드는 Mac(Apple Silicon — M1/M2/M3) 환경에서 XTTS-v2를 설치하고 사용하는 방법을 설명한다. Coqui AI의 TTS Python 라이브러리를 통해 설치하며, ARM64 아키텍처의 패키지 호환성 문제 때문에 Conda 환경 사용을 권장한다.

주의: Coqui AI는 2024년 1월 서비스를 종료했다. Apple Silicon(MPS)에 대한 공식 GPU 가속 지원은 없으며, CPU 모드로 실행해야 한다. CPU만으로도 실용적인 속도로 사용 가능하다.

사전 요구사항

  • macOS: Apple Silicon(M1/M2/M3) 기반 Mac
  • Python: 3.9 이상, 3.12 미만 (3.10 권장)
  • Homebrew: 패키지 관리자 (https://brew.sh)
  • Conda: Miniconda 또는 Anaconda (ARM64 패키지 관리)
  • 디스크 공간: XTTS-v2 모델 파일 약 3~4GB 포함 총 5GB 이상 여유 공간
  • RAM: 최소 8GB, 16GB 권장

설치 방법

1단계: Homebrew 의존성 설치

1brew install mecab espeak

mecab은 일본어 형태소 분석기, espeak은 음소 변환에 사용된다. 한국어/영어만 사용해도 설치해두는 것을 권장한다.

2단계: Conda 환경 생성

1conda create --name xtts python=3.102conda activate xtts

Python 3.10을 사용한다. 3.12 이상에서는 TTS 라이브러리가 동작하지 않을 수 있다.

3단계: 핵심 의존성 설치

1pip install numpy==1.21.62conda install scipy scikit-learn Cython

numpy 버전을 명시하는 이유는 최신 버전과의 호환성 문제 때문이다. scipy와 scikit-learn은 conda로 설치해야 ARM64용 바이너리를 정상적으로 받을 수 있다.

4단계: TTS 라이브러리 설치

pip으로 직접 설치하는 방법:

1pip install TTS

또는 최신 개발 버전을 소스에서 설치하는 방법:

1git clone https://github.com/coqui-ai/TTS.git2cd TTS3pip install -e .

설치 후 버전 확인:

1tts --version

5단계: 설치 확인

1python -c "from TTS.api import TTS; print('TTS 설치 성공')"

Apple Silicon MPS 설정

Apple Silicon의 Metal Performance Shaders(MPS)를 통한 GPU 가속은 공식적으로 지원되지 않으며, MPS 디바이스로 실행하면 프로세스가 멈추는 문제가 보고되어 있다. CPU 모드로 실행하는 것을 강력히 권장한다.

환경 변수로 MPS 비활성화:

1export PYTORCH_ENABLE_MPS_FALLBACK=1

또는 Python 코드에서 명시적으로 CPU 사용:

1import os2os.environ["PYTORCH_ENABLE_MPS_FALLBACK"] = "1"3 4import torch5device = "cpu"  # MPS 대신 CPU 사용

기본 TTS 사용법

명령줄(CLI)에서 사용

XTTS-v2 모델로 텍스트를 음성으로 변환하는 기본 명령:

1tts --model_name tts_models/multilingual/multi-dataset/xtts_v2 \2    --text "안녕하세요, XTTS-v2 테스트입니다." \3    --speaker_wav /path/to/speaker.wav \4    --language_idx ko \5    --out_path output.wav

첫 실행 시 모델 파일(약 3~4GB)을 자동으로 다운로드한다.

Python API에서 사용

1from TTS.api import TTS2 3# 모델 로드 (처음 실행 시 다운로드 발생)4tts = TTS("tts_models/multilingual/multi-dataset/xtts_v2")5 6# 텍스트를 음성으로 변환7tts.tts_to_file(8    text="안녕하세요, XTTS-v2를 사용한 한국어 음성 합성입니다.",9    file_path="output.wav",10    speaker_wav="/path/to/reference.wav",11    language="ko"12)

음성 복제 사용법

음성 복제는 참조 오디오 파일의 목소리를 그대로 사용해 새로운 텍스트를 읽도록 하는 기능이다.

참조 오디오 준비 요령

  • 길이: 6~12초 권장 (너무 짧으면 품질 저하)
  • 형식: WAV, 22050Hz 또는 44100Hz 샘플링 레이트
  • 품질: 배경 소음이 없는 깨끗한 음성
  • 내용: 다양한 음소가 포함된 자연스러운 문장

Python으로 음성 복제

1from TTS.api import TTS2 3tts = TTS("tts_models/multilingual/multi-dataset/xtts_v2")4 5# 단일 참조 파일로 음성 복제6tts.tts_to_file(7    text="이 문장은 참조 오디오의 목소리로 읽힙니다.",8    speaker_wav="reference.wav",9    language="ko",10    file_path="cloned_output.wav"11)12 13# 복수 참조 파일로 더 정확한 복제14tts.tts_to_file(15    text="여러 참조 파일을 사용하면 더 자연스럽습니다.",16    speaker_wav=["ref1.wav", "ref2.wav", "ref3.wav"],17    language="ko",18    file_path="cloned_output_multi.wav"19)

저수준 API로 직접 제어

1from TTS.tts.configs.xtts_config import XttsConfig2from TTS.tts.models.xtts import Xtts3import torch4import soundfile as sf5 6# 모델 직접 로드7config = XttsConfig()8config.load_json("/path/to/model/config.json")9model = Xtts.init_from_config(config)10model.load_checkpoint(config, checkpoint_dir="/path/to/model/")11model.eval()12 13# 화자 임베딩 추출14gpt_cond_latent, speaker_embedding = model.get_conditioning_latents(15    audio_path=["reference.wav"]16)17 18# 음성 생성19out = model.inference(20    "생성할 텍스트를 여기에 입력합니다.",21    "ko",22    gpt_cond_latent,23    speaker_embedding,24)25 26# 파일 저장27sf.write("output.wav", out["wav"], 24000)

다국어 TTS 예시

크로스 언어 기능으로 동일한 목소리(참조 오디오)를 사용해 여러 언어로 음성을 생성할 수 있다.

1from TTS.api import TTS2 3tts = TTS("tts_models/multilingual/multi-dataset/xtts_v2")4reference = "my_voice.wav"5 6# 한국어로 동일 목소리 사용7tts.tts_to_file(8    text="안녕하세요, 오늘 날씨가 맑네요.",9    speaker_wav=reference,10    language="ko",11    file_path="output_ko.wav"12)13 14# 영어로 동일 목소리 사용15tts.tts_to_file(16    text="Hello, the weather is nice today.",17    speaker_wav=reference,18    language="en",19    file_path="output_en.wav"20)21 22# 일본어로 동일 목소리 사용23tts.tts_to_file(24    text="こんにちは、今日は天気がいいですね。",25    speaker_wav=reference,26    language="ja",27    file_path="output_ja.wav"28)

자주 발생하는 오류 해결

오류 1: RuntimeError: MPS does not support ...

MPS 디바이스 관련 오류가 발생할 경우:

1# 환경 변수 설정 후 재실행2export PYTORCH_ENABLE_MPS_FALLBACK=1

또는 Python 코드 최상단에 추가:

1import os2os.environ["PYTORCH_ENABLE_MPS_FALLBACK"] = "1"

오류 2: ImportError: cannot import name 'numpy'

numpy 버전 충돌 문제:

1pip install numpy==1.21.6

오류 3: 프로세스가 멈춤(hang)

MPS 디바이스로 실행 중일 때 발생할 수 있다. CPU 모드로 강제 전환:

1# 코드에서 명시적으로 CPU 지정2tts = TTS("tts_models/multilingual/multi-dataset/xtts_v2").to("cpu")

오류 4: OSError: [Errno 2] No such file or directory: 'espeak'

espeak이 설치되지 않은 경우:

1brew install espeak2# 설치 후 환경 변수 확인3which espeak

오류 5: 모델 다운로드 실패

네트워크 문제로 모델 다운로드가 중단된 경우, 캐시 디렉터리를 비우고 재시도:

1rm -rf ~/.local/share/tts/tts_models--multilingual--multi-dataset--xtts_v22# Python 재실행 시 자동으로 재다운로드

오류 6: conda: command not found

Conda가 설치되지 않은 경우 Miniconda 설치:

1# Apple Silicon용 Miniconda 설치2curl -O https://repo.anaconda.com/miniconda/Miniconda3-latest-MacOSX-arm64.sh3bash Miniconda3-latest-MacOSX-arm64.sh

라이선스 주의사항

XTTS-v2는 Coqui Public Model License 1.0.0 (CPML) 라이선스 하에 배포된다.

  • 개인 연구, 학습, 비상업적 프로젝트에만 무료로 사용 가능하다.
  • 상업적 제품이나 서비스에 사용할 경우 별도 상업 라이선스가 필요하다. Coqui AI의 서비스 종료(2024년 1월)로 현재 공식 상업 라이선스 취득은 불가능한 상태다.
  • 타인의 목소리를 무단으로 복제하는 것은 법적·윤리적으로 문제가 될 수 있다. 반드시 본인의 목소리 또는 명시적 동의를 받은 목소리만 사용해야 한다.

참고 링크

댓글

아직 댓글이 없습니다.

댓글을 작성하려면 로그인이 필요합니다.