Karaoke Generator 🎶 🎥 🚀
Generate karaoke videos with instrumental audio and synchronized lyrics. Available as both a CLI tool and a web application.
✨ Two Ways to Use Karaoke Generator
1. Command Line Interface (CLI)
Traditional Python package for local karaoke generation - perfect for batch processing and automation.
2. Web Application
Modern web interface for easy karaoke creation - no installation required!
- Frontend: https://gen.nomadkaraoke.com
- Technology: React + TypeScript on Cloudflare Pages
- Backend: FastAPI on Google Cloud Run
Learn more about the web version →
Overview
Karaoke Generator is a comprehensive tool for creating high-quality karaoke videos. It automates the entire workflow:
- Download audio and lyrics for a specified song
- Separate audio stems (vocals, instrumental)
- Synchronize lyrics with the audio
- Generate title and end screens
- Combine everything into a polished final video
- Organize and share the output files
Installation
pip install karaoke-gen
Remote Audio Separation 🌐
Karaoke Generator now supports remote audio separation using the Audio Separator API. This allows you to offload the compute-intensive audio separation to a remote GPU server while keeping the rest of the workflow local.
Benefits of Remote Processing
- Save Local Resources: No more laptop CPU/GPU consumption during separation
- Faster Processing: GPU-accelerated separation on dedicated hardware
- Cost Effective: ~$0.019 per separation job on Modal.com (with $30/month free credits)
- Multiple Models: Process with multiple separation models efficiently
Setup Remote Processing
-
Deploy Audio Separator API (using Modal.com):
pip install modal modal setup modal deploy audio_separator/remote/deploy_modal.py -
Set Environment Variable:
export AUDIO_SEPARATOR_API_URL="https://USERNAME--audio-separator-api.modal.run" -
Run Karaoke Generator Normally:
karaoke-gen "Rick Astley" "Never Gonna Give You Up"
The tool will automatically detect the AUDIO_SEPARATOR_API_URL environment variable and use remote processing instead of local separation. If the remote API is unavailable, it will gracefully fall back to local processing.
Remote vs Local Processing
| Aspect | Remote Processing | Local Processing |
|---|---|---|
| Resource Usage | Minimal local CPU/GPU | High local CPU/GPU |
| Processing Time | ~2-5 minutes | ~15-45 minutes |
| Cost | ~$0.019 per job | Free (but uses local resources) |
| Requirements | Internet connection | Local GPU recommended |
| Setup | One-time API deployment | Audio separator models download |
Quick Start
# Generate a karaoke video from a YouTube URL
karaoke-gen "https://www.youtube.com/watch?v=dQw4w9WgXcQ" "Rick Astley" "Never Gonna Give You Up"
# Or let it search YouTube for you
karaoke-gen "Rick Astley" "Never Gonna Give You Up"
Workflow Options
Karaoke Gen supports different workflow options to fit your needs:
# Run only the preparation phase (download, separate stems, create title screens)
karaoke-gen --prep-only "Rick Astley" "Never Gonna Give You Up"
# Run only the finalisation phase (must be run in a directory prepared by the prep phase)
karaoke-gen --finalise-only
# Skip automatic lyrics transcription/synchronization (for manual syncing)
karaoke-gen --skip-transcription "Rick Astley" "Never Gonna Give You Up"
# Skip audio separation (if you already have instrumental)
karaoke-gen --skip-separation --existing-instrumental="path/to/instrumental.mp3" "Rick Astley" "Never Gonna Give You Up"
Advanced Features
Audio Processing
# Specify custom audio separation models
karaoke-gen --clean_instrumental_model="model_name.ckpt" "Rick Astley" "Never Gonna Give You Up"
Lyrics Handling
# Use a local lyrics file instead of fetching from online
karaoke-gen --lyrics_file="path/to/lyrics.txt" "Rick Astley" "Never Gonna Give You Up"
# Adjust subtitle timing
karaoke-gen --subtitle_offset_ms=500 "Rick Astley" "Never Gonna Give You Up"
Video Background
# Use a video as background instead of static image
karaoke-gen --background_video="path/to/video.mp4" "Rick Astley" "Never Gonna Give You Up"
# Use a video background with darkening overlay (0-100%)
karaoke-gen --background_video="path/to/video.mp4" --background_video_darkness=50 "Rick Astley" "Never Gonna Give You Up"
The video background feature automatically:
- Scales the video to 4K resolution (3840x2160) with intelligent cropping
- Loops the video if it's shorter than the audio
- Trims the video if it's longer than the audio
- Applies an optional darkening overlay to improve subtitle readability
- Renders synchronized ASS subtitles on top of the video
Finalisation Options
# Enable CDG ZIP generation
karaoke-gen --enable_cdg --style_params_json="path/to/style.json" "Rick Astley" "Never Gonna Give You Up"
# Enable TXT ZIP generation
karaoke-gen --enable_txt "Rick Astley" "Never Gonna Give You Up"
# Upload to YouTube
karaoke-gen --youtube_client_secrets_file="path/to/client_secret.json" --youtube_description_file="path/to/description.txt" "Rick Astley" "Never Gonna Give You Up"
# Draft completion emails (requires youtube_client_secrets_file for Gmail OAuth)
karaoke-gen --email_template_file="path/to/template.txt" --youtube_client_secrets_file="path/to/client_secret.json" "Rick Astley" "Never Gonna Give You Up"
# Organize files with brand code
karaoke-gen --brand_prefix="BRAND" --organised_dir="path/to/Tracks-Organized" "Rick Astley" "Never Gonna Give You Up"
Full Command Reference
For a complete list of options:
karaoke-gen --help
Development
Running Tests
The project uses pytest for testing with unit and integration tests:
# Run all tests (unit tests first, then integration tests)
pytest
# Run only unit tests (fast feedback during development)
pytest -m "not integration"
# Run only integration tests (comprehensive end-to-end testing)
pytest -m integration
Unit tests run quickly and provide fast feedback, while integration tests are slower but test the full workflow end-to-end.
Web Application
Want to use karaoke generation without installing anything? Check out our web app!
Features:
- Submit jobs from YouTube URLs
- Upload your own audio files
- Real-time progress tracking
- Download generated karaoke videos
- Mobile-friendly interface
Access: https://gen.nomadkaraoke.com
Documentation:
Project Structure
karaoke-gen/
├── karaoke_gen/ # Core CLI package (shared by CLI and web)
├── backend/ # Web application backend (FastAPI)
├── frontend-react/ # Web application frontend (React)
├── docs/ # Documentation
├── tests/ # Test suite
└── README.md # This file
Contributing
Contributions are welcome! Please see our contributing guidelines.
License
MIT