karaoke-gen 0.75.2__tar.gz → 0.76.26__tar.gz

{karaoke_gen-0.75.2 → karaoke_gen-0.76.26}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: karaoke-gen
-Version: 0.75.2
+Version: 0.76.26
 Summary: Generate karaoke videos with synchronized lyrics. Handles the entire process from downloading audio and lyrics to creating the final video with title screens.
 License: MIT
 License-File: LICENSE
@@ -13,6 +13,7 @@ Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Provides-Extra: local-whisper
 Requires-Dist: argparse (>=1.4.0)
 Requires-Dist: attrs (>=24.2.0)
 Requires-Dist: audio-separator[cpu] (>=0.34.0)
@@ -22,7 +23,7 @@ Requires-Dist: dropbox (>=12)
 Requires-Dist: fastapi (>=0.104.0)
 Requires-Dist: fetch-lyrics-from-genius (>=0.1)
 Requires-Dist: ffmpeg-python (>=0.2.0,<0.3.0)
-Requires-Dist: flacfetch (>=0.3)
+Requires-Dist: flacfetch (>=0.9.0)
 Requires-Dist: fonttools (>=4.55)
 Requires-Dist: google-api-python-client
 Requires-Dist: google-auth
@@ -48,6 +49,7 @@ Requires-Dist: lyrics-converter (>=0.2.1)
 Requires-Dist: lyricsgenius (>=3)
 Requires-Dist: matplotlib (>=3)
 Requires-Dist: metaphone (>=0.6)
+Requires-Dist: mutagen (>=1.47)
 Requires-Dist: nest-asyncio (>=1.5)
 Requires-Dist: nltk (>=3.9)
 Requires-Dist: numpy (>=2)
@@ -85,6 +87,7 @@ Requires-Dist: torch (>=2.7)
 Requires-Dist: tqdm (>=4.67)
 Requires-Dist: transformers (>=4.47)
 Requires-Dist: uvicorn[standard] (>=0.24.0)
+Requires-Dist: whisper-timestamped (>=1.15.0) ; extra == "local-whisper"
 Requires-Dist: yt-dlp (>=2024.0.0)
 Project-URL: Documentation, https://github.com/nomadkaraoke/karaoke-gen/blob/main/README.md
 Project-URL: Homepage, https://github.com/nomadkaraoke/karaoke-gen
