drama-studio/README.md

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            # 환경변수 템플릿

설치 및 실행

환경 설정

# 환경변수 설정
cp .env.example .env
# .env 파일을 편집하여 필요한 값 입력

개발 환경 (GPU 없음)

# 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 필요)

# 전체 서비스 실행 (TTS, MusicGen 포함)
docker compose up -d

프라이빗 레지스트리에서 Pull

# 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 - Docker 배포 규칙
• api-design-standards.md - API 설계 표준
• frontend-component-patterns.md - React 컴포넌트 패턴

라이선스

Private - Yakenator