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 server URL. You can copy or open the URL in your default browser using the Karaoke Forever Server menu bar or tray icon (macOS or Windows only).

  3. Create your admin account at the welcome page.

  4. In the Preferences panel, tap Media Folders and add your supported media files.

  5. When the media scan is finished, the new songs will appear in the library view. Queue a few songs by tapping an artist’s name, then tapping a song title.

  6. If you are not on the system that will be running the player go there now, browse to the server URL and sign in with your admin account.

  7. You should see a notice at the top that no players are present, so tap the Start Player link. (If you don’t see a notice, your current browser doesn’t support fullscreen mode)

  8. Click Play in the playback controls that appear at the top. The current singer will temporarily have access to these while it’s their turn. Admins always have access to the playback controls.

You are now ready to party!


Karaoke Forever (the “web” app)

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

Library

The library view lists available songs organized by artist. The search/filter area at the top allows searching by artist name and song title, and/or showing only favorited songs.

Tap an artist to reveal their songs, then tap the song title to add it to the queue, or tap its star to favorite it.

Admins can reveal additional options for each song, such as Get Info, by swiping left on the song. As an admin you may see songs with an italicized number at the end, like (2). That means there are two versions (media files) of the same song. The version in the folder highest in the Media Folders list will be queued unless another version of the song has been set as preferred.

Queue

The queue view shows the current, upcoming and previously played songs.

Karaoke Forever tries to distribute singers as fairly as possible by prioritizing the queue based on the amount of time since each user last sang. This also means users joining later in the session won’t be stuck at the back of a long queue.

To remove an upcoming song, swipe left and tap the remove button. Non-admin users can only remove their own songs. Admins also see additional options when swiping left.

Account

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

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?) Each room gets its own song queue and player, and 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 configure Karaoke Forever Server.

My Account

This panel lets users change their name, username or password and sign out.

Player (admin only)

The player view is designed to run fullscreen in the browser on the system handling audio/video for a room. The latest versions of these browsers are currently supported:

To start a player, sign in as an admin to the desired room and a notice will appear with a link to start the player. If you don’t see a notice, your browser doesn’t support fullscreen mode or there is already another player detected in the room (you can still manually navigate to /player).


Karaoke Forever Server

The server software hosts the “web” app and your media files on your local network (it is not designed to be run as a service exposed to the Internet). Built on Node.js 12 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)

macOS

Karaoke Forever Server (Windows)

Windows

Any OS with Node.js 12

  $ npm i -g karaoke-forever
  $ karaoke-forever-server

Supported Media

Karaoke Forever expects media filenames to be in the format “Artist - Title” (see MetaParser for more info). Media files that couldn’t be parsed are logged to a file (to change the level of logging, see Command Line Options).

MetaParser

When determining the artist name and song title for each media file, the filenames are assumed to be in the format “Artist - Title”. This can be configured per-folder using a _kfconfig.js file. When a _kfconfig.js file is encountered in a folder it applies to all files and subfolders within. If any subfolders have their own _kfconfig.js files those will take precedence.

Configuring the Parser

You can configure the default 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 will disable article normalization
  artistOnLeft: true,
  separator: '-',
}

Creating a 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(), // then the default parser (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) 2
-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