Documentation

Quick Start

  1. Install Karaoke Forever Server on the system that will serve the app and media on your local network.

  2. Browse to the app at the server URL. You can copy or open the URL in your default browser using the Karaoke Forever Server menu bar or tray icon in macOS or Windows, respectively.

  1. Create your admin account at the welcome page.

  2. In the Preferences panel, tap Media Folders 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 the room’s 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. Playback and display controls will appear on all your devices now that there’s a player in the room. The current singer sees these during their turn; admins always see these.

Congratulations, you are now ready to press play and party!


Karaoke Forever (the “web” app)

Karaoke Forever is a modern mobile browser app that lets everyone join quickly, 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. The search area at the top allows filtering by artist name, song title and/or your starred songs:

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. You can also tap its star to save it for later. A glowing song indicates that it’s upcoming in the queue. Artists will also glow to show that they contain queued or starred songs.

If there are multiple versions (media files) of a song, admins will see an italicized number in parentheses after the title, and the version in the folder highest in the Media Folders list will be used by default. Admins can also reveal additional options for a song, such as Get Info, by swiping left on it.

Queue

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

Queue view Queue view

Queue view

Singers are prioritized by time since each last sang, so those joining later in the session aren’t penalized and will get right to the front of the queue.

To remove an upcoming song, swipe left and tap X. Normal users can only remove their own songs, but admins can remove anyone’s upcoming song. Admins will also see additional options when swiping left, such as Get Info.

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 Forever 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.

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 (remote-controllable) Display options (remote-controllable)

Display options (remote-controllable)

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, fullscreen support wasn’t detected, but you can still manually navigate to /player.

MP4 videos will be played verbatim, while media with CD+Graphics have additional display options, including MilkDrop -style visualizations. As with the playback controls, admins and the currently-up singer have access to these options.


Karaoke Forever Server

The server software hosts the “web” app and your media files on your local network. Built on Node.js and SQLite , it can run on relatively minimal hardware (Raspberry Pi 3B+).

Installation

macOS or Windows

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

Karaoke Forever Server (macOS) Karaoke Forever Server (macOS)

Karaoke Forever Server (macOS)

Karaoke Forever Server (Windows) Karaoke Forever Server (Windows)

Karaoke Forever Server (Windows)

Any OS with Node.js

Karaoke Forever Server requires Node.js 12 or later.

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

Media Files

The following media formats are supported:

Media filenames are expected to be in “Artist - Title” format by default, but this can be configured per-folder using a _kfconfig.js file. When this file is encountered in a folder it applies to all files and subfolders. If any subfolders have their own _kfconfig.js, that will take precedence.

Media with filenames that couldn’t be parsed are logged to a file (to change the level of logging, see Command Line Options) and won’t appear in the library view.

Configuring the Metadata Parser

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” instead, you could add this _kfconfig.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 _kfconfig.js can also return a parser creator instead of a configuration object. A parser creator returns a function (parser) 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 calls next unless you don’t want the chain to continue (for instance, if you’ve set artist and title manually and want to use them as-is).

Command Line Options

Karaoke Forever Server supports the following command line options:

Option Description Default
-l, --loglevel <number> Log file level (0=off, 1=error, 2=warn, 3=info, 4=verbose, 5=debug) 3
-p, --port <number> Web server port. To use low ports such as 80 you may need to run the app with elevated privileges (not recommended) 0 (auto)
--version Output the Karaoke Forever Server version and exit

File Locations

macOS

Windows


Acknowledgements