Documentation

Karaoke Eternal (the app)

Karaoke Eternal is a modern mobile browser app that lets everyone join without having to install anything on their phones. It’s built for touch, but a mouse is supported in desktop browsers (click and drag to emulate swipe gestures).

Library

The library view lists available songs organized by artist, with search and filtering options at the top.

Library view Library view

Library view

Library search/filter view Library search/filter view

Library search/filter view

Tap to expand an artist, then tap a song’s title to queue it. A glowing song and artist indicate they’re upcoming in the queue.

Swiping left on a song reveals the following options:

When a song has multiple versions (media files), admins see an italicized number after the title, and media in the folder highest in the Media Folders list will be used unless specifically set (see Song Info above).

Queue

The queue view shows your room’s previous, current and upcoming songs.

Queue view Queue view

Queue view

Karaoke Eternal automatically arranges the queue using a round-robin method for fairness, without penalizing those joining later in the party. For example, a latecomer will be able to sing right after the next-up singer regardless of how long the queue is.

Swiping left on a queued song reveals the following options:

Normal users can only manage their own queued songs, but admins can manage anyone’s.

Account

The account view lets users manage their account, while admins will see additional panels.

Account view Account view

Account view

Rooms (admin only)

The Rooms panel allows admins to create, edit or remove rooms.

Karaoke Eternal uses “rooms” to organize sessions by time and space (spacetime?) Users choose an open room when signing in, and each room has its own queue.

Rooms can have one of the following statuses:

It’s best to create a new room before each session so that you start with an empty queue, then set the room to closed when finished.

Users (admin only)

Blah blah

Preferences (admin only)

The Preferences panel allows admins to set these global preferences:

My Account

The My Account panel allows users to change their username, password, display name or picture as well as sign out.

Player

The player is a part of the app that’s designed to run fullscreen on the system handling audio/video for a room. The latest versions of these browsers are officially supported:

Player view Player view

Player view

Display options Display options

Display options

To start a player, sign in to the desired room as an admin and a player link will appear at the top. If you don’t see a link that means fullscreen support wasn’t detected, but you can still manually navigate to /player.

Once a player is in the room, playback and display controls will appear. Admins always see these, as well as the current singer during their turn.


Karaoke Eternal Server

The server hosts the app and your media files, and can run on relatively minimal hardware (Raspberry Pi 3B+). Note that players don’t need to run on the same system as the server.

Installation

macOS or Windows

Download and install the latest release. Karaoke Eternal Server runs in the menu bar or tray:

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

Karaoke Eternal Server (macOS)

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

Karaoke Eternal Server (Windows)

See Quick Start if you’re new to Karaoke Eternal.

Docker (Synology)

  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 Quick Start if you’re new to Karaoke Eternal.

Docker (CLI and docker-compose)

Official Docker images are available for x64. Support for additional architectures is planned.

These images are modeled after LinuxServer’s:

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:

---
version: "2.1"
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 Quick Start 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
  1. Start the server
  $ karaoke-eternal-server
  1. Watch the output for “Web server running at…” and browse to the server URL. See Quick Start 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', '')
    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:

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.

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

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:

macOS

Windows

Linux


Quick Start

  1. Install and run Karaoke Eternal Server on the system that will serve the app and your media. Note that players don’t need to run on the same system as the server.

  2. Browse to the server URL. In macOS or Windows you can open the URL using the Karaoke Eternal Server menu bar or tray icon.

  1. Create your admin account at the welcome page.

  2. In the account view you’ll see Preferences. Expand the Media Folders section and add your supported media.

  3. Once the media scanner finishes, head to the library and add some songs by tapping an artist, then tapping a song title. A glowing song means it’s upcoming in the queue.

  4. Now we just need a player. On the system that will output audio/video, browse to the server URL, sign in with your admin account, and tap the Start Player link at the top. If you don’t see a link, your current browser doesn’t support fullscreen mode, but you can still navigate to /player.

  5. In the player, press play and party!

Now that there’s a player in the room, playback and display controls will appear on all your devices. Admins always see these, as well as the current singer during their turn.


Acknowledgements