KaraokeMachine

What it looks like

The idle screen: a partly typed song number in blue, a disc in the corner counting
the songs waiting, and a panel giving the machine's address on the network beside a
QR code — **Idle.** Type a number, or point a phone at the code.

The queue overlay drawn over a dimmed playing screen, listing four waiting songs by
number and title with the singer who asked for each in blue at the right — **The queue.** What is waiting, and who asked for it.

Two lines of the carol Angels From the Realms of Glory sung on the playing screen: each
syllable fills in amber as it is sung, the next line waits below in gray, and when the
first line ends the one after the next takes its row — **Singing.** Each syllable fills in time with the music, and the next line is already waiting.

Every phone is a remote

The singer's remote on a phone: mode buttons for songs, artists and a printed book, a
search box, a language filter, and a list of songs with artist, duration and number,
each with a button to look it up on YouTube and a button to add it to the queue — **Search and queue** from any phone. No app to install.

The remote's now-playing page: the song, the singer it was queued for, a progress
bar, and steppers for key and tempo, a music volume slider and a guide-melody
toggle — **The song as it plays** — key, tempo, guide melody, music volume.

The remote's queue page: the song playing across the top with its transport folded
away behind a toggle, then the queued songs by position, title, artist and the
singer who asked for each, their move and remove buttons folded away behind a second
toggle — **Who is up next**, changeable by anyone. The controls stay folded until asked for.

The offline remote showing its song list, with a favorites mode, an A to Z picker,
and a star beside each song for filing it as a favorite — **The offline remote** adds favorites and an A–Z picker, and works with the machine switched off.

What it does

Songs

MIDI and KAR files with embedded karaoke lyrics, in all three karaoke conventions. The machine detects a legacy encoding such as Shift-JIS.
Video songs — H.264/AAC MP4.
MP3+G songs — an MP3 with a .cdg of the same stem. The machine draws the CD+G graphics itself, in Rust.
UltraStar songs — the .txt a singing game times its words in, beside the MP3 it names. The words light up syllable by syllable.
LRC songs — an .lrc of timed lyrics, beside the MP3 of the same name. A file that times each word lights word by word. A file that times only its lines lights a whole line at a time, and counts you back in after a break.
A 0–10 suitability rating for every file, with a breakdown. It also names the melody channel where it finds one with confidence, and gives a reason where it cannot.

Playing

Full-screen on a television, drawn by SDL3, or in a window on a desktop. F switches between them, and the machine remembers the choice. On Linux it draws straight to DRM/KMS from a bare TTY, with no desktop installed.
Or on a television in another room. With --stream the machine opens no window, and serves picture and sound as one HLS stream. A browser opens it at /watch/, and VLC, Kodi or a television's own player opens /stream/live.m3u8.
Words highlight in time, syllable by syllable, on the sequencer's own clock.
Transpose and tempo per song, and a guide melody that can be muted.
A lyric timing offset in milliseconds, adjustable mid-song, for the picture lag of a television. It moves the highlight only and never the audio, because the microphones are in that audio.
Photographed wallpapers behind the words, crossfading, each one checked for contrast in the band the lyrics sit in.

Remotes, and the API

The machine serves a remote at its own address. Any phone on the network opens it with no app to install, from a QR code on the idle screen.
A standalone offline remote keeps its own copy of a machine's catalog. Browsing, searching and favorites work with the machine switched off.
An HTTP API with a WebSocket event stream covering search, queue, transport, settings, packages, wallpapers, demo mode, microphones and audio output.
mDNS finds the machine on the network.
One admin password, which the machine shows on its idle screen as a six-digit PIN. Everything under /api/v1/admin/ needs it, and nothing a singer does needs it.

Getting a corpus into shape

km-package-builder, a local web server over a folder of source files. Browse, search the lyrics themselves, rate, fix names, group duplicates, and pick songs into packages.
km-pack builds and validates packages, and km-lyrics dumps one file's parsed timeline. km-wallpaper-pack builds a wallpaper set from pictures the lyrics stay readable over.
A printed song book with four columns: artist, number, title and first line. It follows the ring-binder book of a commercial machine, and the machine serves one for its own catalog.

Pictures and instruments, found for it

km-admin finds photographs the lyrics stay readable over. It measures each one in the band of the screen the words occupy. It also offers General MIDI banks from a table of sixty-three, and it sends either to the machine. It sends a file you already have too: a package, a bank, a photograph of your own.

The machine cannot do this itself. A box under a television has no shell and may have no internet, and it should not hold your accounts.

Pictures come from Openverse by default, and you may pass its packs on. Pixabay and Pexels need your own API key, and their terms forbid that. The key field shows those terms.

Numbers that cannot clash

A song's number is bank × 1000 + slot. The slot is the number the package gave the song, 1 to 999. The bank is the block of a thousand the package sits in. Two packages that both number a song 500 do not clash: one is 3500, the other 611500.

A package's bank comes from its id, so its numbers are the same on every machine. A printed song list therefore travels with the file.

A package holds at most 999 songs, and the machine holds a thousand packages. The limit is there to encourage a curated volume rather than a whole folder.

Deliberately not

No scoring of singers.
No bare audio files, because an MP3 on its own has no words in it. No CD+G disc images either, only the file pair.
No video wallpapers: a video song is not a video background.
No pitch shifting of audio.
No microphone processing in the app, because hardware mixes the microphones.
No shaped scripts, and no right-to-left. Thai, Arabic and Indic need a text shaper, and this build does not include one. Japanese and Chinese work, with a font from the system.

Each of these is a decision with a reason. To propose a change, start with the decisions.

Getting it

Every package is on the release page, one file per platform. The sixteen carols are a separate download beside them. To build from source, see BUILDING.md.

Platform	What you get
Windows	A setup program holding all seven products behind component checkboxes. It installs per-user with no UAC prompt. It offers to add itself to your `PATH` and to open `.kmbuild` corpus files. Or a portable folder: unzip it and run it.
macOS	An Apple installer package with the same seven products. Applications go to `/Applications` and command-line tools to `/usr/local`, already on your `PATH`. It asks for your administrator password once.
Debian, Ubuntu	A `.deb` that names its ffmpeg and font dependencies, so apt supplies them. It installs a menu entry, an icon and the `karaokemachine` command, plus the appliance service, switched off.
Any Linux	A `.tar.gz`. Unpack it anywhere and run it, with no root and no package manager. It carries its own ffmpeg.
Android, Google TV	An APK carrying both ABIs, so it installs on a phone and on a television.
Meta Quest	An APK of its own, which puts the machine on a screen in the room. It installs beside the Android APK rather than over it.
iPhone, iPad	An `.ipa` for the machine and one for the remote, both unsigned. You sign them yourself with your own Apple ID. It is the whole machine, and songs arrive through the Files app.

Sixteen carols, free

One package is free to download: Silent Night, Joy to the World and fourteen more carols. Every one is public domain, with four or five verses each.

It is a separate download, and no install carries it. A new install starts empty, because you supply your own songs.

It is the only pack of its kind. A karaoke MIDI holds four or five works: the tune, the arrangement, the words, any translation and the entered notes. Carols are among the few songs where all of them are free.