README.md

metadata

title: UTAU WebUI
emoji: 📉
colorFrom: indigo
colorTo: red
sdk: gradio
sdk_version: 5.33.1
app_file: app.py
pinned: false
license: mit

🎵 UTAU WebUI - 한국어 음성 합성기

피아노롤 기반의 웹 UTAU 음성 합성 시스템입니다. 한국어 CVC 보이스뱅크를 사용하여 자연스러운 한국어 음성을 합성할 수 있습니다.

✨ 특징

• 🎹 직관적인 피아노롤 인터페이스: 웹 브라우저에서 바로 사용 가능한 피아노롤 편집기
• 🇰🇷 한국어 음성 합성: hanseol CVC 보이스뱅크를 사용한 고품질 한국어 음성 합성
• 🗜️ HDF5 압축 시스템: 47.7MB → 33.9MB (29% 압축), 46개 파일 → 1개 파일로 최적화
• 🚀 자동화된 워크플로우: Makefile을 통한 원클릭 설정, 압축, 실행
• 🎵 실시간 편집: 노트 추가, 삭제, 가사 입력이 실시간으로 가능
• 🔊 웨이브폼 시각화: 합성된 음성의 웨이브폼을 피아노롤에서 바로 확인
• 🎤 CVC 음소 시스템: 585개의 한국어 CVC 음소로 자연스러운 발음 구현
• ☁️ 클라우드 최적화: Gradio 및 Hugging Face Spaces 환경에 최적화

🎤 보이스뱅크 정보

• 보이스뱅크: hanseol CVC (HDF5 압축)
• CV (Character Voice): KUNGOM
• UTAU: KITANE 백한설
• 음소 수: 585개 CVC 음소
• 언어: 한국어
• 압축율: 29% (원본 47.7MB → 압축 33.9MB)

🚀 빠른 시작

필요 조건

• Python 3.12+
• uv (Python 패키지 관리자)
• GNU Make (자동화 스크립트용)

uv 설치

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

🎯 한 번에 설정하고 실행하기

# 저장소 클론
git clone <repository-url>
cd utau-webui

# 모든 설정과 실행을 한 번에
make all

📋 단계별 실행

# 1. 개발 환경 설정
make setup

# 2. 보이스뱅크 압축 (최초 1회만)
make compress

# 3. 웹UI 실행
make run

🔍 현재 상태 확인

# 프로젝트 상태 확인
make status

# 의존성 및 환경 확인
make check-deps

📋 Makefile 명령어

명령어	설명
make help	사용 가능한 모든 명령어 표시
make setup	개발 환경 초기 설정 (의존성 설치)
make compress	보이스뱅크를 HDF5 형태로 압축
make run	웹UI 실행
make dev	개발 모드로 실행 (auto-reload)
make test	압축된 보이스뱅크 테스트
make status	현재 프로젝트 상태 확인
make clean	임시 파일 및 캐시 정리
make all	전체 설정 및 실행 (setup → compress → run)

🎼 사용법

1. 노트 추가: 피아노롤에서 원하는 위치를 클릭하여 노트 추가
2. 가사 입력: 노트를 더블클릭하여 한국어 가사 입력
3. 노트 편집: 드래그하여 노트 길이 조정, 위아래로 드래그하여 음높이 조정
4. 음성 합성: "🎵 음성 합성" 버튼 클릭하여 음성 생성
5. 재생: 생성된 음성을 바로 들어보거나 다운로드

지원하는 한국어 음소

• 기본 모음: 아, 이, 우, 에, 오, 으, 어
• 자음+모음 조합: 바, 다, 가, 하, 자, 카, 라, 마, 나, 파, 사, 타 등
• 복합 모음: 야, 예, 여, 요, 유, 의, 와, 웨, 위, 워
• 도레미 음계: 도, 레, 미, 파, 솔, 라, 시

🗜️ HDF5 압축 시스템

장점

• 파일 관리 최적화: 46개 WAV 파일 → 1개 HDF5 파일
• 용량 최적화: 29% 압축 효율 (47.7MB → 33.9MB)
• 성능 향상: 더 빠른 로딩 및 배포
• 클라우드 친화적: Hugging Face Spaces 등 클라우드 환경에 최적화

압축 과정

# 자동 압축
make compress

# 수동 압축
uv run python -c "from voice_data_converter import convert_voicebank_to_compressed_format; convert_voicebank_to_compressed_format('voice/hanseol CVC')"

🛠️ 기술 스택

• Frontend: Gradio + Custom PianoRoll Component
• Backend: Python
• 음성 합성: UTAU Engine + Straycat Resampler
• 데이터 압축: HDF5 (with gzip compression)
• 오디오 처리: SoundFile, NumPy
• 패키지 관리: uv
• 자동화: GNU Make

🔧 개발하기

개발 환경 설정

# 전체 개발 환경 설정
make setup

# 개발 모드로 실행 (파일 변경 시 자동 재시작)
make dev

# 쉘 진입
make shell

의존성 관리

# 의존성 추가
uv add <package-name>

# 개발 의존성 추가
uv add --dev <package-name>

# 의존성 업데이트
make update

프로젝트 정보

# 프로젝트 정보 확인
make info

# 의존성 트리 확인
uv tree

🚨 문제 해결

압축된 보이스뱅크가 없는 경우

# 상태 확인
make status

# 보이스뱅크 압축
make compress

원본 보이스뱅크가 없는 경우

1. hanseol CVC 보이스뱅크를 voice/hanseol CVC 디렉토리에 배치
2. make compress 실행

환경 문제

# 환경 확인
make check-deps

# 의존성 재설치
make setup

📝 저작권 및 라이선스

UTAU WebUI

본 프로젝트는 오픈소스 소프트웨어입니다.

Straycat Resampler

본 프로젝트에서 사용하는 UTAU 리샘플러는 straycat을 기반으로 합니다.

원본 저장소: https://github.com/UtaUtaUtau/straycat 라이선스: MIT License 저작권: Copyright (c) UtaUtaUtau

Yet another WORLD-based UTAU resampler.

MIT 라이선스에 따라 본 프로젝트에 포함되었으며, 원본 저작권 표시를 유지합니다.

hanseol CVC 보이스뱅크

• CV: KUNGOM
• UTAU: KITANE 백한설

해당 보이스뱅크의 사용 권한에 대해서는 원 저작권자의 이용 약관을 따릅니다.