voice_copy/README.md

voice_copy

참조 음성 몇 초만 있으면 아무 텍스트나 그 목소리로 합성해 주는 zero-shot 음성 클로닝 웹앱입니다. jamiepine/voicebox의 음성 클로닝 기능(Qwen3-TTS Base 엔진)만 떼어내 간단한 UI로 감쌌습니다.

• 엔진: Qwen3-TTS-12Hz Base (qwen-tts 패키지, zero-shot voice clone)
• 지원 언어: 한국어 · English · 中文 · 日本語 · 독일어 · 프랑스어 · 러시아어 · 포르투갈어 · 스페인어 · 이탈리아어
• UI: 파일 업로드 또는 마이크 녹음 → 전사 입력 → 합성할 텍스트 입력 → 생성/재생/다운로드

필요 사항

• Python 3.9+ (3.10~3.12 권장)
• NVIDIA GPU 권장 (CPU도 되지만 매우 느림). VRAM 6GB+ 권장.
• (선택) ffmpeg — mp3/m4a/webm 업로드를 디코딩할 때 필요. wav/flac와 브라우저 녹음(WAV)은 ffmpeg 없이 동작합니다.

설치

# 1) 자신의 환경에 맞는 torch를 먼저 설치
pip install torch --index-url https://download.pytorch.org/whl/cu128   # NVIDIA(CUDA 12.8)
# CPU만 있으면:  pip install torch

# 2) 나머지 의존성
pip install -r requirements.txt

실행

python app.py
# 브라우저에서 http://localhost:8000 접속

첫 생성 요청 때 Qwen3-TTS 가중치(수 GB)가 HuggingFace에서 자동으로 다운로드됩니다. 이후에는 캐시됩니다.

환경 변수

변수	기본값	설명
VOICE_COPY_MODEL_SIZE	1.7B	모델 크기. 1.7B(품질↑) 또는 0.6B(가벼움)
VOICE_COPY_DEVICE	자동	cuda / cpu / mps 강제 지정
VOICE_COPY_HOST	0.0.0.0	바인드 호스트
VOICE_COPY_PORT	8000	포트

예: VOICE_COPY_MODEL_SIZE=0.6B python app.py

사용법

1. 참조 음성 — 클로닝할 목소리를 5~15초 정도 업로드하거나 마이크로 녹음합니다.
2. 전사 — 그 참조 음성에서 말한 내용을 그대로 텍스트로 적습니다. (클로닝 품질에 중요)
3. 합성할 텍스트 — 그 목소리로 말하게 할 문장을 입력하고 "목소리 생성"을 누릅니다.

API

• GET /api/health — 디바이스/모델/언어 상태
• POST /api/clone — multipart form: ref_audio(파일), ref_text, text, language, instruct(선택), seed(선택) → audio/wav 반환

curl -X POST http://localhost:8000/api/clone \
  -F ref_audio=@sample.wav -F ref_text="안녕하세요" \
  -F text="복제된 목소리로 말합니다." -F language=ko \
  --output cloned.wav

구조

app.py              FastAPI 서버 (UI 제공 + /api/clone)
engine.py           Qwen3-TTS 클로닝 래퍼 (voicebox pytorch_backend에서 추출/단순화)
static/index.html   단일 페이지 UI
requirements.txt

라이선스 / 출처

음성 클로닝 로직은 jamiepine/voicebox에서 파생했습니다. 모델 가중치 및 사용은 각 모델(Qwen3-TTS)과 voicebox의 라이선스를 따르며, 목소리 클로닝은 반드시 본인 또는 동의를 받은 사람의 음성에만 사용하세요.