Jukebox

A web-based jukebox inspired by the AMI Rowe Laserstar-style CD jukebox. Run it on a local machine and let anyone on your network browse albums, queue songs, and rock out — all through a browser.

Interface

Running the Server

python jukebox.py

The server starts on port 5000 by default and prints the local and network URLs. Configuration lives in config.py.

Adding Music

Put your MP3s in the music/ directory. Two layouts are supported:

Subdirectory per album (recommended):

music/
  Artist - Album Name/
    cover.jpg
    01 - Artist - Track Title.mp3
    02 - Artist - Track Title.mp3

Album art is loaded from cover.jpg, cover.png, folder.jpg, or folder.png inside the album folder. Artist and album name are read from ID3 tags when available, falling back to the folder and filename.

Numbered folders (for explicit ordering):

music/
  01 - Album Name/
  02 - Album Name/

Flat MP3s in music/ root are also supported — they get grouped by their ID3 album tag.

How Credits Work

Each browser session starts with a set number of credits (default: 3). Queuing a song costs 1 credit. When a session runs out of credits, a cooldown period begins — one minute per credit (e.g. 3 credits = 3-minute cooldown). After the cooldown expires, credits are automatically restored and the user can queue again.

Credits and cooldowns are per browser session, not per user account. Refreshing the page or opening a new tab reuses the same session.

Admin Panel

Access the admin panel at /admin using the password set in config.py (default: jukebox).

Now Playing & Queue

• See the currently playing song and the full queue
• Skip — stop the current song and advance to the next in the queue
• Clear Queue — remove all queued songs and stop playback

Credits

• Set Default Credits — change how many credits new sessions receive (1–99). This takes effect for new sessions; existing sessions are not affected until their credits are restored after a cooldown.

Album Sort Order

• Alphabetical — albums sorted by artist then album name (default)
• Manual — drag albums into a custom display order; the order is saved to sort_order.json and persists across restarts

Configuration (config.py)

Setting	Default	Description
MUSIC_DIR	music	Path to music folder
DEFAULT_CREDITS	3	Credits given per new session
MAX_QUEUE_SIZE	50	Maximum songs allowed in the queue
ADMIN_PASSWORD	jukebox	Password for the admin panel
PORT	5000	Port the server listens on
SECRET_KEY	(change this)	Flask session secret — change to a long random string; changing it invalidates all existing sessions