zenn/voice.sori.studio

Files

zenn 7101fdcd65 Initial commit: Korean voice-cloning TTS prototype

FastAPI backend, web UI, CosyVoice3/F5-TTS setup scripts, and handoff docs for GPU PC continuation.

Co-authored-by: Cursor <cursoragent@cursor.com>

2026-06-04 13:36:37 +09:00

6.9 KiB

Raw Permalink Blame History

다음 작업자 인수인계 문서

이 문서는 한국어 보이스 클로닝 TTS 프로젝트를 다른 PC 또는 다음 AI가 이어받을 때 가장 먼저 읽어야 하는 문서입니다.

한 줄 요약

한국어 자연스러움과 본인 목소리 유사도를 우선하는 로컬 TTS 프로토타입입니다. 기본 모델은 CosyVoice3, 비교 모델은 F5-TTS이며, FastAPI 백엔드와 간단한 웹 UI까지 만들어져 있습니다.

현재 작업 상태

프로젝트 뼈대 생성 완료
FastAPI 서버 구현 완료
웹 UI 구현 완료
한국어 텍스트 전처리 구현 완료
내 목소리 reference 녹음 가이드 작성 완료
CosyVoice3 / F5-TTS A/B 비교 스크립트 작성 완료
모델별 격리 venv 설치 스크립트 작성 완료
현재 Mac에서 API/UI smoke test 완료
실제 고품질 TTS 추론은 아직 NVIDIA GPU 환경에서 검증 필요

중요한 전제

현재 작업한 Mac은 Apple Silicon 환경이고 nvidia-smi가 없습니다. 따라서 여기서는 API/UI 구조 확인은 가능하지만, 계획한 고품질 보이스 클로닝 추론은 Windows 또는 Linux의 NVIDIA GPU PC에서 이어가는 것이 맞습니다.

메인 PC가 Windows + NVIDIA GPU라면 다음 순서로 진행하세요. 가능하면 WSL2 Ubuntu 환경을 권장합니다. Windows 네이티브도 가능할 수 있지만, CosyVoice는 Linux/WSL2 쪽이 문제 해결 자료가 많습니다.

깃에 올릴 때 주의

올리면 좋은 것:

README.md
docs/HANDOFF.md
backend/
web/
scripts/
config/
samples/README.md
samples/my_voice_ref.txt
.env.example
.gitignore
docker-compose.yml
tests/

올리지 말아야 할 것:

.venvs/
models/
outputs/
external/CosyVoice/
실제 내 목소리 WAV 파일
.env 안에 개인 경로나 민감한 값이 들어간 경우

현재 .gitignore에는 .venvs/, models/, outputs/, external/CosyVoice/, .env, WAV 파일 등이 제외되도록 설정되어 있습니다.

메인 PC에서 처음 할 일

git clone <repo-url>
cd tts

