README.md

---
title: Karaoke Generator
emoji: 🎤
colorFrom: red
colorTo: purple
sdk: gradio
sdk_version: 6.19.0
python_version: '3.13'
app_file: app.py
pinned: false
license: mit
---

# Karaoke Generator

Generate karaoke videos from any audio file with synced, styled lyrics.

## Workflow

### Step 1 — Transcribe
Upload your audio file. The app runs [faster-whisper](https://github.com/SYSTRAN/faster-whisper) (int8 quantized, 4–8× faster than standard Whisper on CPU) to produce a **word-timestamped JSON file** you can download and edit.

For **Gujarati audio**, selecting Language = Gujarati + Model = small automatically uses the fine-tuned [`vasista22/whisper-gujarati-small`](https://huggingface.co/vasista22/whisper-gujarati-small) model — trained on 430+ hours of Gujarati speech data for much better accuracy.

Edit the JSON externally (paste into Gemini/ChatGPT to fix wrong words, or edit timestamps manually). The format is easy to work with:

```json
[
  {
    "start": 1.23,
    "end": 3.45,
    "text": "He Karunanidhi Swami",
    "words": [
      {"word": "He",           "start": 1.23, "end": 1.50},
      {"word": "Karunanidhi", "start": 1.50, "end": 2.20},
      {"word": "Swami",       "start": 2.20, "end": 3.45}
    ]
  }
]
```

### Step 2 — Generate Video
Paste your refined JSON, upload audio + optional background image, choose styling (font, colors, outline), and click **Generate**. The app renders a 1280×720 MP4 with:
- **Left-to-right color sweep** on each word as it's sung (`\kf` ASS karaoke tag)
- Your chosen background image (scaled/cropped to fill)
- Custom font, font size, and three independent color pickers

## Vocal Removal Options
| Method | Speed | Notes |
|--------|-------|-------|
| Skip | Instant | Lyrics over original audio |
| Fast (ffmpeg) | ~5 sec | Phase-cancellation, stereo files only |
| AI (MDX-Net) | 5–10 min | Best quality, CPU only on free tier |

## Tech Stack
- [faster-whisper](https://github.com/SYSTRAN/faster-whisper) — transcription
- [vasista22/whisper-gujarati-small](https://huggingface.co/vasista22/whisper-gujarati-small) — Gujarati fine-tune
- [audio-separator](https://github.com/karaokenerds/python-audio-separator) — MDX-Net vocal removal
- [ffmpeg](https://ffmpeg.org/) — video rendering with ASS karaoke subtitles
- [Gradio](https://gradio.app/) — UI