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

  • Node.js 14.0 or higher
  • npm 6.0 or higher
  • Modern web browser with Widevine DRM support (Chrome, Firefox, Safari, Edge)
  • MP3 music files (optional, for local library)
  • Spotify Premium account (optional, for streaming)

Installation Steps

1. Clone the Repository

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

2. Install Dependencies

npm install
Note: This will install all required Node.js packages including Express.js, SQLite3, and other dependencies.

3. Prepare Your Music Library

Copy your MP3 files to the music/ directory:

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

# Copy your MP3 files
cp /path/to/your/music/*.mp3 music/
Important: Only MP3 files are currently supported. Make sure your files have proper ID3 tags for best results.

4. Start the System

nJukebox consists of two components that need to be running:

Option A: Start Everything (Recommended)

npm start

Option B: Start Components Separately

# Terminal 1: Start the data server
npm run server

# Terminal 2: Start the web interface
npm run web
Success! nJukebox should now be running at http://localhost:3000

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.