chmod +x scripts/*.sh
./scripts/check_env.sh

Windows라면 WSL2 Ubuntu에서 실행하는 것을 권장합니다.

sudo apt update
sudo apt install -y git python3 python3-venv python3-pip ffmpeg sox libsox-dev

NVIDIA GPU가 제대로 잡히는지 확인하세요.

nvidia-smi

환경 설치 순서

API 서버용 venv:

./scripts/setup_api.sh

F5-TTS 비교용 venv:

./scripts/setup_f5tts.sh

CosyVoice3 기본 모델용 venv:

./scripts/setup_cosyvoice.sh

setup_cosyvoice.sh는 external/CosyVoice 레포를 클론하고 models/Fun-CosyVoice3-0.5B 모델을 다운로드합니다. 시간이 오래 걸릴 수 있습니다.

현재 기본 모델

기본값은 cosyvoice입니다.

내 목소리 샘플 준비

자세한 가이드는 samples/README.md에 있습니다.

권장 파일:

samples/my_voice_30s.wav
samples/my_voice_1m.wav
samples/my_voice_3m.wav
samples/my_voice_ref.txt

중요:

WAV는 mono, 24kHz 또는 16kHz 권장
녹음 대본과 my_voice_ref.txt 내용은 일치해야 함
조용한 환경에서 마이크 거리 일정하게 유지
30초, 1분, 3분 샘플을 각각 비교

reference WAV 전처리:

./scripts/prepare_reference.sh samples/my_voice_30s.wav

모델 A/B 비교

설치 검증용:

./scripts/run_ab_compare.py --ref-audio auto

본인 목소리 비교:

./scripts/run_ab_compare.py --ref-audio samples/my_voice_30s.wav

길이별 reference 비교:

./scripts/compare_voice_lengths.sh

결과는 보통 아래에 생성됩니다.

outputs/ab_compare/
outputs/voice_length_compare/

평가 기준:

한국어 발음 정확도
조사/어미 자연스러움
억양과 호흡
내 목소리 유사도
긴 문장 안정성
숫자, 영어, 기호 포함 문장 처리

서버 실행

cp .env.example .env
./scripts/run_server.sh

브라우저:

http://localhost:8000

주요 API:

GET  /api/health
POST /api/tts
GET  /api/audio/{job_id}
GET  /api/voice-samples
POST /api/voice-sample

간단 테스트:

curl -X POST http://localhost:8000/api/tts \
  -H "Content-Type: application/json" \
  -d '{"text":"안녕하세요. 한국어 음성 합성 테스트입니다."}'

Mac에서 가능한 것과 불가능한 것

현재 Mac에서 가능한 것:

FastAPI 서버 실행
웹 UI 확인
/api/health 확인
샘플 업로드 UI 확인
텍스트 전처리 테스트

현재 Mac에서 어려운 것:

CosyVoice3 고품질 추론
F5-TTS CUDA 기반 추론
최종 품질 평가

즉, Mac은 개발/구조 확인용이고, 최종 모델 품질 검증은 NVIDIA GPU PC에서 해야 합니다.

다음 AI에게 요청할 때 권장 문장

다음 AI에게는 아래처럼 시작하면 됩니다.

먼저 docs/HANDOFF.md를 읽고, 현재 한국어 보이스 클로닝 TTS 프로젝트 상태를 파악한 뒤 이어서 작업해줘.
목표는 Windows/NVIDIA GPU PC에서 CosyVoice3와 F5-TTS를 설치하고, 내 목소리 샘플로 A/B 비교 후 더 자연스러운 모델을 선택하는 거야.

다음 작업자가 우선 확인할 파일

docs/HANDOFF.md
README.md
config/settings.yaml
config/model_choice.json
.env.example
samples/README.md
scripts/setup_cosyvoice.sh
scripts/setup_f5tts.sh
scripts/run_ab_compare.py
backend/app/main.py

알려진 주의점

FastAPI TestClient는 현재 API venv에서 httpx 계열 패키지가 없어 직접 테스트가 실패했습니다. 대신 실제 uvicorn 서버를 띄우고 /api/health와 웹 UI 200 응답은 확인했습니다.
scripts/setup_f5tts.sh와 scripts/setup_cosyvoice.sh는 CUDA 12.4 PyTorch index를 사용합니다. 메인 PC CUDA 버전에 맞지 않으면 cu124를 cu121, cu126, cu128 등으로 조정해야 할 수 있습니다.
CosyVoice는 sox, libsox-dev, ffmpeg가 필요할 수 있습니다.
실제 음성 파일은 개인정보성이 있으므로 깃에 올리지 않는 것을 권장합니다.
.env도 깃에 올리지 말고 .env.example만 공유하세요.

완료 기준

이 프로젝트의 다음 큰 완료 기준은 다음과 같습니다.

NVIDIA GPU PC에서 ./scripts/setup_cosyvoice.sh 성공
NVIDIA GPU PC에서 ./scripts/setup_f5tts.sh 성공
본인 목소리 샘플로 ./scripts/run_ab_compare.py 실행 성공
outputs/ab_compare/ 결과를 듣고 모델 선택
선택 모델로 ./scripts/run_server.sh 실행
웹 UI에서 텍스트 입력 후 본인 목소리 WAV 재생 성공

6.9 KiB Raw Permalink Blame History