로컬 한국어 XTTS 엔진

English README

한국어 숏츠 내레이션을 위해 만든 로컬 one-take XTTS-v2 엔진입니다.
핵심 목표는 세 가지입니다.

• 내 목소리 reference를 그대로 쓴다
• 한국어 호흡을 살린 one-take 본문을 만든다
• 외부 SaaS 정책에 덜 묶이고, 로컬에서 재현 가능하게 돌린다

이 저장소는 민감한 사용자 음성 자산을 포함하지 않습니다.
직접 준비한 reference WAV를 넣어 사용해야 합니다.

왜 이 프로젝트가 필요한가

기존 멀티링구얼 TTS는 한국어에서 이런 문제가 자주 생깁니다.

• 중국어처럼 들리는 발음
• 문장보다 토큰 단위로 끊기는 호흡
• 말끝 잡음과 tail artifact
• 외부 서비스 정책 때문에 저장, 편집, 재렌더가 불편한 구조

이 프로젝트는 한국어 전처리 + XTTS-v2 + 로컬 one-take 조합으로 그 문제를 줄이는 데 초점을 둡니다.

구조

flowchart TD
  A["Korean script"] --> B["One-take text normalizer"]
  B --> C["Node CLI / helper"]
  C --> D["Python XTTS wrapper"]
  D --> E["XTTS-v2"]
  E --> F["Master narration.wav"]
  G["Reference voice.wav"] --> D

Loading

포함된 것

• src/index.ts 한국어 one-take 정형화와 Python wrapper 호출
• src/cli.ts 바로 실행 가능한 Node CLI
• scripts/local_korean_xtts.py XTTS-v2 inference wrapper
• scripts/setup_local_korean_tts.ps1 Windows용 런타임 설치 스크립트

빠른 시작

1. 런타임 설치

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 install
npm run synth -- --text-file .\examples\sample-script.ko.txt --output .\out.wav --reference C:\path\to\reference.wav

추가 옵션:

• --reference <wav>를 여러 번 반복 같은 화자의 여러 reference를 함께 넣어 골드 스타일 팩처럼 묶어 사용할 수 있습니다.
• --speed 1.13 숏츠 기준 원래 레퍼런스의 말하기 속도를 direct synth 결과에도 그대로 반영합니다.
• --max-line-length 26 한국어 clause를 더 짧게 끊어 자막과 호흡용 줄바꿈을 더 보수적으로 잡습니다.
• --target-peak 0.92 --target-rms 0.12 기존 Chatter 기준선과 비슷하게 reference WAV 레벨을 정규화해서 음색 드리프트를 줄입니다.
• --post-preset issue-shorts-dad Issue Shorts Studio에서 쓰는 아빠 shorts contour를 후처리로 바로 적용합니다.
• --no-tail-cleanup 말끝 tail cleanup을 끄고 raw XTTS 출력에 가깝게 확인할 때 사용합니다.

CLI 예시

npm run synth -- `
  --text-file .\examples\sample-script.ko.txt `
  --output .\out.wav `
  --reference C:\voices\boss-reference.wav `
  --reference C:\voices\boss-shorts-gold.wav `
  --device cuda `
  --speed 1.13 `
  --max-line-length 24 `
  --target-peak 0.92 `
  --target-rms 0.12 `
  --post-preset issue-shorts-dad

설계 원칙

1. one-take 우선

같은 화자가 이어지는 본문은 scene별 TTS를 이어붙이지 않습니다.
먼저 master narration.wav를 만들고, 영상 컷은 그 뒤에 맞춥니다.

2. 한국어 전처리는 엔진 앞단에서 해결

• 줄바꿈 정리
• 다중 공백 정리
• 문장 종결부 정리
• one-take에 맞는 최소한의 문장 흐름 보존

3. Windows 실전 호환성

이번 저장소에서는 아래 조합으로 실제 검증했습니다.

• Windows
• Python 3.11
• XTTS-v2
• transformers==4.41.2
• PyTorch 2.11 계열

또한 XTTS 내부의 torchaudio.load() 경로가 Windows에서 torchcodec 문제를 일으킬 수 있어, wrapper에서 soundfile 기반 로더로 우회합니다.

시스템 이해용 다이어그램

sequenceDiagram
  participant U as User
  participant N as Node CLI
  participant P as Python Wrapper
  participant X as XTTS-v2

  U->>N: text-file + output + reference
  N->>N: normalize Korean one-take text
  N->>P: spawn python wrapper
  P->>X: load model + reference voice
  X-->>P: synthesized waveform
  P-->>N: output wav path
  N-->>U: master narration.wav

Loading

주의 사항

• 이 저장소는 음성 복제의 책임 있는 사용을 전제로 합니다.
• 본인이 권한을 가진 음성만 사용하세요.
• 공개 저장소에 reference WAV를 함께 올리지 마세요.

다음 단계

• 긴 한국어 문장을 더 안전하게 처리하는 clause chunker
• F5-TTS backend adapter
• ffmpeg 후처리 preset 내장