start.bat 더블클릭만으로 쓸 수 있게 포장했다는 점이다. v4.0에서 설치기를 uv로 갈아엎어 관리자 권한 없이도 돌아가고, CUDA Toolkit·Visual Studio 빌드 도구도 더 이상 필요 없다. 처리·저장은 전부 내 컴퓨터 안에서 일어나고, 클라우드(Azure)는 내 키를 넣었을 때만 선택적으로 쓴다.
abus-aikorea/voice-pro · 라이선스 LGPL · 버전 4.0.0(2026-07-13) · 형식 Gradio 6 웹앱 · 언어 Python 3.12 · 런타임 Torch 2.8.0+cu128 · 파일 약 507개(파이썬 232개) · 코드 규모 app/ 약 12,600줄 + src/ 약 13,700줄 + 벤더링된 cosyvoice/ 약 11,700줄 · 대상 Windows + NVIDIA GPU(검증) · TrendShift Daily #14)
voice-pro는 "유튜브 링크나 미디어 파일을 하나 넣으면, 배경음 분리 → 음성인식(자막) → 번역 → 목소리 복제 더빙까지 이어지는 다국어 더빙 파이프라인을, 최신 오픈소스 음성 모델들을 엮어 하나의 Gradio 웹 화면에서 돌려 주는 데스크탑 웹앱"이다. 한마디로 "영상 한 편을 내 PC 안에서 다른 언어로 다시 말하게 만드는 올인원 스튜디오"다. 성우를 부르거나 상용 API에 돈을 쓰는 대신, 내 그래픽카드로 돌린다.
외화 한 편을 더빙하려면 원래 여러 전문가가 릴레이로 붙는다. 먼저 음향 엔지니어가 배경음악과 대사를 분리하고, 속기사가 대사를 받아 적고, 번역가가 자막을 옮기고, 성우가 그 언어로 다시 연기하고, 마지막에 믹싱으로 합친다. 각 단계마다 사람·장비·비용이 든다.
voice-pro는 이 릴레이를 전부 소프트웨어 모듈로 바꿔 노트북 한 대에 넣었다. 음향 엔지니어 자리엔 Demucs(음원 분리), 속기사 자리엔 Whisper(음성인식), 번역가 자리엔 번역 엔진, 성우 자리엔 F5-TTS·CosyVoice(목소리 복제) 같은 오픈소스 모델이 앉는다. 그리고 이 모든 자리를 웹 화면의 탭 몇 개로 이어 붙여, 오퍼레이터 한 명이 버튼만 눌러도 "원본 영상 → 한국어 더빙 영상"이 나오게 했다. 이 레포의 진짜 가치는 새 AI 모델을 발명한 게 아니라, 흩어져 있던 최고의 모델들을 '한 번에 돌아가게' 포장한 통합·설치 엔지니어링에 있다.
GradioGulliver다. 각 단계는 독립 모듈이라 "받아쓰기만" 혹은 "번역만" 따로 쓸 수도 있다.127.0.0.1:7870)에서 클릭만 하면 된다.사용자가 Dubbing Studio 탭에서 유튜브 URL을 넣고 "다운로드 → 자막 → 번역 → 더빙"을 순서대로 누를 때, 내부에서 벌어지는 일을 압축하면 이렇다:
이 사슬 전체가 한 화면(Dubbing Studio)에 들어 있고, 중간 단계만 떼어 쓰는 전용 탭(Whisper 자막·Translation·Speech Generation)도 따로 있다. 다음 장에서 "왜 이게 지금 뜨는가"를 본다.
2026년 현재 음성 AI 모델은 넘쳐난다. Whisper, F5-TTS, CosyVoice, kokoro… 다 오픈소스로 공짜다. 그런데 보통 사람이 이걸 조립해 쓰는 건 지옥이다. CUDA 버전 맞추고, PyTorch 깔고, 모델 가중치 받고, 각 모델 API를 코드로 엮어야 한다. voice-pro가 트렌딩에 오른 이유는 새 모델이 아니라, 바로 이 "조립·설치 지옥을 없앤 통합 패키징" 때문이다.
이번에 순위가 뛴 결정적 계기는 v4.0(2026-07) 리라이트다. 설치기를 Miniconda/pip에서 uv(Rust로 짠 초고속 파이썬 패키지 매니저)로 갈아엎으면서 다음이 가능해졌다.
start.bat이 ffmpeg가 없으면 휴대용 ffmpeg를 자동으로 받아 installer_files/ 안에 넣는다.uv.lock(약 53만 줄, 전 플랫폼 잠금)으로 누구 PC에서든 같은 버전이 깔린다. 모든 게 installer_files/ 한 폴더 안에 격리돼, 문제 생기면 그 폴더만 지우고 다시 돌리면 끝.다른 오픈소스 음성 도구가 "가구를 부품으로 보내 주고 직접 조립하라(설명서 100쪽)"라면, voice-pro v4.0은 "완제품 가구를 문 앞까지 배송, 나사 하나 안 돌려도 됨"이다. 심지어 배송 트럭(uv)이 예전보다 훨씬 빠르다.
과거 voice-pro는 60초 길이 제한이 있는 무료판 + Azure를 얹은 구독판이라는 상용 모델이었다. 그런데 개발사가 WeConnect라는 다른 제품에 집중하게 되면서 "전 코드를 오픈소스로 풀고 완전 무료로, 누구나 자유롭게 배포·수정 가능"하다고 선언했다. 상용 제품 수준으로 다듬어진 도구가 통째로 공개된 셈이라, 별점과 관심이 몰렸다.
| 관점 | voice-pro (로컬 오픈소스) | ElevenLabs 등 클라우드 상용 |
|---|---|---|
| 비용 | 무료 (내 전기·GPU만) | 분량당 과금·월 구독 |
| 프라이버시 | 처리·저장이 전부 내 PC 안. 원본 음성이 밖으로 안 나감 | 음성을 업체 서버로 전송 |
| 범위 | 다운로드·분리·STT·번역·TTS 전 단계 올인원 | 주로 TTS/더빙 일부에 특화 |
| 모델 선택 | ASR 3종·TTS 4종 등 엔진 교체 가능 | 업체가 정한 모델 고정 |
| 진입장벽 | NVIDIA GPU 필요·초기 모델 다운(수 GB) | 회원가입 즉시 사용 |
| 한국어 | Fun-CosyVoice3로 한국어 클로닝 지원 | 지원하나 유료 |
정리하면 voice-pro의 매력은 "클라우드에 돈·데이터를 내주지 않고, 상용 수준 더빙을 내 손안에서"다. 대신 그 대가로 NVIDIA GPU와 초기 대용량 다운로드를 감수해야 한다.
README가 명시하듯, 개발사는 WeConnect 작업으로 voice-pro 업데이트를 당분간 못 한다. 즉 활발히 유지보수되는 프로젝트가 아니라 "잘 만들어 놓고 동결된" 상태에 가깝다. Mac·Linux는 동작 미검증이고 코드가 platform.system()으로 Windows에 크게 분기한다. 테스트 스위트도 없다. "지금 완성도가 높다"와 "앞으로 계속 좋아진다"는 다른 얘기이니, 학습·활용 대상으로 보되 프로덕션 의존은 신중히.
voice-pro는 "자체 개발 코드는 얇고, 검증된 오픈소스 모델을 두껍게 조립"한 구조다. 영역별로 어떤 부품을 썼는지 지도를 그리면 이렇다.
| 엔진 | 버전 | 성격 |
|---|---|---|
| faster-whisper | 1.2.1 | 기본값. CTranslate2 기반으로 빠르고 가벼움. large-v3-turbo·distil-large-v3.5 지원 |
| openai-whisper | 20250625 | 원조 구현. 정확하지만 무거움 |
| whisper-timestamped | 1.15.9 | 단어 단위 타임스탬프(자막 하이라이트용) |
v4.0에서 whisperX가 제거됐다 — 그 의존성(huggingface-hub<1.0 고정)이 Gradio 6 업그레이드를 막았기 때문. 옛 설정에 whisperX가 남아 있으면 자동으로 faster-whisper로 폴백한다.
| 엔진 | 강점 | 클로닝 |
|---|---|---|
| Edge-TTS | 100+ 언어·400+ 목소리, 초경량(MS 엔진 호출) | ✗ |
| kokoro (0.9.4) | HuggingFace TTS Arena 2위급 품질, 작고 빠름 | ✗ |
| F5-TTS (1.1.21) | 제로샷 보이스 클로닝, 파인튜닝 모델 다수(핀·불·힌디·일·러·스페인어 등) | ✓ |
| CosyVoice (E2-TTS 포함) | 다국어 제로샷 클로닝. Fun-CosyVoice3-0.5B는 한국어 포함 9개 언어 | ✓ |
| 영역 | 부품 | 역할 |
|---|---|---|
| 번역 | deep-translator / Azure Translator | 100+ 언어. 무료 Google 경로 또는 내 Azure 키 |
| 문장 정돈 | spaCy (3.8) · stanza | 자연스러운 문장 단위 분절 → 번역·TTS 품질 ↑ |
| 음원 분리 | Demucs 4.0.1 · MDX-Net | 목소리/배경음 분리(htdemucs·htdemucs_ft 모델) |
| 다운로드 | yt-dlp (2025.9.26+) | 유튜브 등에서 영상·오디오 추출 |
| 오디오 처리 | ffmpeg-python · pydub · librosa · soundfile · pyworld | 포맷 변환·자르기·믹싱 |
| 보이스 변환 | RVC (rvc/) | Retrieval-based Voice Conversion(추가 변환기) |
| 자막 | pysubs2 · python-iso639 · lingua | SRT/ASS/SSA 파싱·언어 감지 |
| UI | Gradio 6.20.0 | 웹 화면 전체 |
gpu/cpu extra로 나뉘고 상호 배타적([tool.uv] conflicts). 파이썬 상한이 <3.13인 이유는 kokoro가 아직 3.13을 지원하지 않아서다. 전부 installer_files/ 안의 uv 관리 격리 환경에서 돈다 — 시스템 파이썬을 건드리지 않는다.numba가 numpy<2.5로 상한을 걸고, transformers는 5.13.0에 고정돼 벤더링된 cosyvoice/llm/llm.py에 두 가지 패치(Qwen 인코더 dtype=float32 + 전체 길이 디코드 어텐션 마스크)를 요구한다 — 안 하면 CosyVoice2/3가 조용히 엉뚱한 내용을 합성한다. pyopenjtalk은 Windows wheel이 없어 pyopenjtalk-plus로 대체, pynini/WeTextProcessing도 같은 이유로 wetext(순수 파이썬)로 교체. 이 핀 목록 자체가 "여러 모델을 한 환경에 공존시키는" 통합 노동의 증거다.voice-pro의 코드는 무섭게 많아 보이지만(파이썬 232개 파일), 실제 골격은 아주 단순한 3계층 규칙과 몇 가지 설계 패턴으로 설명된다. 이걸 알면 남의 대형 파이썬 앱을 읽는 눈이 생긴다.
모든 애플리케이션 코드는 app/ 안에 있고, 파일 이름의 접두사가 곧 계층이다. 기능 하나를 추가하면 보통 세 계층을 다 건드린다.
식당으로 치면 tab_*는 손님이 보는 메뉴판·주문 버튼, gradio_*는 주문을 받아 주방에 지시하는 홀 매니저, abus_*는 실제 요리하는 주방 각 파트(불·칼·오븐)다. 주방 파트(코어)는 손님(UI)을 전혀 모르기 때문에, 배달앱이 새로 생겨도(다른 UI) 그대로 재사용된다. 이 "UI를 모르는 코어"가 좋은 설계의 핵심이다.
abus_app_voice.create_ui()가 화면을 조립하는데, 각 탭이 파이프라인의 한 구간에 대응한다.
gulliver_tab) — 다운로드→받아쓰기→번역→더빙을 한 화면에서 다 하는 올인원subtitle_tab) — 자막 만들기만translate_tab) + Live(live_translate_tab, Windows 전용)GradioGulliver(gradio_gulliver.py)가 Dubbing Studio의 중앙 지휘자로, 생성자에서 다운로더·Demucs·번역기·5종 TTS를 전부 손에 쥔다. 그리고 gradio_whisper() → gradio_translate() → TTS 순으로 파이프라인을 흘린다.
ASR 엔진 선택이 교과서적인 전략 패턴이다. 문자열 이름 하나로 구현 클래스를 바꿔 끼운다.
# app/gradio_gulliver.py — 이름 → 구현 클래스 딕셔너리 매핑
def switch_case(self, case):
switch_dict = {
'faster-whisper': lambda: FasterWhisperInference(),
'whisper': lambda: WhisperInference(),
'whisper-timestamped': lambda: WhisperTimestampedInference(),
}
# 모르는 이름(옛 'whisperX' 등)은 조용히 faster-whisper로 폴백
return switch_dict.get(case, lambda: FasterWhisperInference())()같은 방식으로 Azure냐 무료냐도 런타임에 갈린다. abus_genuine.azure_text_api_working()이 .env의 Azure 키가 실제로 동작하는지 확인해, 되면 AzureTranslator/AzureTTS, 안 되면 DeepTranslator/EdgeTTS(무료)를 쓴다. 사용자는 키를 넣기만 하면 코드 수정 없이 경로가 바뀐다.
src/config.py의 UserConfig가 app/config-user.json5(JSON5)를 읽어 큰 기본값 딕셔너리 위에 덮어쓴다. 위젯은 user_config.get(key, default)로 초기값을 읽고, 바뀌면 set(key, value)가 즉시 파일에 저장. 새 설정은 JSON5 파일과 기본값 딕셔너리 양쪽에 추가해야 한다.i18n("English string")으로 감싼다. 영어 원문이 곧 조회 키이고, 번역은 src/i18n/locale/의 8개 JSON(de·en·es·ja·ko·pt·zh_CN·zh_TW)에 들어간다. 번역이 없으면 키(영어)로 폴백. scan_i18n.py가 소스에서 키를 뽑아낸다.start-voice.py가 AbusHuggingFace.hf_download_models()를 불러, app/abus_hf_files-*.json 매니페스트를 읽고 HF ABUS-AI/*에서 model/로 내려받는다. CosyVoice2-0.5B가 약 9GB라 첫 실행이 길다. Fun-CosyVoice3-0.5B(한국어)는 첫 사용 시 공식 HF 레포에서 받는다.망가지면? README의 정답은 언제나 같다 — installer_files/ 폴더를 지우고 다시 start. 모델(model/)은 남으니 재다운로드는 없다. 이 "격리 폴더 하나만 날리면 초기화"가 v4.0 설계의 핵심 안전장치다.
① CLAUDE.md(아키텍처 지도) → ② app/abus_app_voice.py(탭 = 파이프라인 구성) → ③ app/gradio_gulliver.py(중앙 지휘자, switch_case·파이프라인 메서드) → ④ 코어 하나 골라 정독: abus_asr_faster_whisper.py(받아쓰기) 또는 abus_tts_f5.py(클로닝) → ⑤ app/abus_path.py(경로 규칙) → ⑥ src/config.py(설정) → ⑦ pyproject.toml(의존성·핀의 이유는 주석에)
abus_app_*.py·tab_*.py 중 aicover·kara·gulliver·upscaler·vsr·rvc·demixing 등은 과거·대체 변종이고 여러 개가 abus_app_voice.py에서 주석 처리돼 있다 — 실제 임포트되는지 먼저 확인할 것. 또 컨트롤러들이 from abus_x import *로 코어 네임스페이스를 평탄화해 쓰므로 함수명이 앱 전역에 노출된다. 인라인 주석·일부 로그는 한국어(개발사가 한국 팀)라 오히려 읽기 편하다.voice-pro는 "AI 음성"만 배우는 곳이 아니다. 오히려 "여러 무거운 ML 라이브러리를 한 앱에 공존시키는 실전 통합 기술"의 교보재로 더 값지다.
switch_case) + 안전한 폴백으로 엔진 교체. 모르는 값이 와도 죽지 않게.pyproject.toml 주석은 그 자체로 "의존성 지옥 탈출기"다. numba가 numpy를 막고, transformers 버전이 벤더 코드 패치를 요구하고, Windows에 wheel 없는 패키지를 순수 파이썬 대체로 바꾸고… 이런 결정 하나하나가 현업 ML 엔지니어가 매일 부딪히는 문제다.
uv.lock 기반의 재현 가능·격리 설치, 관리자 권한 없는 부트스트랩, 휴대용 ffmpeg 자동 배치 — "모델을 만드는 것"과 "그 모델을 남이 쓰게 배포하는 것"이 완전히 다른 난이도의 문제임을 체감할 수 있다.
gr.Progress()), 에러를 빨간 토스트로 화면에 노출(v4.0 개선)하는 UX.GPU가 없어도 된다. gradio_gulliver.py의 switch_case와 파이프라인 메서드(gradio_whisper→gradio_translate) 흐름만 종이에 손으로 따라 그려 봐도 "탭=파이프라인" 설계가 손에 잡힌다. pyproject.toml의 주석을 한 줄씩 읽으며 "왜 이 버전에 고정했나"를 검색해 보는 것도 훌륭한 ML 배포 공부다.
| 항목 | 요구/권장 | 비고 |
|---|---|---|
| OS | Windows (검증됨) | Mac/Linux는 스크립트는 있으나 미검증. 코드가 platform.system()으로 크게 분기, Live 번역은 Windows 전용 |
| GPU | NVIDIA GPU 강력 권장 | Torch cu128 → RTX 50 시리즈까지. CPU 설치(cpu extra)도 되지만 매우 느림 |
| 관리자 권한 | 불필요 | v4.0의 핵심 개선. ffmpeg도 자동 다운로드 |
| 디스크 | 수~수십 GB | CosyVoice2-0.5B만 약 9GB. 모델 여러 개 받으면 늘어남 |
| 초기 실행 시간 | 수십 분~1시간+ | 대용량 모델 다운로드 때문. 이후엔 빠름 |
| 사전 설치 | CUDA Toolkit·VS 빌드도구 불필요 | 모든 의존성이 prebuilt wheel |
| 네트워크 | 초기 다운로드에 필요 | 이후 로컬 처리(무료 번역만 Google 엔드포인트 사용) |
| Azure(선택) | 본인 키 | .env.example→.env 복사 후 키 입력 시 활성 |
# 가장 간단한 시작(Windows) — 관리자 권한 없이
git clone https://github.com/abus-aikorea/voice-pro.git
cd voice-pro
start.bat # uv 다운로드→환경 구축→모델 받기→브라우저 자동 오픈
# 브라우저에서 http://127.0.0.1:7870 접속
# GPU/CPU 강제 지정이 필요하면
set GPU_CHOICE=G # G=GPU(NVIDIA), C=CPU
start.bat
# 문제가 생기면 — 격리 폴더만 지우고 재시작(모델은 보존)
# installer_files\ 삭제 후 start.bat 다시 실행F5-TTS·CosyVoice로 타인의 목소리를 복제하는 것은 강력한 기능인 만큼 위험도 크다. 동의 없는 목소리 도용, 사칭·딥페이크·허위 콘텐츠 제작은 초상·음성권 침해와 사기가 될 수 있다. 저작권 있는 영상의 무단 다운로드·재배포도 마찬가지. 반드시 본인 목소리·허락받은 자료·합법적 용도로만 쓸 것.
app/abus_app_voice.py의 create_ui()를 읽고, 어떤 탭이 어떤 컨트롤러(*_tab→Gradio*)를 부르는지 화살표로 정리하라. Windows에서만 열리는 탭이 무엇인지도 찾아보라. (힌트: if system == "Windows")
switch_case가 매핑하는 FasterWhisperInference·WhisperInference·WhisperTimestampedInference 세 코어 파일을 열어, 각 transcribe의 입출력 형태를 비교하라. 왜 기본값이 faster-whisper인지, 왜 timestamped가 자막 하이라이트에 쓰이는지 근거를 코드에서 찾아라.
Speech Generation 탭에서 kokoro 또는 Edge-TTS로 한 문단을 합성해 보고, 이어서 F5-TTS에 내 목소리 10초를 참조로 넣어 같은 문단을 내 목소리로 클로닝해 비교하라. 두 방식의 품질·속도 차이를 표로 남겨라.
저작권 문제 없는 내 영상(또는 CC0)을 Dubbing Studio에 넣어 영어→한국어 더빙본을 뽑아라. 중간 산출물(workspace/의 분리 음원·자막·번역 자막)을 각각 열어 파이프라인이 실제로 남긴 흔적을 확인하라.
탭 하나에 라벨을 하나 추가하되 i18n("New Label")로 감싸고, src/i18n/locale/ko_KR.json에 대응 번역을 넣어라. 번역을 일부러 빼면 어떻게 폴백하는지(키=영어 그대로 노출) 확인하라. 나아가 새 설정값을 config-user.json5 + 기본값 딕셔너리 양쪽에 추가해 get/set으로 저장되게 만들어라.
| 주차 | 주제 | 할 일 / 목표 |
|---|---|---|
| 1주차 | 음성 AI 기초 | STT/TTS/보이스클로닝 개념 정리. Whisper 논문 개요, 제로샷 TTS(F5-TTS·CosyVoice) 데모 체험 |
| 2주차 | voice-pro 구조 독해 | CLAUDE.md+abus_app_voice.py+gradio_gulliver.py 정독. 3계층·전략 패턴 손그림 |
| 3주차 | 파이프라인 실습 | Demucs 음원 분리·Whisper 자막·번역·TTS를 각각 따로 돌려 보고 중간 산출물 관찰 |
| 4주차 | ML 패키징 | uv 학습(pyproject.toml+lock). 의존성 핀 주석을 하나씩 검증하며 "왜 고정?"에 답하기 |
| 5주차 | Gradio 심화 | Gradio 6로 나만의 미니 STT/TTS 데모 앱 제작. 진행률·에러 토스트·상태 관리 |
| 6주차 | 모델 서빙·최적화 | faster-whisper(CTranslate2) 원리, ONNX Runtime, GPU/CPU 분기·양자화 개념 |
| 7주차 | i18n·설정 외부화 | 다국어 앱 설계: 키 추출·폴백·locale 관리. JSON5 설정 패턴 응용 |
| 8주차 | 확장 프로젝트 | voice-pro에 새 TTS 엔진 어댑터를 abus_tts_* 규약대로 추가(전략 패턴 실전) |
CLAUDE.md(아키텍처) → app/abus_app_voice.py(탭=파이프라인) → app/gradio_gulliver.py(중앙 지휘자·switch_case) → app/abus_asr_faster_whisper.py·abus_tts_f5.py(코어) → app/abus_path.py(경로) → src/config.py(설정) → pyproject.toml(의존성 핀의 이유는 주석에)