docs: README.md 추가

- 프로젝트 개요 및 기능 설명 - 기술 스택 및 구조 문서화 - 설치/실행 방법 안내 - API 엔드포인트 목록 - 대본 형식 가이드 - GPU 요구사항 명시 Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-26 11:41:26 +09:00
parent cc547372c0
commit df52a7d7ff
1 changed files with 192 additions and 0 deletions
--- a/README.md
+++ b/README.md
@ -0,0 +1,192 @@
+# Drama Studio
+
+AI 기반 라디오 드라마 제작 시스템
+
+## 개요
+
+Drama Studio는 Qwen3-TTS와 MusicGen을 활용하여 텍스트 대본으로부터 완성된 라디오 드라마를 자동 생성하는 시스템입니다.
+
+## 기능
+
+- **TTS 음성 합성**: Qwen3-TTS 1.7B 모델을 사용한 고품질 한국어/다국어 음성 생성
+- **배경음악 생성**: MusicGen을 활용한 AI 배경음악 생성
+- **효과음 검색**: Freesound API 연동으로 다양한 효과음 검색 및 사용
+- **드라마 제작**: 대본 파싱 → 음성 생성 → 배경음악/효과음 믹싱 → 최종 오디오 출력
+- **음성 관리**: 커스텀 음성 프로필 생성 및 관리
+
+## 기술 스택
+
+| 구성요소 | 기술 |
+|---------|------|
+| Frontend | Next.js 15 + React 19 + TypeScript + Tailwind CSS 4 |
+| Backend | FastAPI + Python 3.11 + Pydantic v2 |
+| TTS Engine | Qwen3-TTS 1.7B (GPU) |
+| Music Gen | MusicGen-small (GPU) |
+| Database | MongoDB 7.0 + Redis 7 |
+| Container | Docker + Docker Compose |
+
+## 프로젝트 구조
+
+```
+drama-studio/
+├── audio-studio-api/       # FastAPI 백엔드 서버
+│   ├── app/
+│   │   ├── routers/        # API 엔드포인트
+│   │   │   ├── drama.py    # 드라마 프로젝트 관리
+│   │   │   ├── tts.py      # TTS 음성 합성
+│   │   │   ├── music.py    # 배경음악 생성
+│   │   │   ├── sound_effects.py  # 효과음 검색
+│   │   │   ├── voices.py   # 음성 프로필 관리
+│   │   │   └── recordings.py     # 녹음 파일 관리
+│   │   └── services/       # 비즈니스 로직
+│   │       ├── drama_orchestrator.py  # 드라마 생성 오케스트레이터
+│   │       ├── script_parser.py       # 대본 파서
+│   │       ├── audio_mixer.py         # 오디오 믹싱
+│   │       ├── tts_client.py          # TTS 엔진 클라이언트
+│   │       └── freesound_client.py    # Freesound API 클라이언트
+│   ├── Dockerfile
+│   └── requirements.txt
+│
+├── audio-studio-ui/        # Next.js 프론트엔드
+│   ├── src/app/
+│   │   ├── page.tsx        # 대시보드
+│   │   ├── drama/          # 드라마 제작
+│   │   ├── tts/            # TTS 테스트
+│   │   ├── music/          # 배경음악 생성
+│   │   ├── sound-effects/  # 효과음 검색
+│   │   ├── voices/         # 음성 관리
+│   │   └── recordings/     # 녹음 관리
+│   ├── Dockerfile
+│   └── package.json
+│
+├── audio-studio-tts/       # Qwen3-TTS 엔진 (GPU)
+│   ├── app/
+│   │   ├── main.py         # FastAPI 서버
+│   │   └── services/
+│   │       └── qwen_tts.py # TTS 모델 서비스
+│   ├── Dockerfile.gpu
+│   └── requirements.txt
+│
+├── audio-studio-musicgen/  # MusicGen 서비스 (GPU)
+│   ├── app/
+│   │   ├── main.py         # FastAPI 서버
+│   │   └── services/
+│   │       └── musicgen_service.py  # MusicGen 모델 서비스
+│   ├── Dockerfile.gpu
+│   └── requirements.txt
+│
+├── docker-compose.yml      # 운영 환경 (GPU 포함)
+├── docker-compose.dev.yml  # 개발 환경 (GPU 없이)
+└── .env.example            # 환경변수 템플릿
+```
+
+## 설치 및 실행
+
+### 환경 설정
+
+```bash
+# 환경변수 설정
+cp .env.example .env
+# .env 파일을 편집하여 필요한 값 입력
+```
+
+### 개발 환경 (GPU 없음)
+
+```bash
+# API + UI + MongoDB + Redis만 실행
+docker compose -f docker-compose.dev.yml up -d
+```
+
+- UI: http://localhost:3010
+- API: http://localhost:8010
+- API Docs: http://localhost:8010/docs
+
+### 운영 환경 (GPU 필요)
+
+```bash
+# 전체 서비스 실행 (TTS, MusicGen 포함)
+docker compose up -d
+```
+
+### 프라이빗 레지스트리에서 Pull
+
+```bash
+# Docker 이미지 Pull
+docker pull docker.yakenator.io/drama-studio/api:latest
+docker pull docker.yakenator.io/drama-studio/ui:latest
+docker pull docker.yakenator.io/drama-studio/tts:latest
+docker pull docker.yakenator.io/drama-studio/musicgen:latest
+```
+
+## API 엔드포인트
+
+### 드라마 프로젝트
+
+| Method | Endpoint | 설명 |
+|--------|----------|------|
+| GET | `/api/drama/projects` | 프로젝트 목록 조회 |
+| POST | `/api/drama/projects` | 새 프로젝트 생성 |
+| GET | `/api/drama/projects/{id}` | 프로젝트 상세 조회 |
+| POST | `/api/drama/projects/{id}/generate` | 드라마 생성 시작 |
+
+### TTS
+
+| Method | Endpoint | 설명 |
+|--------|----------|------|
+| POST | `/api/tts/synthesize` | 텍스트를 음성으로 변환 |
+| GET | `/api/tts/voices` | 사용 가능한 음성 목록 |
+
+### 배경음악
+
+| Method | Endpoint | 설명 |
+|--------|----------|------|
+| POST | `/api/music/generate` | 프롬프트로 배경음악 생성 |
+
+### 효과음
+
+| Method | Endpoint | 설명 |
+|--------|----------|------|
+| GET | `/api/sound-effects/search` | Freesound에서 효과음 검색 |
+
+## 대본 형식
+
+드라마 대본은 다음 형식을 따릅니다:
+
+```
+[장면: 숲속, 아침]
+[BGM: 잔잔한 피아노]
+
+영희: (조용히) 여기가 그 장소야...
+철수: 정말 아름답군.
+
+[효과음: 새소리]
+
+영희: (기쁘게) 들어봐, 새들이 노래하고 있어!
+```
+
+### 태그 설명
+
+- `[장면: ...]` - 장면 설명 (메타데이터)
+- `[BGM: ...]` - 배경음악 프롬프트
+- `[효과음: ...]` - 효과음 검색 키워드
+- `캐릭터명: (감정) 대사` - 대사 및 감정 표현
+
+## GPU 요구사항
+
+| 서비스 | 최소 VRAM | 권장 VRAM |
+|--------|----------|----------|
+| Qwen3-TTS 1.7B | 8GB | 16GB |
+| MusicGen-small | 4GB | 8GB |
+| **합계** | **12GB** | **24GB** |
+
+## 개발 가이드
+
+자세한 개발 가이드는 `.claude/skills/` 디렉토리를 참조하세요:
+
+- [deployment-standards.md](.claude/skills/deployment-standards.md) - Docker 배포 규칙
+- [api-design-standards.md](.claude/skills/api-design-standards.md) - API 설계 표준
+- [frontend-component-patterns.md](.claude/skills/frontend-component-patterns.md) - React 컴포넌트 패턴
+
+## 라이선스
+
+Private - Yakenator