LibreKaraoke

This is a free and open-source karaoke software suite created in November 2024 as a very partial replacement of the online catalog provided by Kara Jukebox. It's still in very early alpha development stage, it's neither feature complete nor stable enough to be used in production.

N.B.: Despite aesthetical similarities, LibreKaraoke was written from scratch and does NOT use any source code of Kara Jukebox, both are based on completely different software stacks.

Minimum requirements

A modern up-to-date web browser is necessary to use LibreKaraoke
* Mozilla Firefox
* Google Chromium and derivatives (Google Chrome, Microsoft Edge, Brave, etc)
* Safari

N.B.: Microsoft Internet Explorer and Microsoft Edge Legacy are not supported.

Building from the source code

To build the latest source code from the Git repository, you will need a few tools, namely
* Git
* OpenJDK Java Development Kit >= 21
* Gradle >= 9

Enter git clone git://git.code.sf.net/p/librekaraoke/code librekaraoke to get the source code of the project.
Enter gradle war to create the WAR file that you can further deploy in a Java web server (Jetty, Glassfish, Wildfly, etc).

N.B.: The directory created by Git is then called LibreKaraoke's home, you shouldn't modify it manually except if you want to contribute to the project. This is the installation directory, keeping it clean helps to upgrade and downgrade. LibreKaraoke's base is the location for your configurations and customizations, it's a distinct directory of your choice set with the environment variable named LIBREKARAOKE_BASE, it mimics the structure of LibreKaraoke's home. This separation allows you to adapt LibreKaraoke to your needs while benefiting of the fixes and improvements brought by the upgrades most of the time.

Testing locally without web server

It can be useful for development purposes, but be aware that the behaviour of the suite can be subtly different with and without web server.
* In Mozilla Firefox, go to about:config, set security.fileuri.strict_origin_policy to false
* Press Control + O (or ⌘ + O under OS X), select the file named index.html in src/main/webapp

Deploying with Jetty

You can obtain the WAR file either by building it from the source code or by downloading a released binary.
You simply need to copy the WAR file into $JETTY_BASE/webapps. You can include a context XML file in WEB-INF/jetty-web.xml within the WAR if needed in order to customize the deployment.

Preparing the data

Kara Jukebox uses a Microsoft Access database to store its data into a file named KAR.MDB, you need to convert this file into a file named KAR.MDB.json to reuse the same data in LibreKaraoke.
* Make a backup of KAR.MDB in order to avoid accidental changes before going any further
* Convert KAR.MDB into CSV with MDBOpener
* Convert CSV to JSON with CSV2JSON
* Rename the JSON file KAR.MDB.json
* Replace KAR.MDB.json within the WAR file
* Redeploy the WAR file

Unfortunately, the above method may fail when the file is very big (> 25 MB), the command line utility mdb-tools comes to the rescue:
* mdb-ver KAR.MDB prints JET4
* mdb-tables KAR.MDB prints Karwhich is the name of the only database table used by Kara Jukebox
* mdb-count KAR.MDB Kar prints the number of lines in the table named Kar
* mdb-import -d ';' KAR.MDB Kar KAR.MDB.csv imports the data from the CSV file into the database table
* mdb-json KAR.MDB Kar exports the data from the database table to JSON (actually newline-separated JSON)
* mdb-prop KAR.MDB Kar prints the properties of the database table
* mdb-sql KAR.MDB allows to run SQL queries on the database, don't forget to enter the go command to send your SQL queries to the parser
* mdb-export -d ';' KAR.MDB Kar exports the database table to CSV

As LibreKaraoke requires a JSON array instead of newline-separated JSON objects, you'll need to add the missing commas as array element delimiters and the square brackets at the beginning and at the end of the file.

N.B.: Modifying your data both in Kara Jukebox and in LibreKaraoke is strongly disadvised because the former supports fewer alphabets than the latter and the former has a coarser data model than the latter.

This step is cumbersome for non technical users. A more user-friendly solution will be provided when the suite becomes much more mature and when it's possible to replace Kara Jukebox entirely by LibreKaraoke. However, this task is absolutely not trivial and will require years of work.

Todo list

LibreKaraoke has currently an extremely limited set of features, the following list gives you an idea of this project's future
* Improvement of search results pertinence when entering multiple words
* Detailed instructions to deploy the program on a dedicated server
* Move of the data from the JSON file into a PostGreSQL schema (implying to add some web services)
* Move of the PostGreSQL JDBC URL outside of the WAR file in order to ease the upgrades
* Move of other configuration parameters and customizations into the PostGreSQL schema
* Import of Kara Jukebox's databases
  * Import of the karaoke data from KAR.MDB
  * Import of the karaoke files from the local file system
* Import of LibreKaraoke's database
* Export of LibreKaraoke's database
* Basic cookie-based authentication (the unauthenticated users can only see the list of available songs)
* Administration graphical user interface to edit the list of available songs
  * Multiple alphabets (Latin, Cyrillic, etc)
  * Multiple video file formats (WebM, MKV, MP4, etc)
  * Disabling of a song (suitable to drive a song temporarily unavailable without removing it from the database)
* Administration graphical user interface to use and edit the playlist
* Fine-grained role-based access control to allow or disallow editing the list of available songs
* Administration graphical user interface to view and edit the list of users
* Fully GPDR-compliant and future-proof cookieless authentication based on JWT
* Customer graphical user interface to view the playlist
* Customer graphical user interface to add a song from the list of available songs into the playlist
  * Automatic fair allocation to maximize the number of customers singing during a session and minimize the waiting time
  * Customizable policy to take into account most corner cases
    * Ban of a customer
    * Priorization of a customer
* Customer graphical user interface to remove his/her own previously added song from the playlist
* Merge of multiple LibreKaraoke's databases into one LibreKaraoke's database with conflict management

Legal notice

Playing music in certain situations (typically in public places) may require a license. Moreover, you may have to pay fees to collective rights management organizations (SACEM, SABAM, GEMA, etc) to use protected musical works. LibreKaraoke's contributors are NOT liable for your use of this program, it's up to you to ensure that you respect the laws.

Any PostGreSQL file system level backup given by LibreKaraoke's contributors is provided exclusively for local testing purposes, LibreKaraoke's contributors are still NOT liable for your use of this program when you use such a backup for another purpose.