전문 노래방 비디오 생성기 🎶 🎥 🚀
PyPI - Version
PyPI - Python Version
Tests
Test Coverage
악기 반주와 동기화된 가사를 사용하여 전문적인 노래방 비디오를 생성합니다. 로컬 CLI(karaoke-gen) 또는 처리 과정을 Google Cloud로 오프로드하는 클라우드 기반 CLI(karaoke-gen-remote) 형태로 사용할 수 있습니다.
✨ 노래방 영상 제작 방법 두 가지
1. 로컬 CLI (karaoke-gen)
모든 처리를 사용자의 기기에서 로컬로 실행합니다. 최적의 오디오 분리(audio separation) 성능을 위해서는 GPU가 필요합니다.
karaoke-gen "ABBA" "Waterloo"
2. 원격 CLI (karaoke-gen-remote)
모든 처리를 클라우드 백엔드로 오프로드합니다. GPU가 필요하지 않으며, 인증 후 작업을 제출하기만 하면 됩니다.
karaoke-gen-remote ./song.flac "ABBA" "Waterloo"
두 CLI 모두 동일한 결과물을 생성합니다: 4K 노래방 비디오, CDG+MP3 패키지, 오디오 스템(audio stems) 등.
🎯 주요 기능 (Features)
핵심 파이프라인 (Core Pipeline)
- 오디오 분리 (Audio Separation): MDX 및 Demucs 모델을 사용한 AI 기반 보컬/악기 분리(vocal/instrumental separation).
- 가사 전사 (Lyrics Transcription): AudioShake API를 통한 단어별 타임스탬프.
- 가사 수정 (Lyrics Correction): 온라인 가사(Genius, Spotify, Musixmatch)와 전사된 내용을 비교하여 일치시킵니다.
- 수동 검토 (Human Review): 최종 렌더링 전에 가사를 수정할 수 있는 인터랙티브 UI 제공.
- 비디오 렌더링 (Video Rendering): 사용자 정의 스타일을 적용한 고화질 4K 노래방 비디오.
- 다중 출력 (Multiple Outputs): MP4 (4K 무손실/손실, 720p), MKV, CDG+MP3, TXT+MP3.
배포 기능 (Distribution Features)
- YouTube 업로드: YouTube 채널로 자동 업로드.
- Dropbox 통합: 브랜드 코드가 지정된 폴더에 결과물을 정리하여 보관.
- Google Drive: 공개 공유 폴더에 업로드.
- Discord 알림: 작업 완료 시 웹훅(Webhook) 알림 제공.
📦 설치 (Installation)
이 명령어는 karaoke-gen (로컬용)과 karaoke-gen-remote (클라우드용) CLI를 모두 설치합니다.
요구 사항 (Requirements)
- Python 3.10-3.13
- FFmpeg
- 로컬 처리를 위한 권장 사양: CUDA 지원 GPU 또는 Apple Silicon CPU
전사 제공업체 설정 (Transcription Provider Setup)
동기화된 가사가 있는 노래방 비디오 제작을 위해서는 전사(Transcription)가 필수적입니다. 시스템은 음악과 동기화되어 가사를 표시하기 위해 단어 수준의 타이밍 데이터가 필요합니다.
옵션 1: AudioShake (권장)
고품질 전사 기능을 갖춘 상업용 서비스입니다. 제작(production) 용도에 가장 적합합니다.
export AUDIOSHAKE_API_TOKEN="your_audioshake_token"
현재 작성 시점 기준, 비즈니스 전용으로 https://www.audioshake.ai/에서 API 키를 받으세요.
옵션 2: 로컬 Whisper (클라우드 불필요)
whisper-timestamped를 사용하여 로컬 머신에서 직접 실행합니다. CPU, NVIDIA GPU (CUDA), 또는 Apple Silicon에서 작동합니다.
pip install "karaoke-gen[local-whisper]"
...
모델 크기 가이드:
| 모델 | VRAM | 속도 | 품질 |
|---|
| tiny | ~1GB | 빠름 | 낮음 |
| ... | | | |
CPU 전용 설치 (GPU 불필요):
pip install torch torchaudio --index-url https://download.pytorch.org/whl/cpu
pip install "karaoke-gen[local-whisper]"
로컬 Whisper는 클라우드 전사 서비스가 구성되지 않은 경우 자동으로 대체(fallback)하여 실행됩니다.
옵션 3: RunPod를 통한 Whisper
RunPod 인프라에서 OpenAI의 Whisper 모델을 사용하는 클라우드 기반 대안입니다.
export RUNPOD_API_KEY="your_runpod_key"
export WHISPER_RUNPOD_ID="your_whisper_endpoint_id"
https://www.runpod.io/에서 Whisper 엔드포인트를 설정하세요.
전사 없이 (반주만)
동기화된 가사가 필요하지 않은 경우, --skip-lyrics 플래그를 사용합니다:
karaoke-gen --skip-lyrics "Artist" "Title"
이는 가사 오버레이가 없는 반주 전용 노래방 비디오를 생성합니다.
참고: 상세한 전사 제공자 구성 옵션은 lyrics_transcriber_temp/README.md를 참조하세요.
🖥️ 로컬 CLI (karaoke-gen)
기본 사용법
karaoke-gen ./song.mp3 "Artist Name" "Song Title"
...
원격 오디오 분리 (선택 사항)
GPU 집약적인 오디오 분리만 Modal.com에 할당하고 다른 처리는 로컬에서 유지하는 방법:
export AUDIO_SEPARATOR_API_URL="https://USERNAME--audio-separator-api.modal.run"
karaoke-gen "Artist" "Title"
주요 옵션
karaoke-gen --style_params_json="./styles.json" "Artist" "Title"
...
전체 옵션 참조
☁️ 원격 CLI (karaoke-gen-remote)
원격 CLI는 모든 처리를 처리하는 Google Cloud 백엔드에 작업을 제출합니다. 로컬에 GPU나 오디오 처리 라이브러리가 설치되어 있을 필요가 없습니다.
설정
- 백엔드 URL 설정:
export KARAOKE_GEN_URL="https://api.nomadkaraoke.com" # 또는 사용자 백엔드 주소
2. **Google Cloud 인증:**
```bash
gcloud auth login
기본 사용법
karaoke-gen-remote ./song.flac "ABBA" "Waterloo"
...
작업 관리
karaoke-gen-remote --list
...
전체 프로덕션 실행
karaoke-gen-remote \
--style_params_json="./karaoke-styles.json" \
--enable_cdg \
...
환경 변수
| 변수 | 설명 | 기본값 |
|---|
KARAOKE_GEN_URL | 백엔드 서비스 URL | 필수 |
| ... | | |
참고: REVIEW_UI_URL은 호스팅된 가사 검토 UI로 기본 설정됩니다. 로컬 개발의 경우, 프론트엔드 개발 서버를 실행하는 경우 http://localhost:5173으로 설정하세요. | | |
인증
백엔드는 관리자 작업(대량 삭제, 내부 워커 트리거)에 대해 토큰 기반 인증을 사용합니다. 기본 작업 제출 및 모니터링의 경우 인증은 선택 사항입니다.
관리자 액세스를 위한 방법:
export KARAOKE_GEN_AUTH_TOKEN="your-admin-token"
이 토큰은 백엔드의 ADMIN_TOKENS 환경 변수에 구성된 토큰 중 하나와 일치해야 합니다.
비대화형 모드
자동화/CI 사용을 위한 방법:
karaoke-gen-remote -y ./song.flac "Artist" "Title"
The -y 플래그는 기본 수정 사항을 자동으로 수락하고 깨끗한 반주(clean instrumental)를 선택합니다.
🎨 스타일 설정 (Style Configuration)
노래방 비디오 모양을 사용자 정의하려면 styles.json 파일을 생성하세요:
{
"intro": {
"video_duration": 5,
...
}
karaoke-gen-remote를 사용할 때, 참조된 모든 파일은 작업과 함께 자동으로 업로드됩니다.
📤 출력 파일 (Output Files)
완료된 작업은 다음을 생성합니다:
BRAND-1234 - Artist - Title/
├── Artist - Title (Final Karaoke Lossless 4k).mp4 # ProRes 4K
├── Artist - Title (Final Karaoke Lossless 4k).mkv # FLAC audio 4K
...
🏗️ 자체 백엔드 배포 (Deploy Your Own Backend)
클라우드 백엔드는 다음을 사용하여 Google Cloud Platform에서 실행됩니다:
- Cloud Run: 서버리스 API 호스팅(Serverless API hosting)
- Firestore: 작업 상태 관리(Job state management)
- Cloud Storage: 파일 업로드 및 출력물
- Modal.com: GPU 가속 오디오 분리(GPU-accelerated audio separation)
- AudioShake: 가사 전사 API (Lyrics transcription API)
사전 요구 사항 (Prerequisites)
- 결제가 활성화된 Google Cloud 계정
- Pulumi CLI
- Modal.com 계정 (오디오 분리를 위해)
- AudioShake API 키
인프라 설정 (Infrastructure Setup)
이 과정은 다음 항목들을 생성합니다:
- Firestore 데이터베이스
- Cloud Storage 버킷
- Artifact Registry
- IAM 역할을 가진 서비스 계정(Service account)
- Secret Manager 비밀 값 (사용자가 값을 추가해야 함)
비밀 값 추가 (Add Secret Values)
echo -n "your-audioshake-key" | gcloud secrets versions add audioshake-api-key --data-file=-
...
Cloud Run 배포 (Deploy Cloud Run)
배포는 main으로 푸시할 때 GitHub Actions CI를 통해 자동으로 이루어집니다. 전체 배포 워크플로는 .github/workflows/ci.yml을 참조하세요.
CLI에서 백엔드 지정 (Point CLI to Your Backend)
export KARAOKE_GEN_URL="https://your-backend.run.app"
karaoke-gen-remote ./song.flac "Artist" "Title"
🔌 백엔드 API 참조 (Backend API Reference)
백엔드는 작업 관리를 위한 REST API를 노출합니다.
작업 제출 (Job Submission)
POST /api/jobs/upload
오디오 파일과 옵션을 사용하여 새로운 노래방 생성 작업을 제출합니다.
curl -X POST "https://api.example.com/api/jobs/upload" \
-F "[email protected]" \
-F "artist=ABBA" \
...
작업 상태 (Job Status)
GET /api/jobs/{job_id}
작업 상태 및 세부 정보를 가져옵니다.
curl "https://api.example.com/api/jobs/abc12345"
작업 목록 조회 (List Jobs)
GET /api/jobs
선택적 상태 필터와 함께 모든 작업 목록을 조회합니다.
curl "https://api.example.com/api/jobs?status=complete&limit=10"
작업 취소 (Cancel Job)
POST /api/jobs/{job_id}/cancel
실행 중인 작업을 취소합니다.
curl -X POST "https://api.example.com/api/jobs/abc12345/cancel" \
-H "Content-Type: application/json" \
-d '{"reason": "User cancelled"}'
작업 삭제 (Delete Job)
DELETE /api/jobs/{job_id}
작업 및 관련 파일을 삭제합니다.
curl -X DELETE "https://api.example.com/api/jobs/abc12345?delete_files=true"
가사 검토 (Lyrics Review)
GET /api/review/{job_id}/correction-data
가사 검토를 위한 수정 데이터를 가져옵니다.
POST /api/review/{job_id}/complete
수정된 가사를 제출하고 비디오 렌더링을 트리거합니다.
반주 선택 (Instrumental Selection)
GET /api/jobs/{job_id}/instrumental-options
사용 가능한 반주 옵션을 가져옵니다.
POST /api/jobs/{job_id}/select-instrumental
반주 선택을 제출합니다 (클린 또는 백킹 포함).
curl -X POST "https://api.example.com/api/jobs/abc12345/select-instrumental" \
-H "Content-Type: application/json" \
-d '{"selection": "clean"}'
파일 다운로드 (Download Files)
GET /api/jobs/{job_id}/download-urls
모든 출력 파일을 위한 다운로드 URL을 가져옵니다.
GET /api/jobs/{job_id}/download/{category}/{file_key}
특정 파일을 스트리밍 다운로드합니다.
상태 확인 (Health Check)
GET /api/health
백엔드 상태를 확인합니다.
🔧 문제 해결 (Troubleshooting)
"처리할 적절한 파일을 찾을 수 없음" (No suitable files found for processing)
이 오류는 최종화 단계에서 (With Vocals).mkv 파일이 누락되었을 때 발생합니다. 이 파일은 가사 전사 과정에서 생성됩니다.
가장 흔한 원인: 전사(transcription) 제공업체가 구성되지 않음.
빠른 해결 방법:
- 전사 제공업체 설정 여부 확인:
echo $AUDIOSHAKE_API_TOKEN
echo $RUNPOD_API_KEY
2. 두 값 모두 비어 있는 경우, 제공업체를 설정합니다 (참고: [전사 제공업체 설정](#transcription-provider-setup)).
3. 또는 악기 전용 노래방 영상의 경우 `--skip-lyrics`를 사용합니다:
```bash
karaoke-gen --skip-lyrics "Artist" "Title"
기타 원인:
- 유효하지 않은 API 자격 증명 - 토큰이 정확하고 활성화되었는지 확인하세요.
- API 서비스 사용 불가 - 서비스 상태 페이지를 확인하세요.
- 네트워크 연결 문제 - API 엔드포인트에 도달할 수 있는지 확인하세요.
- 전사 시간 초과(Transcription timeout) - 다시 시도하거나 다른 제공업체를 사용해 보세요.
전사가 조용히 실패하는 경우 (Transcription Fails Silently)
karaoke-gen이 오류 없이 실행되지만 동기화된 가사를 생성하지 않는 경우:
-
로그 확인 - 상세 출력을 위해 --log_level debug로 실행합니다:
karaoke-gen --log_level debug "Artist" "Title"
-
환경 변수 검증 - API 토큰이 셸에 내보내졌는지 확인하세요:
printenv | grep -E "(AUDIOSHAKE|RUNPOD|WHISPER)"
-
API 연결성 테스트 - 전사 서비스에 도달할 수 있는지 확인합니다.
"어떤 출처에서도 가사를 찾을 수 없음" (No lyrics found from any source)
이 경고는 온라인 출처(Genius, Spotify, Musixmatch)에서 참조 가사가 가져와지지 않았음을 의미합니다. 전사는 여전히 작동하지만 자동 수정 정확도가 낮을 수 있습니다.
해결 방법:
- Genius 가사를 위해
GENIUS_API_TOKEN 설정
- Spotify 가사를 위해
SPOTIFY_COOKIE_SP_DC 설정
- Musixmatch 가사를 위해
RAPIDAPI_KEY 설정
- 또는
--lyrics_file /path/to/lyrics.txt를 사용하여 수동으로 가사 제공
비디오 품질 문제 (Video Quality Issues)
출력된 비디오에 품질 문제가 있는 경우:
- FFmpeg이 제대로 설치되었는지 확인하세요:
ffmpeg -version
- 사용 가능한 코덱을 확인하세요:
ffmpeg -codecs
- 4K 출력을 위해서는 충분한 디스크 공간(트랙당 10GB 이상)을 확보하세요.
로컬 Whisper 문제 (Local Whisper Issues)
GPU 메모리 부족 (Out of Memory)
CUDA 메모리 부족 오류가 발생하는 경우:
export WHISPER_MODEL_SIZE="small"
...
CPU에서 전사(Transcription)가 느린 경우
CPU를 사용한 전사는 GPU에 비해 속도가 현저히 느립니다. 더 빠른 처리를 위해서는:
- 더 작은 모델 사용 (
tiny 또는 base)
- 클라우드 전사 서비스(AudioShake 또는 RunPod) 사용 고려
- Apple Silicon 환경에서는
small 모델이 좋은 속도/품질 균형을 제공합니다.
