What’s new here

The pipeline goes from a YouTube search to a singable song in one step: download, stem separation, lyric fetch, alignment, and MV generation run in the background after you queue a track. CJK songs get Cantonese jyutping or Japanese furigana generated inline at subtitle-creation time, not as a separate manual pass. The web player and shared queue are part of the same server, so phones and other devices on the same LAN can request songs and control playback.

What it does

You search YouTube Music by song or artist from the web UI. The server downloads the video, runs AI stem separation to get vocals, backing, and lead tracks, fetches published lyrics, aligns them to the recording, and renders an MV with per-character amber-highlighted subtitles. The processed song lands in a shared queue and plays when its turn comes.

During playback you get pause, seek, replay, next, fullscreen, real-time pitch shifting, and a 0–100% lead vocal volume slider. Devices on the same LAN share the queue; each device plays independently. Songs are cached up to a default 10 GiB limit with LRU eviction. State is persisted in SQLite; progress pushes over SSE.

Processing time on the included benchmarks: about 3 minutes on an Apple M4 Max for a ~4-minute song, and about 81 seconds on an RTX 5090 rig for a ~4-minute song.

Who it’s for

People who want a home KTV setup they control. The README walks through connecting a TV via HDMI mirroring, routing audio through a mixer, and using a phone as a remote. It also suits developers who want a starting point to wire in other content sources (Bilibili, local files) or build a custom front end.

Try it

Needs Python 3.12. The minimal start (UI and queue only, no song processing):

git clone https://github.com/Trinkle23897/karaoke.git
cd karaoke
python3.12 -m venv .venv
.venv/bin/python -m pip install -r karaoke/requirements-api.txt
.venv/bin/python -m karaoke.api

Open http://127.0.0.1:8746/. API docs are at http://127.0.0.1:8746/docs. The front end needs no build step.

Actual song processing also requires FFmpeg, Node.js, inference dependencies, model weights (see SETUP.md), and an OPENAI_API_KEY for online recognition and metadata (a local recognition mode is available). Recommended hardware: 24 GB unified memory on Apple Silicon, or 32 GB RAM plus 16 GB VRAM on an NVIDIA machine.

How mature is it

Created 2026-09-30, last pushed 2026-10-16. 112 stars, 6 forks, 2 contributors, at least 100 commits in the past 90 days, 0 releases, 1 open PR. MIT license. GitHub Actions run Python and JavaScript tests on every push and PR.