A karaoke machine that behaves like a commercial home unit: pick a song by number, it plays, and the words highlight in time. It runs full-screen on a television, and any phone on the network is a remote. A phone searches the catalog and asks for a song, and with a code it changes the key or skips.
A song is one of five things:
- a MIDI file with embedded karaoke lyrics;
- a video file;
- an MP3+G pair: an MP3 with a
.cdgof the same stem beside it; - an UltraStar song: the
.txta singing game times its words in, and the MP3 it names; - an LRC song: an
.lrcof timed lyrics, and the MP3 of the same name.
An MP3 on its own is not a song, because it has no words in it.
It runs on Windows, macOS and Linux, on Android and a Meta Quest, and on an iPhone and an iPad. The pictures and the download are on the site, rrgmc.github.io/karaokemachine.
 |
 |
| Idle. Type a number, or point a phone at the code. | The queue. What is waiting, and who asked for it. |
Singing. Each syllable fills in time with the music, and the next line is already waiting.
 |
 |
 |
 |
| Search and ask for a song from any phone. No app to install. | The song as it plays — key, tempo, guide melody, music volume. | Who is up next, and about when. Each singer has a colour of their own. | The offline remote adds favorites and an A–Z picker, and works with the machine switched off. |
In a headset, the screen hangs on your wall and the queue hangs beside it.
Songs
- Five kinds of song: MIDI and KAR, video, MP3+G, UltraStar and LRC. See Song files and their formats.
- Songs arrive in packages (
.kmpkg). Double-click one or drag it onto the window, and it goes in without a restart. See Getting songs in. - Song numbers that cannot clash. Each package has its own block of a thousand, the same on every machine, so a printed list travels with the file.
- A language per song, and a 0–10 suitability rating for every file, with a breakdown.
- A printable song book of every installed song, as a PDF. See The song book.
Playing
- 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, adjustable mid-song, for the picture lag of a television.
- A queue with singer names, shown over whatever is playing.
- An announcement before each queued song, naming the title and the singer on the whole screen.
- Wallpapers that cycle with a crossfade, and a demo mode that plays songs by itself.
- Every function on the keyboard, and on a television remote. See The keyboard.
- A stream for a television in another room, which a browser or a playlist player opens. See Watching it in another room.
- A Debian box becomes an appliance: it starts with the power and draws with no desktop installed. See On Debian, it is also an appliance.
- Every Linux download for a Raspberry Pi as well, on Raspberry Pi OS based on Debian 13. They are built for arm64 and are not tested on a board.
Remotes and setup
- Any phone on the network is a remote, with no app to install. An offline remote works with the machine switched off. See The remotes.
- Songs play in the order asked, or singers take turns. A guest asks for songs from a phone. A venue chooses turns, and the machine then keeps one song for each singer in the queue.
- A host runs a public night at a bar or a hall, from a tablet, with no second program. See Running a public night.
- Four levels for the room: watch, ask, add a song with no singer, and skip. One admin password covers everything that reconfigures the machine.
- Setup from a browser: songs, pictures, sound banks, and whatever is wrong. See Setting it up from a browser.
- An HTTP API with a WebSocket event stream, and mDNS discovery. See The HTTP API and the network.
Tools
- Package tools that curate a folder of files, build packages and check them. See Getting a corpus into shape.
- A lyric sync editor that puts words on a MIDI file as you tap them. See Putting words on a MIDI file.
- KaraokeMachine Admin finds photographs the lyrics stay readable over, and offers General MIDI banks.
What it does has the whole list, and what the machine leaves out by decision.
The downloads are on the release page, one
file per platform. The manual's Installing
chapter says what each file is. To build from source, see BUILDING.md.
Windows shows "Windows protected your PC" when you open a setup program, because the Windows downloads are not signed. Click More info, then Run anyway.
- Install the machine and start it.
- Double-click a
.kmpkgpackage, or drag it onto the machine's window. The release page has one of sixteen Christmas carols. - Type a song number and press
Enter.
The idle screen shows the machine's address and a QR code. Point a phone at the code to search the catalog and queue a song.
The manual is at
rrgmc.github.io/karaokemachine/docs. Its source is
docs/manual/.
| Part | What it covers |
|---|---|
| Getting started | What it looks like and what it does. Installing on each platform, the Debian appliance, signing for an iPhone, and removing it. |
| Using it | The keyboard, getting songs in, the remotes, running a public night, watching it in another room, setting it up from a browser, and the song book. |
| For a technical reader | The command line, the song file formats, the HTTP API, the tools that make a package, and the lyric sync editor. |
| File | What it is |
|---|---|
docs/manual/ |
Installing and using it. The manual, a chapter per file. |
CHANGELOG.md |
What changed. What a release gave you. |
BUILDING.md |
Building it. Prerequisites, the cargo aliases and the Taskfile, video, the release scripts and CI. |
RELEASE.md |
Cutting a release. The order the steps go in. |
DEPLOYING.md |
Getting it onto a device. Android and iOS, and a Linux box over SSH. |
CONTRIBUTING.md |
Working on it. What to run before a pull request, the conventions, and the invariants. |
SECURITY.md |
Reporting a vulnerability. Privately, through GitHub, and what counts as one. |
CODE_OF_CONDUCT.md |
How people treat each other here. The Contributor Covenant. |
docs/decisions/ |
Why it is the way it is. Every product decision, in topic files, indexed. |
docs/ARCHITECTURE.md |
How it is built. The overview and the crate map; docs/architecture/ has a note per subsystem. |
docs/research/ |
Investigations. Findings, not commitments. |
docs/learning-rust.md |
What a C++ reader needs in order to read this codebase. |
docs/HISTORY.md |
Where it came from. Five attempts at this machine over eighteen years, and where each one stopped. |
CLAUDE.md |
Repository guide, and the rules those documents are kept under. |
You may use the command-line app "km-site-pack" to make a package out of these sites.
MIT OR Apache-2.0, at your option, as every crate in the workspace declares. The texts are
LICENSE-MIT and LICENSE-APACHE.
Unless you say otherwise, a contribution you deliberately submit falls under the same dual license, with no additional terms.
The license covers the application only. A release carries the ffmpeg libraries under the LGPL, with their terms in the folder that holds them. The instrument bank has its own license.
The seven default wallpapers are CC0 photographs, in assets/wallpapers/default-wallpapers.zip.
CREDITS.md beside the zip names each photographer and source page, and says how each image was
edited.
No release includes a pack you build with
tools/cmd/assets/km-wallpaper-pack. Only an Openverse pack
may travel on. A Pixabay or Pexels pack stays on the machine that built it, and manifest.json
records each image's license. See Where a wallpaper pack's photographs may come from.
No program sends telemetry, crash reports or usage data, and none checks for updates. A crash report stays in a file on the computer. A program contacts a host on the internet only when you ask for a download or a picture search. The manual's Privacy chapter names each case.
Rangel Reale (realerangel@gmail.com)