Karaoke Eternal Server

The server hosts the web app and your media files, and can run on pretty much anything, including a Windows PC, Mac, or a dedicated server like a Raspberry Pi or Synology NAS.

Note that because the player is fully browser-based, it doesn’t need to run on the same system as the server, but it can.


Windows and macOS

The Releases page has the latest packages available for Windows and macOS. Once started, Karaoke Eternal Server will appear in the tray or menu bar:

Karaoke Eternal Server (Windows) Karaoke Eternal Server (Windows)

Karaoke Eternal Server (Windows)

Karaoke Eternal Server (macOS) Karaoke Eternal Server (macOS)

Karaoke Eternal Server (macOS)

See Getting Started if you’re new to Karaoke Eternal.

Docker (Synology NAS)

  1. In the Registry section of DSM’s Docker package, search for and download the radrootllc/karaoke-eternal image.
  2. In the Image section, double-click to launch the image.
  3. The container creation dialog has the following sections:
  1. Click Done. Karaoke Eternal Server should now be running and reachable at http://<your_synology_ip>:8080.

See Getting Started if you’re new to Karaoke Eternal.

Docker (CLI and Compose V2)

The Karaoke Eternal docker image supports amd64, arm64 and arm/v7. It’s modeled after LinuxServer’s images:

Example CLI usage:

  $ docker run \
    --name=karaoke-eternal \
    -v <path_to_database>:/config \
    -v <path_to_media>:/mnt/karaoke \
    -p <host_port>:8080 \
    --restart unless-stopped \

Example docker compose usage:

    image: radrootllc/karaoke-eternal
    container_name: karaoke-eternal
      - <path_to_database>:/config
      - <path_to_media>:/mnt/karaoke
      - <host_port>:8080
    restart: unless-stopped

See Getting Started if you’re new to Karaoke Eternal.


Karaoke Eternal is available as an npm package for systems running Node.js 16 or later.

  1. Install via npm
  $ npm i -g karaoke-eternal
  1. Start the server
  $ karaoke-eternal-server
  1. Watch the output for “Web server running at…” and browse to the server URL.

See Getting Started if you’re new to Karaoke Eternal.

Media Files

The following types are supported:

Your media files should be named in “Artist - Title” format by default (you can configure this). Media with filenames that couldn’t be parsed won’t appear in the library, so check the scanner log or console output for these.

Configuring the Metadata Parser

The media metadata parser can be customized using a _kes.v1.js file. When this file is encountered in a media folder it applies to all files and subfolders (if any subfolders have their own _kes.v1.js, it will take precedence).

You can configure the default metadata parser by returning an object with the options you want to override. For example, if a folder has filenames in the format “Title - Artist”, you could add this _kes.v1.js file:

return {
  artistOnLeft: false, // override default

The default configuration is:

return {
  articles: ['A', 'An', 'The'], // false disables article normalization
  artistOnLeft: true,
  delimiter: '-', // can also be a RegExp

Creating a Metadata Parser (Experimental)

Your _kes.v1.js file can also return a parser creator instead of a configuration object. A parser creator returns a function that can be called for each media file. The default parser is still available so you don’t have to reinvent the wheel.

The following example creates a parser that removes the word ‘junk’ from each filename before handing off to the default parser:

return ({ compose, getDefaultParser, defaultMiddleware }) => {
  function customMiddleware (ctx, next) {
    ctx.name = ctx.name.replace('junk', '')

  return compose(
    customMiddleware,   // our custom pre-processing
    getDefaultParser(), // everything else (optionally accepts a configuration object)

Your parser creator is passed an object with the following properties:

When a media file is scanned, the parser is called with a context object ctx having the following properties:

Middleware may mutate ctx as required. Once finished, the following properties on it will be used:

It’s important that each middleware call next unless you’re done or don’t want the chain to continue.


Karaoke Eternal Server supports the following CLI options and environment variables. The numeric levels used for logs/console are: 0=off, 1=error, 2=warn, 3=info, 4=verbose, 5=debug

Option ENV Description Default
--consoleLevel <number> KES_CONSOLE_LEVEL Web server console output level 4
--data <string> KES_PATH_DATA Absolute path of folder for database files
--logLevel <number> KES_LOG_LEVEL Web server log file level 3
-p, --port <number> KES_PORT Web server port auto
--rotateKey KES_ROTATE_KEY Rotate the session key at startup
--scan KES_SCAN Run the media scanner at startup
--scanConsoleLevel <number> KES_SCAN_CONSOLE_LEVEL Media scanner console output level (default=4) 4
--scanLogLevel <number> KES_SCAN_LOG_LEVEL Media scanner log file level 3
--urlPath <string> KES_URL_PATH Web server base URL path (must begin with a forward slash) /
-v, --version Show version and exit

File Locations

The default locations for the database (database.sqlite3), web server log (server.log) and media scanner log (scanner.log) are as follows: