| Name | karaoke-gen JSON |
| Version |
0.61.0
JSON |
| download |
| home_page | https://github.com/nomadkaraoke/karaoke-gen |
| Summary | Generate karaoke videos with synchronized lyrics. Handles the entire process from downloading audio and lyrics to creating the final video with title screens. |
| upload_time | 2025-07-26 05:39:24 |
| maintainer | None |
| docs_url | None |
| author | Andrew Beveridge |
| requires_python | <3.14,>=3.10 |
| license | MIT |
| keywords |
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Karaoke Generator 🎶 🎥 🚀
Generate karaoke videos with instrumental audio and synchronized lyrics. Handles the entire process from downloading audio and lyrics to creating the final video with title screens, uploading the resulting video to YouTube.
## Overview
Karaoke Generator is a comprehensive tool for creating high-quality karaoke videos. It automates the entire workflow:
1. **Download** audio and lyrics for a specified song
2. **Separate** audio stems (vocals, instrumental)
3. **Synchronize** lyrics with the audio
4. **Generate** title and end screens
5. **Combine** everything into a polished final video
6. **Organize** and **share** the output files
## Installation
```bash
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
1. **Deploy Audio Separator API** (using Modal.com):
```bash
pip install modal
modal setup
modal deploy audio_separator/remote/deploy_modal.py
```
2. **Set Environment Variable**:
```bash
export AUDIO_SEPARATOR_API_URL="https://USERNAME--audio-separator-api.modal.run"
```
3. **Run Karaoke Generator Normally**:
```bash
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
```bash
# 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:
```bash
# 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
```bash
# Specify custom audio separation models
karaoke-gen --clean_instrumental_model="model_name.ckpt" "Rick Astley" "Never Gonna Give You Up"
```
### Lyrics Handling
```bash
# 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"
```
### Finalisation Options
```bash
# 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"
# 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:
```bash
karaoke-gen --help
```
## Development
### Running Tests
The project uses pytest for testing with unit and integration tests:
```bash
# 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.
## License
MIT
Raw data
{
"_id": null,
"home_page": "https://github.com/nomadkaraoke/karaoke-gen",
"name": "karaoke-gen",
"maintainer": null,
"docs_url": null,
"requires_python": "<3.14,>=3.10",
"maintainer_email": null,
"keywords": null,
"author": "Andrew Beveridge",
"author_email": "andrew@beveridge.uk",
"download_url": "https://files.pythonhosted.org/packages/06/bc/d22309bee4ab9846a1b7796e65bc1a5840622f067d0c79de832f53be7733/karaoke_gen-0.61.0.tar.gz",
"platform": null,
"description": "# Karaoke Generator \ud83c\udfb6 \ud83c\udfa5 \ud83d\ude80\n\n\n\n\n\n\nGenerate karaoke videos with instrumental audio and synchronized lyrics. Handles the entire process from downloading audio and lyrics to creating the final video with title screens, uploading the resulting video to YouTube.\n\n## Overview\n\nKaraoke Generator is a comprehensive tool for creating high-quality karaoke videos. It automates the entire workflow:\n\n1. **Download** audio and lyrics for a specified song\n2. **Separate** audio stems (vocals, instrumental)\n3. **Synchronize** lyrics with the audio\n4. **Generate** title and end screens\n5. **Combine** everything into a polished final video\n6. **Organize** and **share** the output files\n\n## Installation\n\n```bash\npip install karaoke-gen\n```\n\n## Remote Audio Separation \ud83c\udf10\n\nKaraoke 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.\n\n### Benefits of Remote Processing\n- **Save Local Resources**: No more laptop CPU/GPU consumption during separation\n- **Faster Processing**: GPU-accelerated separation on dedicated hardware\n- **Cost Effective**: ~$0.019 per separation job on Modal.com (with $30/month free credits)\n- **Multiple Models**: Process with multiple separation models efficiently\n\n### Setup Remote Processing\n\n1. **Deploy Audio Separator API** (using Modal.com):\n ```bash\n pip install modal\n modal setup\n modal deploy audio_separator/remote/deploy_modal.py\n ```\n\n2. **Set Environment Variable**:\n ```bash\n export AUDIO_SEPARATOR_API_URL=\"https://USERNAME--audio-separator-api.modal.run\"\n ```\n\n3. **Run Karaoke Generator Normally**:\n ```bash\n karaoke-gen \"Rick Astley\" \"Never Gonna Give You Up\"\n ```\n\nThe 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.\n\n### Remote vs Local Processing\n\n| Aspect | Remote Processing | Local Processing |\n|--------|------------------|------------------|\n| **Resource Usage** | Minimal local CPU/GPU | High local CPU/GPU |\n| **Processing Time** | ~2-5 minutes | ~15-45 minutes |\n| **Cost** | ~$0.019 per job | Free (but uses local resources) |\n| **Requirements** | Internet connection | Local GPU recommended |\n| **Setup** | One-time API deployment | Audio separator models download |\n\n## Quick Start\n\n```bash\n# Generate a karaoke video from a YouTube URL\nkaraoke-gen \"https://www.youtube.com/watch?v=dQw4w9WgXcQ\" \"Rick Astley\" \"Never Gonna Give You Up\"\n\n# Or let it search YouTube for you\nkaraoke-gen \"Rick Astley\" \"Never Gonna Give You Up\"\n```\n\n## Workflow Options\n\nKaraoke Gen supports different workflow options to fit your needs:\n\n```bash\n# Run only the preparation phase (download, separate stems, create title screens)\nkaraoke-gen --prep-only \"Rick Astley\" \"Never Gonna Give You Up\"\n\n# Run only the finalisation phase (must be run in a directory prepared by the prep phase)\nkaraoke-gen --finalise-only\n\n# Skip automatic lyrics transcription/synchronization (for manual syncing)\nkaraoke-gen --skip-transcription \"Rick Astley\" \"Never Gonna Give You Up\"\n\n# Skip audio separation (if you already have instrumental)\nkaraoke-gen --skip-separation --existing-instrumental=\"path/to/instrumental.mp3\" \"Rick Astley\" \"Never Gonna Give You Up\"\n```\n\n## Advanced Features\n\n### Audio Processing\n\n```bash\n# Specify custom audio separation models\nkaraoke-gen --clean_instrumental_model=\"model_name.ckpt\" \"Rick Astley\" \"Never Gonna Give You Up\"\n```\n\n### Lyrics Handling\n\n```bash\n# Use a local lyrics file instead of fetching from online\nkaraoke-gen --lyrics_file=\"path/to/lyrics.txt\" \"Rick Astley\" \"Never Gonna Give You Up\"\n\n# Adjust subtitle timing\nkaraoke-gen --subtitle_offset_ms=500 \"Rick Astley\" \"Never Gonna Give You Up\"\n```\n\n### Finalisation Options\n\n```bash\n# Enable CDG ZIP generation\nkaraoke-gen --enable_cdg --style_params_json=\"path/to/style.json\" \"Rick Astley\" \"Never Gonna Give You Up\"\n\n# Enable TXT ZIP generation\nkaraoke-gen --enable_txt \"Rick Astley\" \"Never Gonna Give You Up\"\n\n# Upload to YouTube\nkaraoke-gen --youtube_client_secrets_file=\"path/to/client_secret.json\" --youtube_description_file=\"path/to/description.txt\" \"Rick Astley\" \"Never Gonna Give You Up\"\n\n# Organize files with brand code\nkaraoke-gen --brand_prefix=\"BRAND\" --organised_dir=\"path/to/Tracks-Organized\" \"Rick Astley\" \"Never Gonna Give You Up\"\n```\n\n## Full Command Reference\n\nFor a complete list of options:\n\n```bash\nkaraoke-gen --help\n```\n\n## Development\n\n### Running Tests\n\nThe project uses pytest for testing with unit and integration tests:\n\n```bash\n# Run all tests (unit tests first, then integration tests)\npytest\n\n# Run only unit tests (fast feedback during development)\npytest -m \"not integration\"\n\n# Run only integration tests (comprehensive end-to-end testing)\npytest -m integration\n```\n\nUnit tests run quickly and provide fast feedback, while integration tests are slower but test the full workflow end-to-end.\n\n## License\n\nMIT\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Generate karaoke videos with synchronized lyrics. Handles the entire process from downloading audio and lyrics to creating the final video with title screens.",
"version": "0.61.0",
"project_urls": {
"Documentation": "https://github.com/nomadkaraoke/karaoke-gen/blob/main/README.md",
"Homepage": "https://github.com/nomadkaraoke/karaoke-gen",
"Repository": "https://github.com/nomadkaraoke/karaoke-gen"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "0d27f0399df83fd67d6745100da9ebd871eec715fa28981ab3a76990d13e885b",
"md5": "9a5de1a9d844aad3ca25b6d8145781cb",
"sha256": "b2c3810b4635a6acc6b18d53f890432bac819d4b625ce1fcd49af28f01afd32f"
},
"downloads": -1,
"filename": "karaoke_gen-0.61.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "9a5de1a9d844aad3ca25b6d8145781cb",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<3.14,>=3.10",
"size": 377214,
"upload_time": "2025-07-26T05:39:23",
"upload_time_iso_8601": "2025-07-26T05:39:23.075741Z",
"url": "https://files.pythonhosted.org/packages/0d/27/f0399df83fd67d6745100da9ebd871eec715fa28981ab3a76990d13e885b/karaoke_gen-0.61.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "06bcd22309bee4ab9846a1b7796e65bc1a5840622f067d0c79de832f53be7733",
"md5": "6411d388e66f3358a03dfba18ec1f1c7",
"sha256": "e65e3ef58aca21e2ea6807d369b6b5313e70f3aee1cee850bc257cda19218e96"
},
"downloads": -1,
"filename": "karaoke_gen-0.61.0.tar.gz",
"has_sig": false,
"md5_digest": "6411d388e66f3358a03dfba18ec1f1c7",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<3.14,>=3.10",
"size": 372885,
"upload_time": "2025-07-26T05:39:24",
"upload_time_iso_8601": "2025-07-26T05:39:24.642303Z",
"url": "https://files.pythonhosted.org/packages/06/bc/d22309bee4ab9846a1b7796e65bc1a5840622f067d0c79de832f53be7733/karaoke_gen-0.61.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-26 05:39:24",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "nomadkaraoke",
"github_project": "karaoke-gen",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "karaoke-gen"
}
