Karaoke Eternal

Search the Marketplace for Karaoke Eternal on Ubuntu 24.04, then choose your VM size and OS disk size.

Attach an NSG that allows TCP 22 (SSH) from your management network. Also allow TCP 80 / 443 from the networks your guests connect from. These ports carry the web application, including the websockets for the live song queue. On a home or venue network, that usually means your own LAN.

If the server is reachable from the internet, front port 80 with TLS (see the HTTPS section below).

RG="karaoke-prod"; LOCATION="eastus"; VM_NAME="karaoke-01" IMAGE_URN="sac1647283583153:karaoke-eternal-ubuntu-24-04:default:latest" SSH_KEY="$(cat ~/.ssh/id_rsa.pub)" az group create --name "$RG" --location "$LOCATION" az network vnet create -g "$RG" --name ke-vnet --address-prefix 10.91.0.0/16 --subnet-name ke-subnet --subnet-prefix 10.91.1.0/24 az network nsg create -g "$RG" --name ke-nsg az network nsg rule create -g "$RG" --nsg-name ke-nsg --name allow-ssh --priority 100 \
  --source-address-prefixes "<your-mgmt-cidr>" --destination-port-ranges 22 --access Allow --protocol Tcp az network nsg rule create -g "$RG" --nsg-name ke-nsg --name allow-web --priority 110 \
  --source-address-prefixes "<your-mgmt-cidr>" --destination-port-ranges 80 443 --access Allow --protocol Tcp
# Accept the Marketplace terms once per subscription (required before the first CLI deploy)
az vm image terms accept --urn sac1647283583153:karaoke-eternal-ubuntu-24-04:default:latest
az vm create -g "$RG" --name "$VM_NAME" --image "$IMAGE_URN" \
  --size Standard_B2s --storage-sku StandardSSD_LRS --os-disk-size-gb 256 \
  --admin-username azureuser --ssh-key-values "$SSH_KEY" \
  --vnet-name ke-vnet --subnet ke-subnet --nsg ke-nsg --public-ip-sku Standard

Give the OS disk enough room for your library. The setting --os-disk-size-gb 256 holds roughly 20,000 MP3 plus CDG song pairs.

ssh azureuser@<vm-ip>

First boot takes about thirty seconds. When it finishes, both units are active and nginx answers on port 80.

sudo systemctl is-active karaoke-eternal nginx
sudo systemctl is-enabled karaoke-eternal nginx curl -s -o /dev/null -w 'Karaoke Eternal: HTTP %{http_code}\n' http://127.0.0.1/

Expected output:

active active enabled enabled Karaoke Eternal: HTTP 200

The listening sockets show the separation. nginx holds port 80 for the outside world, and the application's own port 8080 is reachable only from inside the instance. systemd enforces that separation, not just convention.

First boot generated two secrets on this VM. One is your administrator password. The other is the password for the default room, which everyone joining the party needs.

sudo cat /root/karaoke-eternal-credentials.txt

Expected output (your values will differ, because every instance gets its own):

# Karaoke Eternal on Ubuntu 24.04 - per-VM credentials (root only, chmod 600)
# ... KARAOKE_ETERNAL_URL=http://<vm-ip>/ KARAOKE_ETERNAL_ADMIN_USER=kadmin KARAOKE_ETERNAL_ADMIN_PASSWORD=<admin-password> KARAOKE_ETERNAL_ROOM_PASSWORD=<room-password> KARAOKE_ETERNAL_MEDIA_DIR=/srv/karaoke

The file is 0600 root:root, so only root can read it. Once you are signed in, change the administrator password from the app's Account page. Keep the room password to hand, because it is what you give your guests.

Browse to http://<vm-ip>/. Pick Room 1 and enter the room password from Step 5. Then sign in with the administrator username and password.

The library folder is /srv/karaoke, and it ships empty. Your instance's admin user is a member of the karaoke group, so you can copy files straight into the folder over SSH from your own machine:

rsync -av --progress ~/my-karaoke-library/ azureuser@<vm-ip>:/srv/karaoke/

Karaoke Eternal recognises:

• MP3 + CDG: the classic MP3+G format. Keep the two files side by side with the same base name, for example Some Artist - Some Song.mp3 and Some Artist - Some Song.cdg.
• ZIP: a zip containing one MP3 (or M4A) and its CDG sidecar.
• MP4: karaoke videos with the lyrics burned in.

Name files Artist - Title, and the scanner splits them into artist and title automatically.

On the instance, confirm what has landed:

ls -la /srv/karaoke | sed -n '1,6p' find /srv/karaoke -type f | wc -l

On a freshly deployed instance, the command reports an empty folder, which is how the image ships:

total 8 drwxrwsr-x 2 karaoke karaoke 4096 Aug 7 10:48 . drwxr-xr-x 3 root root 4096 Aug 7 10:48 .. 0

