Getting Started with nJukebox

Complete installation and setup guide

Notice: This project was developed for my personal use as a touch display hardware jukebox. Please note that the code quality is admittedly poor and was written for functionality over best practices. Use at your own discretion!

System Requirements

  • Go 1.26 or newer — only needed to build; the resulting binary runs on its own
  • Chromium-based browser (Chrome or Edge) for Spotify playback — the Spotify Web Playback SDK needs the Widevine module. Local playback works in any browser.
  • MP3 or FLAC music files (optional, for local library)
  • Spotify Premium account (optional, for streaming)
Note: nJukebox (short for Nico's Jukebox) started as a Node.js project and has been completely rewritten in Go — a single statically linked binary with no runtime dependencies.

Installation Steps

1. Clone the Repository

git clone https://github.com/Nigcra/nJukebox.git
cd nJukebox

2. Build the Binary

go build -o njukebox ./cmd/njukebox
Note: On Windows the binary is njukebox.exe. Go is only needed for this step — the binary is statically linked and has no runtime dependencies.

3. Prepare Your Music Library

Copy your MP3 and FLAC files to the music/ directory (the server creates it on first start):

# Create music directory if it doesn't exist
mkdir -p music

# Copy your music files
cp /path/to/your/music/*.mp3 music/
Important: MP3 and FLAC files are supported. Make sure your files have proper metadata tags for best results. The application scans on startup and watches the folder while it runs.

4. Start the System

One binary serves both the web interface and the data server:

Option A: Start Everything (Recommended)

./njukebox

Option B: Start Components Separately

# Only the data server
./njukebox --data-only

# Only the web server
./njukebox --web-only
Success! nJukebox should now be running at http://127.0.0.1:5500
Tip: Use 127.0.0.1, not localhost — Spotify only accepts unencrypted HTTP redirect URIs for the loopback address.

First Time Setup

1. Music Library Scan

When you first access nJukebox, it will automatically scan your music/ directory for MP3 files. This process:

  • Reads ID3 tags from your MP3 files
  • Extracts album artwork
  • Creates a searchable database
  • Organizes music by artist, album, genre, and decade

2. Admin Access

To access admin features:

  1. Click the lock icon (🔒) in the top-left corner
  2. Enter the default PIN: 1234
  3. You now have access to admin controls
Security: Change the default PIN in the admin settings for production use.

3. Configure Settings

In the admin panel, you can configure:

  • Language: Switch between German and English
  • Auto-DJ: Enable automatic playlist generation
  • Track Lock Time: Prevent recently played tracks from being queued again
  • Visualizations: Customize visual effects

Basic Usage

Browsing Music

  • 🌟 Neu: Recently added tracks
  • 👤 Interpret: Browse by artist
  • 💿 Album: Browse by album
  • 🎷 Genre: Browse by music genre
  • 🕰️ Jahrzehnt: Browse by decade
  • 📊 Top Hits: Most played tracks

Playing Music

  1. Browse or search for a track
  2. Click on any track to add it to the playlist
  3. Use the player controls at the bottom
  4. View the current playlist on the right side

Search

Use the search bar to find music by:

  • Artist name
  • Album title
  • Song title
  • Genre

Next Steps

Need Help? Check our troubleshooting guide or visit the GitHub issues page for support.