Karaoke Eternal: a self-hosted karaoke server for parties

The problem Karaoke Eternal solves: queueing at a party without a laptop in the middle

Karaoke nights fail on logistics, not on music. One person ends up holding a laptop, taking requests by shouting, and typing filenames into a player while everyone waits. Karaoke Eternal moves that job into the guests' own phones. The README describes the goal plainly: "Host awesome karaoke parties where everyone can easily find and queue songs from their phone's browser." The audience is the person who already has a folder of karaoke files and a machine that can stay on during the party, not someone looking for a streaming catalogue.

The project has three named parts. The server serves the web app and your media files, and the README says it runs on "pretty much anything", listing a Windows PC, a Mac, a Raspberry Pi, or a Synology NAS. The app is the mobile browser interface guests use. The player is described as "just another part of the app", meant to run fullscreen on the system that handles audio and video for a room. That split is the whole design: the phone is the remote, the machine with the speakers is the output.

Two features set the tone. First, joining is meant to be low-friction, with QR codes and guest accounts, so nobody has to install anything. Second, queues are dynamic rather than fixed. The README says dynamic queues "keep parties fair, fun and no-fuss", though it does not spell out the rotation rule on the page itself. If fairness policy matters to you, that is a detail to check in the docs rather than assume.

How the server, app and player fit together

The repository layout confirms the split the README describes. There are separate top-level directories for server, src, shared, config and docs, plus a build pipeline in package.json with build:server and build:client targets. The server compiles TypeScript from server/main.ts into build/server/main.js, and the client is bundled by webpack. The shared directory suggests code used by both sides, which is consistent with a web app and a server written in one language.

The server is a Node.js HTTP service built on Koa, judging by the @koa/router and ctx-compose dependencies in package.json. Persistence is SQLite, which appears in the repository topics. Authentication uses bcryptjs for password hashing, and the presence of json-e and schemas under server/lib/schemas points to JSON-driven configuration or data definitions. None of that is documented on the README page; it is what the dependency list and file tree show.

Media handling is the part that defines the product. The player supports MP3+G, which the README describes as "MP3 with CDG lyrics; including zipped", plus MP4 videos and WebGL visualizations with automatic lyrics background removal. That CDG support is why the project exists in this shape. CDG is a graphics stream paired with an audio file, so the player has to composite lyrics over audio in real time rather than play a finished video. The README notes that microphones are not required, because the player only outputs music, which leaves your audio setup entirely to you.

Multiple rooms are supported, optionally password-protected, each with its own queue. That is the mechanism behind running more than one party or more than one stage from a single server.

Installing Karaoke Eternal Server and running it in development

The README does not reproduce installation commands. It points to a Getting Started page at karaoke-eternal.com/docs/getting-started/ and to a server documentation page that lists several installation methods. If you want a packaged install, that page is where the project says to look, and the repository does not duplicate it here.

What the README does give is the development path. It requires Node.js v24 or later, and package.json sets the same floor, with npm >=11. Fork and clone the repository, then install dependencies:

npm i

Then start the development server. The README says to look for "Web server running at" in the output to find the server URL:

npm run dev

That script runs tsx watch against server/main.ts with NODE_ENV=development and the port flag -p 3000, so the development server listens on port 3000 by default. For a production-style build, package.json defines the sequence separately:

npm run build
npm run serve

build runs build:server and build:client in order; serve runs node build/server/main.js. There is also a published binary name, karaoke-eternal-server, pointing at build/server/main.js, which is what a packaged install would invoke. What you should see after starting is a web server URL in the console, which you open in a browser to reach the app, then open again on a phone to join as a guest.

Where Karaoke Eternal is the wrong tool

The project ships no songs. It serves media you already own, so an empty media directory means an empty karaoke night. Anyone expecting a subscription catalogue, a store, or a search across licensed tracks will find nothing here, and the README makes no such promise.

The player also does not process microphones. The README states this directly: microphones are not required since the player only outputs music. That is a deliberate boundary, and it means vocal effects, pitch correction, and microphone mixing are outside the project. You bring a mixer or an amplifier if you want them.

There is a second, quieter constraint in the development setup. Node.js v24 or later is a hard floor in package.json, and npm >=11 with it. If your NAS or Raspberry Pi ships an older Node.js and you cannot upgrade it, the development route is closed to you, and your only path is whatever packaged installation method the docs describe. The README does not say what those methods require.

Finally, consider the failure mode of a self-hosted party system: if the machine running the server sleeps, reboots, or drops off the network mid-party, the app and the player go with it. Nothing in the README describes failover, a second server, or offline queueing. The queue lives with the server.

How Karaoke Eternal differs from a desktop karaoke player

The closest alternative in practice is a desktop karaoke application that plays MP3+G and MP4 files from a local folder on the same machine that outputs audio. Those tools have a real advantage: one process, one machine, no network, no browser. If you sing alone or with a small group around one screen, a desktop player asks less of you.

The difference is the queue and the remote. A desktop player puts song selection on the machine that plays the music, so someone has to stand at it or pass a keyboard around. Karaoke Eternal splits that: the server holds the library and the queue, the player renders audio and video fullscreen, and any guest with a phone browser joins, searches, and adds a song. The README frames this as joining "with QR codes and guest accounts", which is the mechanism that makes the split worth the extra moving parts.

Dynamic queues are the other divergence. A desktop player typically plays a list in the order it was built. Karaoke Eternal's README describes dynamic queues that keep parties fair, and supports multiple simultaneous rooms, each optionally password-protected. Running two queues from one server is something a single-machine desktop player does not attempt.

The trade is operational. A desktop player is one install. Karaoke Eternal is a server you keep running, a browser player you keep open, and guests on your network. Choose it when the queue is the problem, not when the playback is.

Maintenance, licensing and what upgrading costs you

The repository is not archived, and its last push was on 2026-08-19, about a month before this writing. Releases are less frequent than pushes: v2.0.0 landed on 2025-12-26, v2.0.1 on 2026-01-10, and v2.0.2 on 2026-02-15. So the codebase moves between releases, and the tagged versions arrive on their own schedule. If you deploy from a release rather than from main, plan on roughly quarterly version bumps based on that history, and check CHANGELOG.md, which sits at the repository root, before you upgrade.

The licence is ISC, a permissive licence that appears in both the repository metadata and the LICENSE file. It permits use, modification, and redistribution with the licence text retained. That is a statement about the licence text, not legal advice about your situation; if you plan to redistribute the server inside a product, read the LICENSE file and talk to someone qualified.

The practical maintenance cost is the Node.js floor. package.json requires Node.js >=24 and npm >=11, and dependencies are pinned with caret ranges plus two overrides for is-generator-function and get-generator-function. That means upgrades are not fire-and-forget: a Node.js major version bump on your host can invalidate the runtime your install expects. The README gives no upgrade procedure and does not document rollback, so treat the CHANGELOG and a backup of your SQLite database as your safety net, and verify the database path in your own configuration rather than assuming a default.

Editorial conclusion

Adopt Karaoke Eternal if you host parties and already keep a local library of MP3+G or MP4 karaoke files, and you are willing to run a Node.js 24 server on a machine that stays on. Do not adopt it if you expect a hosted service, a song catalogue, or a phone app that does the singing itself: it has none of those. Before committing, read the Getting Started page at karaoke-eternal.com and confirm which installation method matches your hardware, since the README names the page but does not reproduce the steps.

Frequently asked questions

Official sources

1. bhj/KaraokeEternal on GitHub
2. License: ISC
3. Project website
4. README
5. Releases