In the app, open the smiley menu, choose Preferences, and press Rescan next to /srv/karaoke. New files are also picked up automatically while the folder is being watched.

You can trigger the same scan from the shell:

CF=/root/karaoke-eternal-credentials.txt
U=$(sudo grep '^KARAOKE_ETERNAL_ADMIN_USER=' "$CF" | cut -d= -f2-)
P=$(sudo grep '^KARAOKE_ETERNAL_ADMIN_PASSWORD=' "$CF" | cut -d= -f2-) sudo node /usr/local/sbin/karaoke-eternal-ctl.mjs req http://127.0.0.1 "$U" "$P" - - GET /api/prefs/paths/scan

Expected output:

STATUS 200

When the scan finishes, the library page lists your songs by artist.

To confirm the appliance works before you copy your real library across, generate a short sound-check clip on the instance. Nothing is downloaded. ffmpeg synthesises the video and the tone locally. ffmpeg is not part of the image, and the steps remove it again at the end.

sudo apt-get -o DPkg::Lock::Timeout=120 update -qq sudo apt-get -o DPkg::Lock::Timeout=120 install -y --no-install-recommends ffmpeg >/dev/null ffmpeg -version 2>/dev/null | sed -n '1p' command -v ffmpeg >/dev/null || { echo 'FAIL: ffmpeg did not install'; exit 1; }

sudo -u karaoke ffmpeg -nostdin -hide_banner -loglevel error -y \
  -f lavfi -i "sine=frequency=440:duration=12" \
  -f lavfi -i "color=c=0x101828:s=1280x720:d=12" \
  -filter_complex "[1:v]drawtext=fontfile=/usr/share/fonts/truetype/dejavu/DejaVuSans-Bold.ttf:text='YOUR LIBRARY IS WORKING':fontcolor=white:fontsize=54:x=(w-tw)/2:y=(h-th)/2[v]" \
  -map "[v]" -map 0:a -c:v libx264 -pix_fmt yuv420p -c:a aac -shortest \
  "/srv/karaoke/sac - Library Test.mp4" ls -l "/srv/karaoke/sac - Library Test.mp4" [ -s "/srv/karaoke/sac - Library Test.mp4" ] || { echo 'FAIL: test clip not generated'; exit 1; }

CF=/root/karaoke-eternal-credentials.txt
U=$(sudo grep '^KARAOKE_ETERNAL_ADMIN_USER=' "$CF" | cut -d= -f2-)
P=$(sudo grep '^KARAOKE_ETERNAL_ADMIN_PASSWORD=' "$CF" | cut -d= -f2-) sudo node /usr/local/sbin/karaoke-eternal-ctl.mjs req http://127.0.0.1 "$U" "$P" - - GET /api/prefs/paths/scan for i in $(seq 1 30); do
N=$(sudo sqlite3 /var/lib/karaoke-eternal/data/database.sqlite3 'SELECT COUNT(*) FROM songs;') [ "$N" != "0" ] && break sleep 2 done
sudo sqlite3 /var/lib/karaoke-eternal/data/database.sqlite3 \
  'SELECT artists.name || " - " || songs.title FROM songs JOIN artists USING(artistId);' [ "$(sudo sqlite3 /var/lib/karaoke-eternal/data/database.sqlite3 'SELECT COUNT(*) FROM songs;')" = "1" ] \
  || { echo 'FAIL: the test clip did not appear in the library'; exit 1; }

Expected output:

STATUS 200 sac - Library Test

The song is now in the library and can be queued from any phone signed in to the room. When you are done, remove it to return the instance to a clean state:

sudo rm -f "/srv/karaoke/sac - Library Test.mp4" CF=/root/karaoke-eternal-credentials.txt
U=$(sudo grep '^KARAOKE_ETERNAL_ADMIN_USER=' "$CF" | cut -d= -f2-)
P=$(sudo grep '^KARAOKE_ETERNAL_ADMIN_PASSWORD=' "$CF" | cut -d= -f2-) sudo node /usr/local/sbin/karaoke-eternal-ctl.mjs req http://127.0.0.1 "$U" "$P" - - GET /api/prefs/paths/scan
sudo apt-get -o DPkg::Lock::Timeout=120 purge -y ffmpeg >/dev/null
sudo apt-get -o DPkg::Lock::Timeout=120 autoremove --purge -y >/dev/null command -v ffmpeg >/dev/null && { echo 'FAIL: ffmpeg still installed'; exit 1; } echo "ffmpeg removed again" sleep 3 echo "songs now: $(sudo sqlite3 /var/lib/karaoke-eternal/data/database.sqlite3 'SELECT COUNT(*) FROM songs;')"

By default, nobody can create their own account. That is the safe setting for a server reachable from a browser. For a party you will usually want guests to join, so open it deliberately:

