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.

Installation

• Windows and macOS
• Docker (CLI and Compose v2)
• Docker (Synology NAS)
• NPM

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:

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:

• /config should be mapped to a host volume (the database will be stored here)
• media folder(s) should be mapped to host volume(s) (once inside the app, you’ll add these as Media Folders)
• port 8080 should be published to the desired host port
• PUID, PGID and TZ environment variables are optional

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 \
    radrootllc/karaoke-eternal

Example docker compose usage:

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

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

Docker (Synology NAS)

This assumes your Synology DiskStation is running DSM 7.2 or later.

1. In Package Center, open Container Manager.
   • If Container Manager doesn’t appear in the “Installed” section, install it from the “All Packages” section.
2. In the Registry section, search for and download the radrootllc/karaoke-eternal image.
3. In the Image section, select the radrootllc/karaoke-eternal image and click Run.
4. At the General Settings page of the container creation dialog:
   • Choose Enable auto-restart (if desired)
   • Click Next.
5. At the Advanced Settings page:

• Port Settings
  • Set the Local Port to 8080 or another if desired (this will be the port used when browsing to the app URL)
• Volume Settings
  • Click Add Folder, select docker and create a new karaoke-eternal subfolder. Select that subfolder and click Select, then map it to /config. This path will be used to store the database.
  • Click Add Folder again, and this time select your media folder. Map it to /mnt/karaoke (once inside the app, you’ll add this path in Media Folders.
• Click Next.

6. Click Done.
   • Karaoke Eternal Server will run and you should be able to browse to the app URL at http://<your_synology_ip>:8080 (or whichever Local Port you chose in step 5)

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

NPM

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

2. Start the server

  $ karaoke-eternal-server

3. 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:

• MP3+G (.cdg and .mp3 files must be named the same; also supports an .m4a instead of .mp3)
• MP4 video (codec support can vary depending on the browser running the player).

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', '')
    next()
  }

  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:

• compose (function) accepts functions (or arrays of functions) as arguments and returns a single composed function that can be used as a parser
• getDefaultParser (function) gets an instance of the default parser, which itself can be used as middleware. Note that the method must be called because you can optionally pass a configuration object
• defaultMiddleware Map containing the default middleware in order. This can be used to recompose the middleware in your custom parser

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

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

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

• 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)

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

CLI & ENV

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

File Locations

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

macOS

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

Windows

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

Linux

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