English · 한국어

ursoTTS: 보이스 클로닝과 텍스트 음성 변환

내 목소리로, 원하는 만큼 다시 만들어 보세요.
영상 크리에이터를 위한 보이스 클로닝 내레이션 도구입니다. Claude Code로 개발했습니다.

Built with Claude Code Python 3.10+ MIT 라이선스 영어와 한국어

빠른 시작 · 웹 UI · 발음 · 매뉴얼

--- **ursoTTS™는 영상 크리에이터를 위한 보이스 클로닝 일괄 내레이션 도구입니다.** 대본을 텍스트 파일로 작성하고 목소리를 한 번 녹음하면, 영상마다 필요한 내레이션과 자막을 WAV 및 MP3 파일로 만들 수 있습니다. 오픈소스 모델을 내 컴퓨터에서 실행하므로 글자 수에 따라 요금을 내지 않아도 됩니다. 데스크톱 앱, 웹 브라우저, 명령줄에서 사용할 수 있습니다. [@ursomics](https://youtube.com/@ursomics)의 영어·한국어 생물정보학 영상 시리즈를 위해 만들었으며, Claude Code로 개발했습니다. 📖 **처음 사용하시나요? [매뉴얼](docs/MANUAL.ko.md)을 확인해 보세요.** VS Code, 데스크톱 앱 또는 CLI에서 Claude Code를 이용한 설치부터 웹 UI와 터미널 명령어 사용, 대본 작성과 발음 수정까지 안내합니다.

ursoTTS 웹 UI: Speak, Pronunciation, Batch 탭
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-사용하기)에 단계별로 있습니다. ### 데스크톱 앱으로

ursoTTS 데스크톱 앱: Speak, Pronunciation, Batch, Claude Code 화면