• Sign in as the administrator and open Preferences from the smiley menu.
• Under Rooms, edit Room 1.
• Tick Allow new guest accounts. Also tick Allow new user accounts if you want regulars to keep a named account and their starred songs.
• Save.

Now anyone who can reach the server, enters the room password and picks a name can join. Give your guests the URL and the room password. The room password keeps the party to the people in the room.

Everyone browses the same library from their phone and taps a song to join the queue.

On the machine wired to the TV or projector, sign in as the administrator. Open the player tab in the bottom bar, or browse to http://<vm-ip>/player. Press play, and the player screen takes over. Lyrics for MP3+G songs are rendered live from the CDG stream, MP4 songs play as video, and a visualiser fills the background. Use the full-screen control at the top right.

As each song ends, the player advances automatically to whoever is next in the queue, so nobody has to touch the machine again all night.

Every live action rides a socket.io websocket: a guest queueing a song, the queue reordering, the player advancing and the progress bar on everyone's phone. The nginx vhost in this image is already configured to proxy that upgrade, with long timeouts so a connection is never reaped mid-song.

You can watch the handshake succeed:

UP=$(curl -s -i -N -m 8 -H 'Connection: Upgrade' -H 'Upgrade: websocket' \
  -H "Sec-WebSocket-Key: $(head -c 16 /dev/urandom | base64)" -H 'Sec-WebSocket-Version: 13' \
  'http://127.0.0.1/socket.io/?EIO=4&transport=websocket' 2>/dev/null | sed -n '1,3p' || true) printf '%s\n' "$UP" printf '%s' "$UP" | grep -q '101 Switching Protocols' || { echo 'FAIL: nginx did not proxy the websocket upgrade'; exit 1; }

Expected output:

HTTP/1.1 101 Switching Protocols Upgrade: websocket Connection: Upgrade

101 Switching Protocols confirms that the upgrade works. A reverse proxy that answers 200 here has silently broken the live queue. This is why the image ships the proxy already configured.

You can go one step further and confirm that an authenticated session receives server-pushed events over that websocket:

CF=/root/karaoke-eternal-credentials.txt
U=$(sudo grep '^KARAOKE_ETERNAL_ADMIN_USER=' "$CF" | cut -d= -f2-)
P=$(sudo grep '^KARAOKE_ETERNAL_ADMIN_PASSWORD=' "$CF" | cut -d= -f2-)
R=$(sudo grep '^KARAOKE_ETERNAL_ROOM_PASSWORD=' "$CF" | cut -d= -f2-) sudo node /usr/local/sbin/karaoke-eternal-ctl.mjs wscheck http://127.0.0.1 "$U" "$P" 1 "$R"

Expected output:

OK:websocket-upgraded 'HTTP/1.1 101 Switching Protocols' authenticated=kadmin live-events=prefs-push+queue-push

Rooms let you run more than one party from the same library, or reset the evening with a clean queue. Under Preferences, you can create a room, give it its own password, and open or close it.

Closing a room stops anyone new from joining without stopping the music. Guests already in the room stay put.

The default Room 1 was created for you at first boot with the room password from Step 5.

cat /opt/karaoke-eternal/SAC_VERSION node -v nginx -v ls /opt/karaoke-eternal/build/client | sed -n '1,4p'

Expected output:

2.0.2 v24.19.0 nginx version: nginx/1.24.0 (Ubuntu) 240.e30082e5be751ce05500.js 447.e30082e5be751ce05500.js 715.e30082e5be751ce05500.js 851.e30082e5be751ce05500.css

The client bundles under build/client are the compiled React app. They are built into the image, so a customer VM never needs a build toolchain, an internet connection or a CDN to serve the interface.

Everything that matters lives on the OS disk and is included in your normal VM backups or snapshots:

• /srv/karaoke: your karaoke files
• /var/lib/karaoke-eternal/data/database.sqlite3: accounts, rooms, queues, stars and the media index
• /root/karaoke-eternal-credentials.txt: the credentials generated on this instance

To back up the database safely while the service is running, use SQLite's own online backup:

sudo sqlite3 /var/lib/karaoke-eternal/data/database.sqlite3 ".backup '/var/tmp/karaoke-eternal-backup.sqlite3'"
sudo ls -l /var/tmp/karaoke-eternal-backup.sqlite3

The media index is derived data. If you ever lose the database, you lose only accounts, rooms and stars, and a rescan rebuilds your library.

If the server is reachable from the internet, put TLS in front of it. Point a DNS record at the VM and open port 443 in the NSG. Then run:

sudo apt-get update && sudo apt-get install -y certbot python3-certbot-nginx
sudo certbot --nginx -d your-domain.example.com

Certbot edits the shipped vhost in place and keeps the websocket and media proxy settings. The live queue keeps working over wss://.