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
.cdg of the same stem beside it;
- an UltraStar song: the
.txt a singing game times its words in, and the MP3 it names;
- an LRC song: an
.lrc of 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.
What it looks like
Singing. Each syllable fills in time with the music, and the next line is already
waiting.
In a headset, the screen hangs on your wall and the queue hangs beside it.
Features
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.
Installing
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.
Starting
- Install the machine and start it.
- Double-click a
.kmpkg package, 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
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. |
Documentation
| 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. |
|
Related projects
Sites with downloadable karaoke files
You may use the command-line app "km-site-pack" to make a package out of these sites.
License
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.
Privacy
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.
Author
Rangel Reale ([email protected])
