hmisaki/voicebox

TTS 엔진 추가

목표

새로운 텍스트 음성 변환 엔진을 Voicebox에 처음부터 끝까지 통합합니다: 의존성 조사, 백엔드 프로토콜 구현, 프론트엔드 UI 연결, PyInstaller 번들링, 빌드 확인. 사용자는 최종 빌드를 로컬에서만 테스트하면 됩니다.

참조 문서

전체 단계별 가이드는 docs/content/docs/developer/tts-engines.mdx에 있습니다. 시작하기 전에 이 파일 전체를 읽으십시오. 다음 내용이 포함되어 있습니다:

• Phase 0: 의존성 조사 (코드 작성 전에 필수)
• Phase 1: 백엔드 구현 (TTSBackend 프로토콜)
• Phase 2: 라우트 및 서비스 통합 (보통 변경 사항 없음)
• Phase 3: 프론트엔드 통합 (5개 파일)
• Phase 4: 의존성 (requirements.txt, justfile, CI, Docker)
• Phase 5: PyInstaller 번들링 (build_binary.py + server.py)
• Phase 6: 일반적인 상위 호환 문제 해결
• 구현 체크리스트 (단계 간 게이트)

워크플로우

1. 가이드 읽기

# TTS 엔진 문서 전체 읽기
cat docs/content/docs/developer/tts-engines.mdx

모든 단계, 특히 Phase 0과 Phase 5를 내재화하십시오. v0.2.3 릴리스는 Phase 0을 건너뛰었기 때문에 세 번의 패치 릴리스가 있었습니다.

2. 의존성 조사 (Phase 0)

모델 라이브러리를 임시 디렉토리에 클론하고 감사합니다. 절대 건너뛰지 마십시오.

mkdir /tmp/engine-research && cd /tmp/engine-research
git clone <model-library-url>

가이드의 Phase 0.2에 있는 grep 검색을 클론된 소스와 그 전이 의존성에 대해 실행합니다. 다음을 포함하는 문서화된 의존성 감사 결과를 생성합니다:

1. PyPI 패키지와 비PyPI 패키지 구분
2. 필요한 PyInstaller 지시문 (--collect-all, --copy-metadata, --hidden-import)
3. 번들링해야 하는 런타임 데이터 파일
4. 고정 빌드에서 환경 변수 재정의가 필요한 네이티브 라이브러리 경로
5. 필요한 몽키 패치 (torch.load, float64, MPS, HF 토큰)
6. 샘플 레이트
7. 모델 다운로드 방법 (from_pretrained vs snapshot_download + from_local)

진행하기 전에 임시 가상 환경에서 CPU로 모델 로딩 및 생성을 테스트합니다.

3. 구현 (Phases 1–4)

가이드의 단계를 순서대로 따릅니다. 수정해야 할 주요 파일:

백엔드 (Phase 1):

• backend/backends/<engine>_backend.py 생성
• backend/backends/__init__.py에 등록 (ModelConfig + TTS_ENGINES + 팩토리)
• backend/models.py의 정규식 업데이트

프론트엔드 (Phase 3):

• app/src/lib/api/types.ts — 엔진 유니온 타입
• app/src/lib/constants/languages.ts — ENGINE_LANGUAGES
• app/src/components/Generation/EngineModelSelector.tsx — ENGINE_OPTIONS, ENGINE_DESCRIPTIONS
• app/src/lib/hooks/useGenerationForm.ts — Zod 스키마, 모델 이름 매핑
• app/src/components/ServerSettings/ModelManagement.tsx — MODEL_DESCRIPTIONS

의존성 (Phase 4):

• backend/requirements.txt
• justfile (setup-python, setup-python-release 타겟)
• .github/workflows/release.yml
• Dockerfile (해당되는 경우)

4. PyInstaller 번들링 (Phase 5)

backend/build_binary.py에 엔진 등록:

• 백엔드 모듈 및 모델 패키지용 --hidden-import
• inspect.getsource를 사용하거나 데이터 파일, 네이티브 라이브러리를 제공하는 패키지용 --collect-all
• importlib.metadata를 사용하는 패키지용 --copy-metadata

엔진에 네이티브 데이터 경로가 있는 경우, backend/server.py의 if getattr(sys, 'frozen', False): 블록 내에 os.environ.setdefault()를 추가합니다.

5. 개발 모드에서 확인

just dev

전체 체인을 테스트합니다: 모델 다운로드 → 로드 → 생성 → 음성 복제.

6. 체크리스트 사용

tts-engines.mdx 하단의 구현 체크리스트를 살펴봅니다. 사용자에게 빌드를 전달하기 전에 모든 항목이 확인되어야 합니다.

주요 교훈 (v0.2.3에서)

다음은 가장 일반적인 실패 모드입니다. Phase 0 조사는 이 모든 것을 발견합니다:

패턴	고정 빌드 증상	수정 방법
@typechecked / inspect.getsource()	"could not get source code"	--collect-all <package>
패키지가 사전 훈련된 모델 파일을 제공함	.pth.tar, .yaml에 대한 FileNotFoundError	--collect-all <package>
하드코딩된 시스템 경로가 있는 C 라이브러리	/usr/share/...에 대한 FileNotFoundError	--collect-all + server.py의 환경 변수
importlib.metadata.version()	"No package metadata found"	--copy-metadata <package>
map_location 없는 torch.load	CPU 빌드에서 CUDA 장치를 사용할 수 없음	torch.load 몽키 패치
float64 데이터에 대한 torch.from_numpy	dtype 불일치 RuntimeError	.float()으로 캐스팅
HF 다운로드 호출의 token=True	저장된 HF 토큰 없음 인증 실패	snapshot_download(token=None) + from_local() 사용

참고 사항

• 라우트 및 서비스 레이어에는 엔진별 디스패치 지점이 없습니다. main.py는 변경이 필요 없습니다.
• backends/__init__.py의 모델 설정 레지스트리는 모든 디스패치를 자동으로 처리합니다.
• backends/base.py의 get_torch_device()와 model_load_progress()를 사용하세요. 장치 감지 또는 진행 상황 추적을 다시 구현하지 마십시오.
• 항상 깨끗한 HuggingFace 캐시(개발 중 미리 다운로드된 모델 없음)로 테스트하십시오.
• 푸시하거나 릴리스를 생성하지 마십시오. 사용자에게 빌드를 전달하여 로컬 테스트를 진행하십시오.