@@ -94,7 +97,7 @@ Description-Content-Type: text/markdown
 # Karaoke Generator 🎶 🎥 🚀
 
 ![PyPI - Version](https://img.shields.io/pypi/v/karaoke-gen)
-![Python Version](https://img.shields.io/badge/python-3.10+-blue)
+![PyPI - Python Version](https://img.shields.io/pypi/pyversions/karaoke-gen)
 ![Tests](https://github.com/nomadkaraoke/karaoke-gen/workflows/Test%20and%20Publish/badge.svg)
 ![Test Coverage](https://codecov.io/gh/nomadkaraoke/karaoke-gen/branch/main/graph/badge.svg)
 
@@ -147,10 +150,76 @@ pip install karaoke-gen
 This installs both `karaoke-gen` (local) and `karaoke-gen-remote` (cloud) CLIs.
 
 ### Requirements
-- Python 3.10+
+- Python 3.10-3.13
 - FFmpeg
 - For local processing: CUDA-capable GPU or Apple Silicon CPU recommended
 
+### Transcription Provider Setup
+
+**Transcription is required** for creating karaoke videos with synchronized lyrics. The system needs word-level timing data to display lyrics in sync with the music.
+
+#### Option 1: AudioShake (Recommended)
+Commercial service with high-quality transcription. Best for production use.
+
+```bash
+export AUDIOSHAKE_API_TOKEN="your_audioshake_token"
+```
+
+Get an API key at [https://www.audioshake.ai/](https://www.audioshake.ai/) - business only, at time of writing this.
+
+#### Option 2: Local Whisper (No Cloud Required)
+Run Whisper directly on your local machine using whisper-timestamped. Works on CPU, NVIDIA GPU (CUDA), or Apple Silicon.
+
+```bash
+# Install with local Whisper support
+pip install "karaoke-gen[local-whisper]"
+
+# Optional: Configure model size (tiny, base, small, medium, large)
+export WHISPER_MODEL_SIZE="medium"
+
+# Optional: Force specific device (cpu, cuda, mps)
+export WHISPER_DEVICE="cpu"
+```
+
+**Model Size Guide:**
+| Model | VRAM | Speed | Quality |
+|-------|------|-------|---------|
+| tiny | ~1GB | Fast | Lower |
+| base | ~1GB | Fast | Basic |
+| small | ~2GB | Medium | Good |
+| medium | ~5GB | Slower | Better |
+| large | ~10GB | Slowest | Best |
+
+**CPU-Only Installation** (no GPU required):
+```bash
+# Pre-install CPU-only PyTorch first
+pip install torch torchaudio --index-url https://download.pytorch.org/whl/cpu
+pip install "karaoke-gen[local-whisper]"
+```
+
+Local Whisper runs automatically as a fallback when no cloud transcription services are configured.
+
+#### Option 3: Whisper via RunPod
+Cloud-based alternative using OpenAI's Whisper model on RunPod infrastructure.
+
+```bash
+export RUNPOD_API_KEY="your_runpod_key"
+export WHISPER_RUNPOD_ID="your_whisper_endpoint_id"
+```
+
+Set up a Whisper endpoint at [https://www.runpod.io/](https://www.runpod.io/)
+
+#### Without Transcription (Instrumental Only)
+If you don't need synchronized lyrics, use the `--skip-lyrics` flag:
+
+```bash
+karaoke-gen --skip-lyrics "Artist" "Title"
+```
+
+This creates an instrumental-only karaoke video without lyrics overlay.
+
+> **Note:** See `lyrics_transcriber_temp/README.md` for detailed transcription provider configuration options.
+
 ---
 
 ## 🖥️ Local CLI (`karaoke-gen`)
@@ -273,9 +342,11 @@ karaoke-gen-remote \
 |----------|-------------|---------|
 | `KARAOKE_GEN_URL` | Backend service URL | Required |
 | `KARAOKE_GEN_AUTH_TOKEN` | Admin auth token (for protected endpoints) | Optional |
-| `REVIEW_UI_URL` | Lyrics review UI URL | `https://lyrics.nomadkaraoke.com` |
+| `REVIEW_UI_URL` | Lyrics review UI URL | `https://gen.nomadkaraoke.com/lyrics/` |
 | `POLL_INTERVAL` | Seconds between status polls | `5` |
 
+**Note:** The `REVIEW_UI_URL` defaults to the hosted lyrics review UI. For local development, set it to `http://localhost:5173` if you're running the frontend dev server.
+
 ### Authentication
 
 The backend uses token-based authentication for admin operations (bulk delete, internal worker triggers). For basic job submission and monitoring, authentication is optional.
@@ -566,6 +637,111 @@ Check backend health status.
 
 ---
 
+## 🔧 Troubleshooting
+
+### "No suitable files found for processing"
+
+This error occurs during the finalisation step when the `(With Vocals).mkv` file is missing. This file is created during lyrics transcription.
+
+**Most common cause:** No transcription provider configured.
+
+**Quick fix:**
+1. Check if transcription providers are configured:
+   ```bash
+   echo $AUDIOSHAKE_API_TOKEN
+   echo $RUNPOD_API_KEY
+   ```
+
+2. If both are empty, set up a provider (see [Transcription Provider Setup](#transcription-provider-setup))
+
+3. Or use `--skip-lyrics` for instrumental-only karaoke:
+   ```bash
+   karaoke-gen --skip-lyrics "Artist" "Title"
+   ```
+
+**Other causes:**
+- Invalid API credentials - verify your tokens are correct and active
+- API service unavailable - check service status pages
+- Network connectivity issues - ensure you can reach the API endpoints
+- Transcription timeout - try again or use a different provider
+
+### Transcription Fails Silently
+
+If karaoke-gen runs without errors but produces no synchronized lyrics:
+
+1. **Check logs** - Run with `--log_level debug` for detailed output:
+   ```bash
+   karaoke-gen --log_level debug "Artist" "Title"
+   ```
+
+2. **Verify environment variables** - Ensure API tokens are exported in your shell:
+   ```bash
+   # Check if set
+   printenv | grep -E "(AUDIOSHAKE|RUNPOD|WHISPER)"
+   
+   # Set in current session
+   export AUDIOSHAKE_API_TOKEN="your_token"
+   ```
+
+3. **Test API connectivity** - Verify you can reach the transcription service
+
+### "No lyrics found from any source"
+
+This warning means no reference lyrics were fetched from online sources (Genius, Spotify, Musixmatch). The transcription will still work, but auto-correction may be less accurate.
+
+**To fix:**
+- Set `GENIUS_API_TOKEN` for Genius lyrics
+- Set `SPOTIFY_COOKIE_SP_DC` for Spotify lyrics
+- Set `RAPIDAPI_KEY` for Musixmatch lyrics
+- Or provide lyrics manually with `--lyrics_file /path/to/lyrics.txt`
+
+### Video Quality Issues
+
+If the output video has quality problems:
+- Ensure FFmpeg is properly installed: `ffmpeg -version`
+- Check available codecs: `ffmpeg -codecs`
+- For 4K output, ensure sufficient disk space (10GB+ per track)
+
+### Local Whisper Issues
+
+#### GPU Out of Memory
+If you get CUDA out of memory errors:
+```bash
+# Use a smaller model
+export WHISPER_MODEL_SIZE="small"  # or "tiny"
+
+# Or force CPU mode
+export WHISPER_DEVICE="cpu"
+```
+
+#### Slow Transcription on CPU
+CPU transcription is significantly slower than GPU. For faster processing:
+- Use a smaller model (`tiny` or `base`)
+- Consider using cloud transcription (AudioShake or RunPod)
+- On Apple Silicon, the `small` model offers good speed/quality balance
+
+#### Model Download Issues
+Whisper models are downloaded on first use (~1-3GB depending on size). If downloads fail:
+- Check your internet connection
+- Set a custom cache directory: `export WHISPER_CACHE_DIR="/path/with/space"`
+- Models are cached in `~/.cache/whisper/` by default
+
+#### whisper-timestamped Not Found
+If you get "whisper-timestamped is not installed":
+```bash
+pip install "karaoke-gen[local-whisper]"
+# Or install directly:
+pip install whisper-timestamped
+```
+
+#### Disabling Local Whisper
+If you want to disable local Whisper (e.g., to force cloud transcription):
+```bash
+export ENABLE_LOCAL_WHISPER="false"
+```
+
+---
+
 ## 🧪 Development
 
 ### Running Tests

{karaoke_gen-0.75.2 → karaoke_gen-0.76.26}/README.md

@@ -1,7 +1,7 @@
 # Karaoke Generator 🎶 🎥 🚀
 
 ![PyPI - Version](https://img.shields.io/pypi/v/karaoke-gen)
-![Python Version](https://img.shields.io/badge/python-3.10+-blue)
+![PyPI - Python Version](https://img.shields.io/pypi/pyversions/karaoke-gen)
 ![Tests](https://github.com/nomadkaraoke/karaoke-gen/workflows/Test%20and%20Publish/badge.svg)
 ![Test Coverage](https://codecov.io/gh/nomadkaraoke/karaoke-gen/branch/main/graph/badge.svg)
 
@@ -54,10 +54,76 @@ pip install karaoke-gen
 This installs both `karaoke-gen` (local) and `karaoke-gen-remote` (cloud) CLIs.
 
 ### Requirements
-- Python 3.10+
+- Python 3.10-3.13
 - FFmpeg
 - For local processing: CUDA-capable GPU or Apple Silicon CPU recommended
 
+### Transcription Provider Setup
+
+**Transcription is required** for creating karaoke videos with synchronized lyrics. The system needs word-level timing data to display lyrics in sync with the music.
+
+#### Option 1: AudioShake (Recommended)
+Commercial service with high-quality transcription. Best for production use.
+
+```bash
+export AUDIOSHAKE_API_TOKEN="your_audioshake_token"
+```
+
+Get an API key at [https://www.audioshake.ai/](https://www.audioshake.ai/) - business only, at time of writing this.
+
+#### Option 2: Local Whisper (No Cloud Required)
+Run Whisper directly on your local machine using whisper-timestamped. Works on CPU, NVIDIA GPU (CUDA), or Apple Silicon.
+
+```bash
+# Install with local Whisper support
+pip install "karaoke-gen[local-whisper]"
+
+# Optional: Configure model size (tiny, base, small, medium, large)
+export WHISPER_MODEL_SIZE="medium"
+
+# Optional: Force specific device (cpu, cuda, mps)
+export WHISPER_DEVICE="cpu"
+```
+
+**Model Size Guide:**
+| Model | VRAM | Speed | Quality |
+|-------|------|-------|---------|
+| tiny | ~1GB | Fast | Lower |
+| base | ~1GB | Fast | Basic |
+| small | ~2GB | Medium | Good |
+| medium | ~5GB | Slower | Better |
+| large | ~10GB | Slowest | Best |
+
+**CPU-Only Installation** (no GPU required):
+```bash
+# Pre-install CPU-only PyTorch first
+pip install torch torchaudio --index-url https://download.pytorch.org/whl/cpu
+pip install "karaoke-gen[local-whisper]"
+```
+
+Local Whisper runs automatically as a fallback when no cloud transcription services are configured.
+
+#### Option 3: Whisper via RunPod
+Cloud-based alternative using OpenAI's Whisper model on RunPod infrastructure.
+
+```bash
+export RUNPOD_API_KEY="your_runpod_key"
+export WHISPER_RUNPOD_ID="your_whisper_endpoint_id"
+```
+
+Set up a Whisper endpoint at [https://www.runpod.io/](https://www.runpod.io/)
+
+#### Without Transcription (Instrumental Only)
+If you don't need synchronized lyrics, use the `--skip-lyrics` flag:
+
+```bash
+karaoke-gen --skip-lyrics "Artist" "Title"
+```
+
+This creates an instrumental-only karaoke video without lyrics overlay.
+
+> **Note:** See `lyrics_transcriber_temp/README.md` for detailed transcription provider configuration options.
+
 ---
 
 ## 🖥️ Local CLI (`karaoke-gen`)
@@ -180,9 +246,11 @@ karaoke-gen-remote \
 |----------|-------------|---------|
 | `KARAOKE_GEN_URL` | Backend service URL | Required |
 | `KARAOKE_GEN_AUTH_TOKEN` | Admin auth token (for protected endpoints) | Optional |
-| `REVIEW_UI_URL` | Lyrics review UI URL | `https://lyrics.nomadkaraoke.com` |
+| `REVIEW_UI_URL` | Lyrics review UI URL | `https://gen.nomadkaraoke.com/lyrics/` |
 | `POLL_INTERVAL` | Seconds between status polls | `5` |
 
+**Note:** The `REVIEW_UI_URL` defaults to the hosted lyrics review UI. For local development, set it to `http://localhost:5173` if you're running the frontend dev server.
+
 ### Authentication
 
 The backend uses token-based authentication for admin operations (bulk delete, internal worker triggers). For basic job submission and monitoring, authentication is optional.
@@ -473,6 +541,111 @@ Check backend health status.
 
 ---
 
+## 🔧 Troubleshooting
+
+### "No suitable files found for processing"
+
+This error occurs during the finalisation step when the `(With Vocals).mkv` file is missing. This file is created during lyrics transcription.
+
+**Most common cause:** No transcription provider configured.
+
+**Quick fix:**
+1. Check if transcription providers are configured:
+   ```bash
+   echo $AUDIOSHAKE_API_TOKEN
+   echo $RUNPOD_API_KEY
+   ```
+
+2. If both are empty, set up a provider (see [Transcription Provider Setup](#transcription-provider-setup))
+
+3. Or use `--skip-lyrics` for instrumental-only karaoke:
+   ```bash
+   karaoke-gen --skip-lyrics "Artist" "Title"
+   ```
+
+**Other causes:**
+- Invalid API credentials - verify your tokens are correct and active
+- API service unavailable - check service status pages
+- Network connectivity issues - ensure you can reach the API endpoints
+- Transcription timeout - try again or use a different provider
+
+### Transcription Fails Silently
+
+If karaoke-gen runs without errors but produces no synchronized lyrics:
+
+1. **Check logs** - Run with `--log_level debug` for detailed output:
+   ```bash
+   karaoke-gen --log_level debug "Artist" "Title"
+   ```
+
+2. **Verify environment variables** - Ensure API tokens are exported in your shell:
+   ```bash
+   # Check if set
+   printenv | grep -E "(AUDIOSHAKE|RUNPOD|WHISPER)"
+   
+   # Set in current session
+   export AUDIOSHAKE_API_TOKEN="your_token"
+   ```
+
+3. **Test API connectivity** - Verify you can reach the transcription service
+
+### "No lyrics found from any source"
+
+This warning means no reference lyrics were fetched from online sources (Genius, Spotify, Musixmatch). The transcription will still work, but auto-correction may be less accurate.
+
+**To fix:**
+- Set `GENIUS_API_TOKEN` for Genius lyrics
+- Set `SPOTIFY_COOKIE_SP_DC` for Spotify lyrics
+- Set `RAPIDAPI_KEY` for Musixmatch lyrics
+- Or provide lyrics manually with `--lyrics_file /path/to/lyrics.txt`
+
+### Video Quality Issues
+
+If the output video has quality problems:
+- Ensure FFmpeg is properly installed: `ffmpeg -version`
+- Check available codecs: `ffmpeg -codecs`
+- For 4K output, ensure sufficient disk space (10GB+ per track)
+
+### Local Whisper Issues
+
+#### GPU Out of Memory
+If you get CUDA out of memory errors:
+```bash
+# Use a smaller model
+export WHISPER_MODEL_SIZE="small"  # or "tiny"
+
+# Or force CPU mode
+export WHISPER_DEVICE="cpu"
+```
+
+#### Slow Transcription on CPU
+CPU transcription is significantly slower than GPU. For faster processing:
+- Use a smaller model (`tiny` or `base`)
+- Consider using cloud transcription (AudioShake or RunPod)
+- On Apple Silicon, the `small` model offers good speed/quality balance
+
+#### Model Download Issues
+Whisper models are downloaded on first use (~1-3GB depending on size). If downloads fail:
+- Check your internet connection
+- Set a custom cache directory: `export WHISPER_CACHE_DIR="/path/with/space"`
+- Models are cached in `~/.cache/whisper/` by default
+
+#### whisper-timestamped Not Found
+If you get "whisper-timestamped is not installed":
+```bash
+pip install "karaoke-gen[local-whisper]"
+# Or install directly:
+pip install whisper-timestamped
+```
+
+#### Disabling Local Whisper
+If you want to disable local Whisper (e.g., to force cloud transcription):
+```bash
+export ENABLE_LOCAL_WHISPER="false"
+```
+
+---
+
 ## 🧪 Development
 
 ### Running Tests