Platforms

The rest of this page describes the Windows build, which is what ships today. The Mac build behaves identically — same console, same tuner, same keys. The TV app moves the console onto your phone, since a television has no keyboard; guest phones work exactly as they do now.

Setting up

Kuthu needs Windows 10 or 11, Python 3.9 or newer and Node.js. When you install Python, tick “Add python.exe to PATH” — almost every setup problem traces back to that box being left unticked.

1. Unzip Kuthu somewhere permanent, e.g. C:\Kuthu.
2. Double-click setup.bat. One time only.
3. Double-click run.bat. This starts the app.

The first run fetches the player runtime — a few minutes and about 250 MB. Every run after that opens straight away. Inside the app, Ctrl+K opens the console, which is where you find songs and build a set.

The API key

You can skip this entirely for your first party. With no key at all, paste YouTube links into Add a song by hand and Kuthu reads the title and channel straight from YouTube. That is enough to run a night.

A free key adds the things that need to search:

• Finding popular dance songs automatically, by language
• Importing a playlist or a nonstop mix
• Hunting down a working copy when a video dies

Getting one

1. Go to console.cloud.google.com
2. Create a project — any name
3. APIs & Services → Library, search for YouTube Data API v3, click Enable
4. APIs & Services → Credentials → Create credentials → API key
5. Paste it into the first box of the Kuthu console and save

The key is stored on your own laptop and is never sent anywhere except to Google. The free tier allows roughly eight full discovery runs a day, and the allowance resets at midnight Pacific. Playback costs nothing — once your set is built you can party with the allowance completely spent.

Building a collection

By hand

Paste any YouTube link into Add a song by hand. Your own picks skip the popularity filter, so an obscure favourite gets in regardless of view count.

By discovery

Find popular dance videos searches each language by view count and scores what comes back, blending absolute views with views-per-day so this year's floor-filler is not buried under a decade-old classic. Each run continues where the last one stopped, so running it again gives you different songs rather than the same ones.

By import

Paste a playlist link and Kuthu imports every video in it. Paste a nonstop mix and it reads the timestamped tracklist out of the description, then looks up each song as its own music video — so you get something to dance to rather than a static image with audio over it.

Tuning the segments

Kuthu's job is to find the forty-five seconds of a song that fills a floor. It does that three ways, from cheapest to most accurate.

1. A structural model — intro, first vocal block, interlude, second vocal block, outro. Costs nothing and is right most of the time. This is what you get on night one.
2. Automatic vocal detection — the tuner listens to a song and proposes where the singing starts, with a confidence figure. Treat anything under about 40% as worth a listen before accepting.
3. Marking by hand — the tuner starts playing twelve seconds before the estimated vocal entry. Press 1 when the singing starts and 2 at the second vocal block. Saved forever.

Segments open a few seconds before the vocal entry on purpose. Dropping the floor exactly on the first syllable feels abrupt; arriving into the hook does not.

Tuner keys

Running the night

Drag the player window to your TV, press Start, then F for fullscreen. Everything after that is one keypress.

Guest requests

A QR code sits on the player screen. Any phone on the same WiFi scans it and gets a page showing what is playing, what is coming, and a search box for your collection. Guests request songs and vote on what other people asked for. Requests land in a queue — press R on the player to review them — and the requester's name shows on the TV when their pick comes up.

Guests search your collection, not YouTube. That keeps requests instant, costs no API allowance, and means nobody can ask for something that will not play. They can also paste a YouTube link or playlist directly, skip the current song, and choose whether a request plays its dance section, the whole song, or from the beginning.

Limits — how many phones, how many requests each, how long between them — live in the Guest requests card in the console. They are all unlimited by default; set them if your crowd needs it.

Ads and YouTube Premium

Kuthu plays videos from YouTube exactly as YouTube serves them. Ads play, and Kuthu never skips, blocks or hides one. That is deliberate: the ad against a film song is how the composer, the singers, the studio and the label get paid for a track you did not buy, and a party that plays fifty songs is fifty songs' worth of royalties reaching them.

An ad is still badly timed for a dance floor. Because the watch page gives Kuthu no readable playhead, elapsed time is the only timing there is — and an ad makes that wrong by however long it ran, which means a song cut off before its chorus. So Kuthu watches its own network traffic for the signs of an ad and holds the segment clock still until it finishes. Nothing of YouTube's page is touched or read. The ad plays in full; your song then gets its full section.

Kuthu is an independent product, not affiliated with, endorsed by or sponsored by YouTube or Google, and earns nothing from Premium subscriptions. YouTube is a trademark of Google LLC.

Your own video files

Point Kuthu at folders of video files and it plays them directly. This gets you more than just convenience: no ads, nothing buffering mid-song, and it works with no internet at all.

.mp4, .m4v, .webm and .mov play. An .mkv or .avi is listed as skipped rather than silently dropped — convert those first. Everything else works identically: vocal marking, segment tuning, guest requests, the language mix.

What you are entitled to play is between you and whoever you got the files from. Kuthu plays what you point it at and does not acquire anything.

Backing up

One file matters: data\library.json. It holds every song you have collected along with every in and out point you have tuned. Copy it to a new machine and your whole collection comes with you. Copy it somewhere safe before you ever use Clear the library.

Troubleshooting

Nothing starts when I double-click run.bat

Almost always Python is not on your PATH. Reinstall Python and tick Add python.exe to PATH, then run setup.bat again. If it complains about Node instead, install Node.js and try again.

Guests' phones cannot reach the QR code page

Check the firewall prompt was allowed for private networks, and that the phones are on the same WiFi as the laptop — guest networks on many routers are deliberately isolated from the main one.

A song starts in the wrong place

Nudge it with , and . and press S. It will never be wrong for that song again.

A song gets cut off before the chorus

Usually an ad eating the clock. Kuthu compensates for the ads it can detect — see Ads and YouTube Premium for what it does and why Premium is the better fix.

A run of discovery comes back with very few songs

Read the message — it names every rejection reason. The usual culprit is the minimum view count, which is high for regional dance tracks. Lower it and run again.

“This video is unavailable” on screen

Videos get pulled and region-blocked between parties. Run Soundcheck before the night and Kuthu re-checks the whole running order, replacing anything dead with another upload of the same song.

Still stuck? Check you are on the latest build first — early access moves quickly.