세팅과 모델 선택

이 하네스는 세팅을 추측으로 시작하지 않습니다. 칩이 무엇인지, Python이 몇 버전인지, ffmpeg가 설치되어 있는지를 먼저 확인하고, 그 결과를 근거로 모델을 추천합니다. “처음 세팅하려고 해” 또는 “내 맥에서 쓸 모델 추천해줘”라고 말하면 setup-advisor가 진입점이 됩니다.

1) 환경 감지

추천보다 감지가 먼저입니다. local-env-setup 스킬이 scripts/detect_env.sh로 아래 항목을 수집합니다.

칩은 uname -m으로 확인합니다. arm64면 Apple Silicon이고, x86_64면 Intel이나 Linux입니다.
맥이면 통합메모리를 sysctl hw.memsize로 확인합니다.
Python 버전을 확인합니다. 3.10과 3.11이 호환성이 가장 좋고, 일부 모델은 3.12까지 지원합니다.
ffmpeg와 ffprobe를 확인합니다. 오디오 조립에 반드시 필요하고, 없으면 brew install ffmpeg로 설치합니다.
GPU를 확인합니다. Linux면 nvidia-smi로 보고, 맥이면 PyTorch 설치 뒤 torch.backends.mps.is_available()로 MPS 가속을 확인합니다.

감지 결과를 표로 요약하고 부족한 것부터 안내합니다. ffmpeg가 없으면 그것부터 설치하고 넘어갑니다.

2) 모델 선택

감지가 끝나면 네 가지를 묻습니다. 주 언어가 한국어인지 영어인지, 하드웨어가 무엇인지, 상업적으로 쓸 것인지, 품질과 설치 난이도 중 무엇을 우선할지입니다. 답에 따라 한두 개만 추천합니다. 여섯 개를 모두 나열하지 않습니다.

한국어가 주 언어라면 현실적인 후보는 셋으로 좁혀집니다.

최고 품질을 원하고 설치 부담을 감수하겠다면 GPT-SoVITS v2Pro를 씁니다. MIT 라이선스라 상업적으로도 쓸 수 있고, 참조음성은 5초면 충분합니다. 대신 conda와 Gradio 세팅에 손이 많이 갑니다.
크기가 작고 라이선스가 관대하며 공식 한국어를 지원하는 모델을 원하면 CosyVoice2-0.5B를 씁니다. Apache-2.0 라이선스이고 참조음성은 3초면 되며, MPS 가속이 병합되어 있습니다.
가장 쉽게 시작하고 싶으면 XTTS-v2를 씁니다. pip install coqui-tts 한 줄이면 설치되지만, 가중치가 개인용 라이선스라 상업적으로는 쓸 수 없고 MPS에서 불안정해 CPU에서 느리게 동작합니다.

고르는 근거와 결정 트리는 모델 비교에 자세히 있습니다. 추천은 확정하는 것이 아니라 출발점이라서, 실제로 짧은 문장을 합성해 들어 보고 바꿔도 됩니다.

3) 설치

모델별로 venv를 따로 두기를 권합니다. torch 버전이나 mecab, espeak 의존성이 서로 충돌하는 일이 잦습니다.

python3 -m venv .venv-cosyvoice && source .venv-cosyvoice/bin/activate
python -m pip install -U pip

선택한 모델의 설치 레시피는 local-env-setup 스킬이 꺼내 실행하거나 안내합니다. 예를 들어 XTTS-v2는 다음과 같습니다.

pip install coqui-tts
# 첫 실행 때 가중치가 자동으로 내려받아집니다.
# MPS에서 멈추면 device="cpu"로 강제하거나 아래 설정을 켭니다.
export PYTORCH_ENABLE_MPS_FALLBACK=1

CosyVoice2와 GPT-SoVITS는 git clone과 conda 환경 구성이 필요해서 작업이 조금 더 많습니다. 가중치는 각각 HuggingFace의 FunAudioLLM/CosyVoice2-0.5B와 lj1995/GPT-SoVITS에서 받습니다.

알아 둘 함정

XTTS는 MPS에서 멈추는 사례가 알려져 있습니다. CPU로 실행하면 안전하지만 실시간보다 느립니다.
OpenVoice의 한국어 베이스인 MeloTTS는 mecab-ko와 unidic 설치가 필수 조건입니다. Apple Silicon에서는 brew로 mecab을 먼저 설치해야 할 수 있습니다.
가중치를 받을 때만 인터넷이 필요하고, 그 뒤로는 완전히 오프라인으로 동작합니다.

설치가 끝났으면 참조음성 준비로 자기 목소리를 담습니다. 참조 클립의 품질이 결과 품질을 사실상 결정합니다.