```bash ursotts app ``` 같은 Speak, Pronunciation, Batch 기능을 VS Code Dark 스타일의 일반 창에서 씁니다. 액티비티 바, 크기 조절되는 사이드바, 줄 번호가 있는 대본 편집기, 실시간 기록이 보이는 OUTPUT 패널이 있습니다. 내장된 **Claude Code** 화면에서 말로 요청해 앱의 모양과 기능을 바꿀 수 있고, 한 번에 되돌릴 수도 있습니다. [매뉴얼](docs/MANUAL.ko.md#7-ursotts-데스크톱-앱-쓰기)을 참고하세요. ### 터미널에서 ```bash ursotts preview scripts/02_intro_ko.txt # 나뉜 덩어리, 언어, 쉼 확인 (소리 없음) ursotts say "Hello from Ursomics." -o output/hello.wav ursotts batch scripts output # scripts/의 모든 대본 생성 ``` 대본 `name.txt` 하나마다 `batch`가 만드는 파일: ``` output/name.wav output/name.mp3 output/name.srt output/batch_report.json ``` `batch`를 다시 실행하면 텍스트와 설정이 바뀌지 않은 대본은 건너뜁니다. 전부 다시 만들려면 `--force`를 붙이세요. 문장 캐시 덕분에 그래도 빠릅니다. ## 목소리 샘플 녹음하기 녹음 파일을 `voices/`에 넣고 `config.yaml`에 적습니다: ```yaml voices: en: voices/my_voice_en.wav ko: voices/my_voice_ko.wav ``` 목소리를 잘 복제하려면 다음을 참고하세요. - 영상과 같은 말투로 **10~30초** 동안 자연스럽게 말하세요. - 조용한 곳에서 배경 음악 없이 혼자 녹음하고, 마이크와의 거리를 일정하게 유지하세요. - 언어마다 샘플을 하나씩 녹음하세요. 한국어는 한국어 녹음으로 클로닝해야 가장 자연스럽습니다. - WAV가 가장 좋고, MP3도 됩니다. 설정에 등록한 샘플 파일이 없으면 ursoTTS가 실행되지 않습니다. 덕분에 실수로 다른 사람의 목소리로 일괄 생성하는 일을 막을 수 있습니다. ## 발음 대문자 약어는 자동으로 철자를 풀어 읽습니다. `DNA`는 영어로 `D.N.A.`, 한국어로 `디엔에이`가 됩니다. 나머지는 `pronunciations.yaml`에 적습니다: ```yaml en: CD8: C.D. eight # 글자: 대문자 하나마다 점 NANOG: {say: NAN.og, like: "NAN as in man, og as in dog"} # 점은 음절을 한 단어로 연결 RNA-seq: R.N.A. seek ko: GATA6: 가타식스 # 한국어: 한글로 읽는 법을 적습니다 ``` 한영 혼합 대본이라면 맨 위에 `@lang ko`를 쓰세요. 영어 용어가 많은 한국어 문장도 한국어 목소리와 `ko:` 사전으로 일정하게 읽힙니다([한영 혼합 대본의 발음](docs/MANUAL.ko.md#한영-혼합-대본의-발음)). 유전자 이름이 가득한 테스트 대본이 `examples/`에 있습니다. 소리를 Claude에게 설명하는 방법을 포함한 전체 안내는 [매뉴얼](docs/MANUAL.ko.md#93-발음-고치기)을 보세요. ## 스크립트 형식 ```text # #으로 시작하는 줄은 메모이며 읽지 않습니다. @lang auto (선택: 파일 전체를 en / ko로 고정) Welcome to Ursomics. Today we run scRNA-seq QC with Claude Code. 먼저 데이터를 불러옵니다. [pause 0.8] 그다음 미토콘드리아 비율을 확인합니다. ``` ## 목소리 조정 (`config.yaml`) | 설정 | 웹 UI 이름 | 효과 | |---|---|---| | `exaggeration` | Expressiveness | 0.3 = 차분한 강의, 0.5 = 기본, 0.7 이상 = 생동감 | | `cfg_weight` | Pacing | 낮을수록(~0.3) 느리고 또박또박 | | `temperature` | Variation | 높을수록 말투가 다양해짐 | | `seed` | Seed | 바꾸면 같은 텍스트의 다른 버전이 나옴 | | `max_chars` | — | 덩어리가 작을수록 긴 대본에서 말투가 안정적 | ## 하드웨어 | 환경 | 참고 | |---|---| | NVIDIA GPU (CUDA) | 가장 빠름 | | Apple Silicon Mac | 됨(`mps`), 더 느림 | | CPU만 | 되지만 느림. 짧은 클립에는 충분 | | 클라우드 GPU (RunPod, Colab 등) | 시간 단위로 빌려 한 번에 많은 대본을 생성 | ## 책임감 있게 사용하기 **본인의 목소리**나 명시적인 사용 허락을 받은 목소리만 클로닝하세요. Chatterbox는 생성한 오디오에 들리지 않는 워터마크를 넣습니다. 워터마크를 제거하지 마세요. `ursotts ui --share`는 임시 공개 링크를 만드니, 의도한 경우에만 쓰세요. ## 기여하기 다음과 같은 기여를 환영합니다. - [ ] 대체 백엔드로 CosyVoice2 엔진(Apache 2.0) - [ ] 대화·인터뷰를 위한 줄 단위 목소리 전환 - [ ] 자동 감지 언어 추가(현재 영어와 한국어) 새 엔진을 추가하려면 `ursotts/engine.py`의 `BaseEngine`을 상속하면 됩니다. pull request를 보내기 전에 `ursotts batch scripts output --engine dummy`를 실행해 전체 처리 과정이 정상 동작하는지 확인해 주세요. ## 라이선스 MIT © 2026 Ursus (@ursomics). Chatterbox는 © Resemble AI, MIT 라이선스입니다. 함께 들어 있는 **Poppins** 글꼴은 © The Poppins Project Authors이며, SIL Open Font License 1.1을 따릅니다(`ursotts/assets/fonts/OFL.txt`). `docs/brand/`의 ursoTTS 이름, 로고, 곰 그림은 © 2026 Ursus (@ursomics)이며 MIT 라이선스 대상이 아닙니다. 이 프로젝트는 Anthropic과 제휴 관계가 없으며, Anthropic의 후원을 받지 않습니다. Claude와 Claude Code는 Anthropic의 상표입니다. ---

ursoTTS 곰
Made with ursoTTS bear by ursomics@GitHub · ursomics.com · @ursomics