zeroshot-tts

zeroshot-tts는 docx, hwpx, hwp, pptx, pdf 문서에서 텍스트를 뽑아 당신이 직접 녹음한 목소리로 읽어 주는 하네스입니다. 유료 API도, 서버도, 프론트엔드도 쓰지 않습니다. 무료 오픈소스 모델을 당신의 맥에서 그대로 실행합니다.

먼저 분명히 해 둘 것이 있습니다. 이 하네스는 완성된 제품이 아니라 실험용 템플릿입니다. 품질은 어떤 모델을 고르는지, 참조음성을 얼마나 깨끗하게 녹음했는지, 문서가 얼마나 긴지에 따라 크게 달라집니다. 특히 긴 문서에서 청크 경계의 음색이 미세하게 달라지는 문제는 현재 오픈소스 제로샷 TTS의 구조적 한계라서 완전히는 사라지지 않습니다. 이 점은 알려진 한계에서 솔직하게 다룹니다.

무엇을 하나

문서 한 편을 텍스트 추출 단계부터 최종 mp3 단계까지 파이프라인으로 연결합니다.

문서(docx/hwpx/hwp/pptx/pdf) ──▶ 텍스트 추출 ──▶ 한국어 전처리·청킹
                                                    │
   당신의 녹음 ──▶ 참조 클립 준비 ──▶ 로컬 TTS 모델(자기 목소리 클로닝)
                                                    │
                              청크별 합성 ──▶ 조립(크로스페이드·음량정규화) ──▶ mp3/wav

다섯 가지 정체성 제약

이 하네스는 다섯 제약을 바탕으로 합니다. 여기서 벗어나면 프로젝트의 의미가 없어집니다.

1. 무료이고 로컬에서 실행되며 오프라인으로 동작하는 도구만 씁니다. CLOVA나 ElevenLabs 같은 유료 API를 쓰거나 서버를 구축하지 않습니다. 가중치는 최초 한 번만 내려받고 그 뒤로는 인터넷 없이 동작합니다.
2. 목적은 당신의 목소리를 재현하는 제로샷 클로닝입니다. 정해진 성우 목소리로 읽어 주는 고정 화자 TTS는 목적에 맞지 않습니다.
3. Apple Silicon 맥을 기준으로 설계했고, 한국어와 영어를 다룹니다. CPU로도 동작하지만 느립니다.
4. 참조음성은 개인 생체정보입니다. 로그에 남기지 않고, 커밋하지 않고, 외부로 올리지 않습니다.
5. 청크 경계의 이음매는 구조적 한계입니다. 이 한계를 완화하되 과장하지 않고 있는 그대로 알립니다.

어디서부터 보면 되나

• 처음 쓰는 분은 세팅과 모델 선택으로 환경을 감지하고 맞는 모델을 고른 다음, 참조음성 준비로 자기 목소리를 담습니다.
• 어떤 모델이 좋은지부터 궁금한 분은 모델 비교의 결정 트리로 곧장 갑니다.
• 전체 흐름이 궁금한 분은 문서에서 음성까지에서 다섯 단계가 어떻게 이어지는지 봅니다.
• 도입 전에 한계부터 확인하려는 분은 알려진 한계를 먼저 읽습니다.

다른 base와 다른 점

다른 base는 판매를 전제한 상업용 템플릿이지만, zeroshot-tts는 실험적이고 개인 용도를 전제합니다. 진입 역할은 CLAUDE.md의 정체성 제약과 트리거 규칙, 그리고 zeroshot-tts-orchestrator 스킬이 나누어 담당합니다. “docx를 내 목소리로 읽어줘”처럼 말하면 오케스트레이터가 세팅부터 조립까지 각 단계를 에이전트에 위임합니다.

다음

처음이라면 세팅과 모델 선택으로 갑니다. 모델부터 정하고 싶으면 모델 비교로, 한계가 먼저라면 알려진 한계로 갑니다.