---
**ursoTTS™는 영상 크리에이터를 위한 보이스 클로닝 일괄 내레이션 도구입니다.** 대본을 텍스트 파일로 작성하고 목소리를 한 번 녹음하면, 영상마다 필요한 내레이션과 자막을 WAV 및 MP3 파일로 만들 수 있습니다. 오픈소스 모델을 내 컴퓨터에서 실행하므로 글자 수에 따라 요금을 내지 않아도 됩니다. 데스크톱 앱, 웹 브라우저, 명령줄에서 사용할 수 있습니다.
[@ursomics](https://youtube.com/@ursomics)의 영어·한국어 생물정보학 영상 시리즈를 위해 만들었으며, Claude Code로 개발했습니다.
📖 **처음 사용하시나요? [매뉴얼](docs/MANUAL.ko.md)을 확인해 보세요.** VS Code, 데스크톱 앱 또는 CLI에서 Claude Code를 이용한 설치부터 웹 UI와 터미널 명령어 사용, 대본 작성과 발음 수정까지 안내합니다.
Speak: 내 목소리로 내레이션 생성 · Pronunciation: 표기를 귀로 비교 · Batch: 폴더 전체 생성
## ursoTTS를 쓰는 이유
클라우드 보이스 클로닝 서비스는 생성하는 글자 수에 따라 요금을 부과합니다. 영상이 수백 편에 이르는 시리즈라면 비용이 빠르게 늘어날 수 있습니다. ursoTTS는 [Chatterbox](https://github.com/resemble-ai/chatterbox)(Resemble AI, MIT 라이선스)를 내 컴퓨터에서 실행합니다. 설치를 마치면 추가 비용은 GPU 사용 시간뿐입니다.
## 주요 기능
- **웹 UI.** 텍스트를 붙여 넣고, 브라우저에서 목소리 샘플을 녹음하거나 올리고, 슬라이더로 말투를 조정한 뒤 결과를 내려받습니다.
- **일괄(batch) 모드.** 대본 폴더를 지정하면 대본마다 내레이션 하나씩을 만듭니다.
- **두 언어 지원.** 영어와 한국어를 **문장마다** 감지하므로 한국어·영어가 섞인 대본도 됩니다. 언어마다 다른 목소리 샘플을 쓸 수 있습니다.
- **필요한 부분만 다시 생성.** 대본이나 설정이 바뀐 경우에만 작업하며, 바뀐 문장만 다시 만듭니다. 10분짜리 대본도 오타가 있는 문장만 몇 초 안에 고칠 수 있습니다.
- **자막 포함.** 내레이션 타이밍에 맞춘 `.srt` 파일이 함께 나오며, 원래 표기를 그대로 유지합니다(발음용 표기가 아니라 `scRNA-seq`).
- **매끄러운 약어.** `DNA`, `ATP` 같은 대문자 약어를 글자마다 자연스럽게 읽습니다. 영어는 `D.N.A.`, 한국어는 `디엔에이`. `config.yaml`에서 `spell_acronyms: false`로 끌 수 있습니다.
- **전문 용어의 정확한 발음.** 유전자 이름과 도구 이름을 어떻게 읽을지 정할 수 있습니다(`CD8: C.D. eight`, `NANOG: NAN.og`, `GATA6: 가타식스`). 영어와 한국어로 생물정보학 용어 약 60개가 기본으로 들어 있습니다.
- **발음 실험실.** 웹 UI에서 까다로운 단어의 여러 표기를 직접 들어 비교하고, 가장 좋은 것을 저장합니다.
- **쉼 조절.** 대본 어디에나 `[pause 1.5]`를 쓰면 됩니다. 빈 줄은 문단 사이 쉼이 됩니다.
- **유튜브용 MP3.** 음량을 -14 LUFS로 맞춰 내보냅니다.
- **같은 결과 재현.** seed를 고정하면 다시 만들어도 같은 말투가 나옵니다.
- **테스트 엔진.** `--engine dummy`로 GPU 없이 대본과 타이밍을 확인합니다.
## 활용 예
- **유튜브 튜토리얼과 강의:** 화면 녹화와 슬라이드에 내 목소리로 내레이션을 입힙니다.
- **논문 요약과 저널 클럽:** 논문을 짧은 영상이나 오디오 요약으로 만듭니다.
- **온라인 강좌와 실험실 교육:** e-러닝 모듈, 프로토콜·SOP 안내, 새 연구원 교육 자료.
- **발표:** 슬라이드 음성 해설, 학회 발표 녹화, 포스터 소개 영상, 참석하지 못하는 랩 미팅 발표.
- **발표 연습:** 발표 대본을 미리 들어 보고 시간을 확인합니다.
- **팟캐스트와 오디오 버전:** 블로그 글, 뉴스레터, 내가 쓴 글을 오디오로 바꿉니다.
- **두 언어 콘텐츠:** 같은 화면으로 영어판과 한국어판을 만듭니다.
- **짧은 영상:** 유튜브 쇼츠, 인스타그램 릴스, 틱톡 내레이션.
- **제품·앱 소개:** 데모 영상, 사용 안내, 업데이트 소개.
- **접근성:** 문서의 오디오 버전과, 읽으며 보는 사람을 위한 자막.
본인의 목소리나 사용 허락을 받은 목소리만 클로닝하세요.
## 앱 다운로드 (Python 설치 불필요)
[최신 릴리스](https://github.com/ursomics/ursotts/releases/latest) 페이지에서 운영체제에 맞는 설치 파일을 다운로드하세요.
| 컴퓨터 | 파일 | 설치 |
|---|---|---|
| **Mac** (Apple Silicon) | `ursoTTS-1.0.0-mac-arm64.dmg` | 파일을 열고 **ursoTTS** 아이콘을 **응용 프로그램(Applications)** 폴더로 드래그하세요. |
| **Windows** (64비트) | `ursoTTS-1.0.0-windows-setup.exe` | 설치 파일을 실행한 뒤 안내에 따라 설치하세요. |
- **처음 열 때:** 아직 유료 개발자 인증서로 서명되지 않아 처음 한 번 직접 허용해야 합니다. Mac: ursoTTS를 연 뒤 **시스템 설정 → 개인정보 보호 및 보안 → 그래도 열기**. Windows: SmartScreen 창에서 **추가 정보** → **실행**. 두 과정 모두 [스크린샷과 함께 단계별로 안내](docs/MANUAL.ko.md#72-python-없이-설치하기-dmg--exe)합니다.
- **첫 내레이션**을 만들 때 목소리 모델(몇 GB)을 한 번 내려받으므로, 처음에는 인터넷 연결이 필요합니다.
- 내 파일은 홈 폴더의 **`ursoTTS`** 폴더에 있습니다. 목소리 샘플은 `voices/`, 대본은 `scripts/`에 넣고, 결과는 `output/`에서 찾으세요.
명령줄이나 웹 UI를 사용하려면 아래 안내에 따라 소스 코드에서 설치하세요.
## 빠른 시작
프로젝트 이름은 **ursoTTS**이고, 입력하는 명령어는 `ursotts`입니다.
테스트 환경:
| 운영체제 | Python 버전 | 테스트 범위 |
|---|---:|---|
| macOS (Apple Silicon) | 3.13 | 실제 목소리 모델을 사용해 전체 기능 테스트, 설치 파일(.dmg) 포함 |
| Linux (Ubuntu) | 3.10–3.13 | 업데이트마다 명령줄, 웹 UI, 생성 과정을 테스트 엔진으로 자동 테스트 |
| Linux (Ubuntu) | 3.12 | 데스크톱 앱, 설치 파일 빌드, 실행 아이콘을 테스트 엔진으로 확인 |
| Windows (64비트) | 3.11(설치 파일에 포함) | 설치 파일(.exe)로 설치해 실제 사용 확인 |
Python 3.10 이상이면 됩니다. Linux에서는 목소리 모델 자체를 아직 테스트하지 않았습니다. 사용해 보신 결과를 알려 주시면 반영하겠습니다.
```bash
# 1. 프로젝트 받기: ursotts.zip을 풀거나, 다음을 실행합니다
# git clone https://github.com//ursotts.git
# "ursotts" 폴더는 iCloud, OneDrive, Dropbox가 동기화하지 않는 곳
# (예: ~/Projects/)에 두세요. 용량이 큰 .venv와 캐시 폴더를 동기화하면
# 동기화가 느려지고 환경이 망가질 수 있습니다.
# 그다음 폴더 안으로 들어갑니다. ursotts 명령은 항상 여기서 실행하세요.
# 현재 폴더의 config.yaml(목소리 설정)을 읽기 때문입니다:
cd ~/Projects/ursotts
# 2. 가상환경을 만들고 전체(CLI + 웹 UI)를 설치합니다
python3.13 -m venv .venv
source .venv/bin/activate # 새 터미널을 열 때마다 실행
pip install -e ".[all]"
# 3. voices/에 목소리 샘플을 넣고(아래 참고) 설치를 확인합니다
ursotts check
```
처음 실제로 실행할 때 Hugging Face에서 Chatterbox 모델 가중치(몇 GB)를 내려받습니다.
## 사용 방법
### 브라우저에서
```bash
ursotts ui
```
브라우저에서 **http://127.0.0.1:7860**이 열립니다. 내 컴퓨터에서만 실행되며 파일이나 음성이 외부로 전송되지 않습니다.
시스템에 설정된 라이트 모드 또는 다크 모드에 맞춰 표시됩니다.
- **Speak 탭:** 대본을 붙여 넣고, 언어와 언어별 저장된 목소리를 고른 뒤 **Generate narration**을 누릅니다. 새 목소리를 쓰려면 *Record or upload a new sample*을 고르고 10~30초 녹음한 뒤 **Save to my voices**로 저장하세요. **Speaking style**에서 표현력, 속도, 변화를 조정합니다. 결과는 `output/ui/`에 저장됩니다.
- **Pronunciation 탭:** 한 단어의 여러 표기를 나란히 듣고 가장 좋은 것을 저장합니다.
- **Batch 탭:** 대본 폴더와 출력 폴더를 고르거나 새로 만든 뒤 전체를 만듭니다. `ursotts batch`와 같습니다.
탭마다 쓰는 법은 [매뉴얼](docs/MANUAL.ko.md#6-웹-ui-사용하기)에 단계별로 있습니다.
### 데스크톱 앱으로