local-korean-xtts-engine — 한국어 숏츠용 로컬 TTS 엔진
개요
한국어 숏츠 내레이션을 위한 로컬 one-take XTTS-v2 엔진. 기존 멀티링구얼 TTS의 한국어 한계를 해소하기 위해 한국어 전용 전처리 + 로컬 실행 조합으로 설계된 오픈소스 프로젝트.
GitHub: sinmb79/local-korean-xtts-engine License: MIT | 언어: TypeScript 72%, Python 22%, PowerShell 6% | Stars: 9
기존 TTS의 한국어 문제점
- 중국어처럼 들리는 발음
- 문장보다 토큰 단위로 끊기는 호흡
- 말끝 잡음과 tail artifact
- 외부 SaaS 정책 의존으로 저장/편집/재렌더 불편
핵심 기능
| 기능 | 설명 |
|---|---|
| one-take 합성 | scene별 TTS 이어붙이지 않고 master narration.wav 한 번에 생성 |
| 한국어 clause chunking | 한국어 호흡을 살린 최소한의 문장 흐름 보존 |
| tail cleanup | 말끝 잡음 제거 |
| 다중 reference WAV | 같은 화자의 여러 레퍼런스를 골드 스타일 팩으로 묶어 사용 |
| 속도 제어 | --speed 1.13 등 숏츠 기준 속도 반영 |
| 레벨 정규화 | --target-peak 0.92 --target-rms 0.12로 음색 드리프트 최소화 |
| 후처리 프리셋 | --post-preset issue-shorts-dad 등 preset 내장 |
| Windows 호환 | Python 3.11 + CUDA 런타임 자동 설치 스크립트 |
아키텍처
Korean script → One-take text normalizer → Node CLI → Python XTTS wrapper → XTTS-v2 → master narration.wav
Reference voice.wav ────────────────────────────────────────────────────────────────────────────────┘
설치 및 사용
1. 런타임 설치 (Windows)
pwsh -ExecutionPolicy Bypass -File .\scripts\setup_local_korean_tts.ps1- Python 3.11 전용 가상환경
.venv-local-korean-tts - CUDA 경로 감지 시
torch 2.11.0+cu128자동 설치 TTS==0.22.0,transformers==4.41.2
2. reference WAV 준비
- 10초 이상, 배경음악 없는 mono/stereo WAV
- 한국어 발음이 또렷한 음성
3. 합성 실행
npm run synth -- `
--text-file .\examples\sample-script.ko.txt `
--output .\out.wav `
--reference C:\voices\reference.wav `
--device cuda `
--speed 1.13 `
--max-line-length 24 `
--target-peak 0.92 `
--target-rms 0.12 `
--post-preset issue-shorts-dad설계 원칙
- one-take 우선: 같은 화자가 이어지는 본문은 scene별 TTS를 이어붙이지 않음. master narration.wav 먼저 만들고 영상 컷 뒤에 맞춤
- 한국어 전처리 엔진 앞단: 줄바꿈 정리, 다중 공백 정리, 문장 종결부 정리, one-take에 맞는 최소한의 문장 흐름 보존
- Windows 실전 호환성: Windows + Python 3.11 + XTTS-v2 + PyTorch 2.11 계열에서 실제 검증.
torchaudio.load()Windows 문제를soundfile기반 로더로 우회
다음 단계 (roadmap)
- 긴 한국어 문장을 더 안전하게 처리하는 clause chunker
- F5-TTS backend adapter
- ffmpeg 후처리 preset 내장
주의
- 음성 복제의 책임 있는 사용 전제
- 본인 권한 있는 음성만 사용
- 공개 저장소에 reference WAV 올리지 말 것