README.md

---
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](https://docs.astral.sh/uv/) (Python 패키지 관리자)
- GNU Make (자동화 스크립트용)

### uv 설치

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

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

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

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

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

### 📋 단계별 실행

```bash
# 1. 개발 환경 설정
make setup

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

# 3. 웹UI 실행
make run
```

### 🔍 현재 상태 확인

```bash
# 프로젝트 상태 확인
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 등 클라우드 환경에 최적화

### 압축 과정
```bash
# 자동 압축
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

## 🔧 개발하기

### 개발 환경 설정
```bash
# 전체 개발 환경 설정
make setup

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

# 쉘 진입
make shell
```

### 의존성 관리
```bash
# 의존성 추가
uv add <package-name>

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

# 의존성 업데이트
make update
```

### 프로젝트 정보
```bash
# 프로젝트 정보 확인
make info

# 의존성 트리 확인
uv tree
```

## 🚨 문제 해결

### 압축된 보이스뱅크가 없는 경우
```bash
# 상태 확인
make status

# 보이스뱅크 압축
make compress
```

### 원본 보이스뱅크가 없는 경우
1. hanseol CVC 보이스뱅크를 `voice/hanseol CVC` 디렉토리에 배치
2. `make compress` 실행

### 환경 문제
```bash
# 환경 확인
make check-deps

# 의존성 재설치
make setup
```

## 📝 저작권 및 라이선스

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

### Straycat Resampler
본 프로젝트에서 사용하는 UTAU 리샘플러는 [straycat](https://github.com/UtaUtaUtau/straycat)을 기반으로 합니다.

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

> Yet another WORLD-based UTAU resampler.

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

### hanseol CVC 보이스뱅크
- **CV**: KUNGOM
- **UTAU**: KITANE 백한설

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