Karaoke Eternal Server

The server hosts the web app and your media files, and can run on pretty much anything including a Raspberry Pi, NAS or Windows/Mac/Linux desktop. Since the player is fully browser-based, it doesn’t need to run on the same system as the server, but it can.

Installation

Karaoke Eternal Server is available as both a Docker image and an npm package. Both options are multi-platform and multi-architecture (64-bit required).

• Docker
• NPM

Docker

Docker is the preferred way to run Karaoke Eternal Server if you’re using a dedicated server or NAS. The Karaoke Eternal docker image is modeled after LinuxServer’s images and supports both amd64 and arm64.

The easiest way to use the Docker image is via a Compose file, which is a simple YAML format for configuring your container.

Below is an example docker compose file:

services:
  karaoke-eternal:
    container_name: karaoke-eternal
    image: radrootllc/karaoke-eternal
    volumes:
      # Folder where the Karaoke Eternal Server database will be created
      - <path_to_database>:/config
      # Folder(s) containing your media 
      # (inside the app, you'll add /mnt/karaoke to Media Folders)
      - <path_to_media>:/mnt/karaoke
    ports:
      # Web server port
      - <host_port>:8080
    # environment:
    #   - PUID=1000 # optional: user ID to run as
    #   - PGID=1000 # optional: group ID to run as
    #   - TZ=America/New_York # optional: timezone
    restart: unless-stopped

At a minimum, replace <path_to_database>, <path_to_media> and <host_port> with the desired values. See the CLI & ENV section for additional environment settings.

Once the container is running, see Getting Started if you’re new to Karaoke Eternal.

NPM

Karaoke Eternal Server is also available as an npm package:

1. Install Node.js v24 or later if it’s not already installed.

2. In your terminal or command prompt, run the following:

npm i -g karaoke-eternal

3. Start the server by running:

karaoke-eternal-server

4. Look for “Web server running at…” and browse to that server URL.

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

Media Files

The following file types are supported:

• MP3+G (including zipped; also supports .m4a instead of .mp3)
• MP4 video (codec support can vary depending on the browser running the player)

Karaoke Eternal Server expects your media files to 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.

Metadata Parser

You can customize the metadata parser by creating a file named _kes.v2.json in a media folder. It will apply to all media files in the folder, including subfolders. If any subfolders contain their own _kes.v2.json file, that will take precedence instead. These files can be in JSON or JSON5 format - JSON5 is used in the examples below since it’s friendlier for humans.

Basic Configuration

At the most basic, your _kes.v2.json file can alter some or all of the parser’s default configuration, which is:

{
  // used to normalize artist/title; set false to disable
  articles: ['A', 'An', 'The'],

  // assumes filenames are in "Artist - Title" format
  artistOnLeft: true,

  // assumes a hyphen separates the artist and title 
  delimiter: '-',
}

For example, if you had a folder with filenames in the format “Title - Artist” instead, you could create this _kes.v2.json file in it:

{
  artistOnLeft: false, // override default
}

Advanced Templating

If changing the parser’s default configuration doesn’t yield the desired results, you can also define your own “template” to override the result for one or more of these fields:

• artist (string) artist’s name as it will be shown in the library
• artistNorm (string) normalized version of the artist’s name; used for matching and sorting (artist if not set)
• title (string) song’s title as it will be shown in the library
• titleNorm (string) normalized version of the song’s title; used for matching and sorting (title if not set)

For each media file encountered, Karaoke Eternal makes a “context” available to your field template(s). This context includes the fields above (that is, the results from the built-in parser) in addition to:

• name (string) media filename (without extension)
• meta (object) media file’s metadata fields
• dir (string) full path of the containing folder
• dirSep (string) path separator used by the current OS (/ or \)

Field templates are defined using JSON-e syntax. In addition to JSON-e’s built-in methods, a replace method is also provided for simple text replacement. Here are a few examples of how one might use field templates in their _kes.v2.json file:

// explicitly set the artist field
{
  artist: "My Artist's Name",
}

// remove "junk" from anywhere in the parsed artist field
{
  artist: {
    $eval: 'replace(artist, "junk", "")'
  },
}

// remove "junk" case-insensitively from the start of the parsed artist field (regex syntax)
// note: double backslash escapes to a single backslash
{
  artist: {
    $eval: 'replace(artist, "^junk\\s", "i", "")'
  },
}

// set artist and title using the media file's metadata tags
{
  artist: '${meta.artist}',
  title: '${meta.title}',
}

CLI & ENV

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

File Locations

If using the Docker image, the database will be located in the folder you mapped to the container’s /config folder. The container doesn’t write log files by default; use the Docker logs command instead to see the container’s output.

If using the npm installation method, the default locations for the database (database.sqlite3), web server log (server.log) and media scanner log (scanner.log) are as follows:

Windows

• Database: %USERPROFILE%\AppData\Roaming\Karaoke Eternal Server
• Logs: %USERPROFILE%\AppData\Roaming\Karaoke Eternal Server\logs

macOS

• Database: ~/Library/Application Support/Karaoke Eternal Server
• Logs: ~/Library/Logs/Karaoke Eternal Server

Linux

• Database: ~/.config/Karaoke Eternal Server
• Logs: ~/.config/Karaoke Eternal Server/logs