⚙️ Configuration

Advanced configuration and customization options for nJukebox

Configuration Files

nJukebox uses several configuration files to customize behavior and settings:

nJukebox/ ├── config.json # Main application configuration ├── package.json # Node.js dependencies and scripts ├── data/ │ ├── app.db # Application database (SQLite) │ ├── music.db # Music library database │ └── custom_playlists.json # Saved custom playlists ├── locales/ │ ├── en.json # English translations │ └── de.json # German translations └── lib/ └── valid_genres.js # Supported music genres

Main Configuration (config.json)

The main configuration file contains core application settings:

{
  "app": {
    "port": 3000,
    "host": "localhost",
    "adminPin": "1234",
    "sessionTimeout": 3600,
    "maxPlaylistSize": 100
  },
  "audio": {
    "defaultVolume": 0.8,
    "fadeTime": 3000,
    "trackLockTime": 10,
    "autoDJ": true
  },
  "spotify": {
    "clientId": "",
    "clientSecret": "",
    "redirectUri": "http://localhost:3000/spotify-callback"
  },
  "library": {
    "musicPath": "./music",
    "supportedFormats": [".mp3", ".flac", ".m4a", ".ogg"],
    "autoScan": true,
    "scanInterval": 300000
  },
  "visualization": {
    "enabled": true,
    "effects": ["space", "fire", "particles", "circles"],
    "switchInterval": 30
  },
  "reporting": {
    "enabled": true,
    "gemaCompliance": true,
    "logDetail": "detailed"
  }
}

Configuration Options

Application Settings

Setting Default Description
port 3000 Web server port
host localhost Bind address (use 0.0.0.0 for network access)
adminPin 1234 Admin panel access code
sessionTimeout 3600 Admin session timeout (seconds)
maxPlaylistSize 100 Maximum tracks in playlist

Audio Settings

Setting Default Description
defaultVolume 0.8 Default audio volume (0.0-1.0)
fadeTime 3000 Crossfade duration (milliseconds)
trackLockTime 10 Minutes to lock recently played tracks
autoDJ true Automatically add tracks when playlist is empty

Library Settings

Setting Default Description
musicPath ./music Path to music directory
supportedFormats [".mp3", ".flac", ".m4a", ".ogg"] Supported audio file formats
autoScan true Automatically scan for new music
scanInterval 300000 Auto-scan interval (milliseconds)

Environment Variables

You can override configuration settings using environment variables:

# Server Configuration
NJUKEBOX_PORT=3000
NJUKEBOX_HOST=0.0.0.0
NJUKEBOX_ADMIN_PIN=secretpin123

# Spotify Configuration
SPOTIFY_CLIENT_ID=your_spotify_client_id
SPOTIFY_CLIENT_SECRET=your_spotify_client_secret

# Database Configuration
DATABASE_PATH=./data/custom_location.db
MUSIC_DATABASE_PATH=./data/custom_music.db

# Audio Configuration
DEFAULT_VOLUME=0.8
TRACK_LOCK_TIME=15
AUTO_DJ=true

# Development Mode
DEBUG=true
NODE_ENV=development
Environment Priority: Environment variables take precedence over config.json settings, making them ideal for deployment-specific configurations.

Network Configuration

Local Network Access

To allow access from other devices on your network:

  1. Set host to 0.0.0.0 in config.json
  2. Configure your firewall to allow port 3000
  3. Access using your computer's IP address: http://192.168.1.100:3000

Port Configuration

If port 3000 is in use, change it in multiple places:

  • config.json: Update the port setting
  • Spotify redirect URI: Update in Spotify Developer Dashboard
  • Batch files: Update any startup scripts

Reverse Proxy Setup

For production deployment behind nginx:

server {
    listen 80;
    server_name your-domain.com;

    location / {
        proxy_pass http://localhost:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_cache_bypass $http_upgrade;
    }
}

Database Configuration

SQLite Settings

nJukebox uses SQLite databases for data storage:

  • app.db: Application settings, user sessions, event data
  • music.db: Music library metadata, play counts, ratings

Database Backup

Regular backups are recommended:

# Windows
copy "data\*.db" "backup\%date%\"

# Linux/macOS
cp data/*.db backup/$(date +%Y%m%d)/

Database Migration

When moving between systems:

  1. Copy the entire data/ directory
  2. Update file paths in config.json if needed
  3. Run a library rescan to update paths

Performance Tuning

Memory Usage

Optimize for different system sizes:

System Size Library Size Recommended Settings
Small (Raspberry Pi) < 1,000 tracks Disable auto-scan, lower scan interval
Medium (Home PC) 1,000 - 10,000 tracks Default settings work well
Large (Server) > 10,000 tracks Enable caching, optimize database

Disk Usage

  • Cover Cache: Can grow large; enable periodic cleanup
  • Log Files: Rotate or delete old log files
  • Temporary Files: Clear cache directory periodically

Security Configuration

Admin PIN Security

Important: Always change the default PIN (1234) in production!
  • Use a strong 4-6 digit PIN
  • Avoid sequential numbers (1234, 2345)
  • Don't use dates or personal information
  • Consider rotating PINs periodically

Network Security

  • Local Only: Keep host as localhost for private use
  • Firewall: Restrict port access to trusted networks
  • HTTPS: Use reverse proxy with SSL for external access
  • VPN: Consider VPN access for remote administration

Internationalization

Adding New Languages

To add a new language:

  1. Copy locales/en.json to locales/[language].json
  2. Translate all text strings
  3. Update the language selector in the admin panel
  4. Test all interface elements

Translation File Structure

{
  "app": {
    "title": "nJukebox",
    "subtitle": "Your Digital Music Experience"
  },
  "navigation": {
    "library": "Library",
    "playlist": "Playlist",
    "search": "Search"
  },
  "admin": {
    "login": "Admin Login",
    "settings": "Settings",
    "reports": "Reports"
  }
}

Advanced Customization

Custom CSS

Override default styles by creating custom.css:

/* Custom color scheme */
:root {
    --primary-color: #ff6b35;
    --background-dark: #1a1a2e;
    --text-primary: #ffffff;
}

/* Custom font */
body {
    font-family: 'Your Custom Font', sans-serif;
}

/* Hide admin button for kiosk mode */
.admin-lock {
    display: none !important;
}

Custom Visualization Effects

Add custom visualizations by extending the effects system:

// Custom effect in js/visualizations/custom.js
class CustomEffect {
    constructor(canvas, audioData) {
        this.canvas = canvas;
        this.ctx = canvas.getContext('2d');
        this.audioData = audioData;
    }
    
    render() {
        // Your custom visualization code
    }
}

Custom API Endpoints

Extend the API by adding custom routes:

// In jukebox_server.js
app.get('/api/custom/stats', (req, res) => {
    // Custom statistics endpoint
    res.json({
        totalPlays: getTotalPlays(),
        topGenres: getTopGenres()
    });
});
Customization Tip: Keep custom modifications in separate files when possible to make updating easier while preserving your customizations.

Deployment Configurations

Development Environment

{
  "app": {
    "port": 3000,
    "host": "localhost",
    "adminPin": "1234"
  },
  "audio": {
    "trackLockTime": 1
  },
  "debug": true
}

Production Environment

{
  "app": {
    "port": 8080,
    "host": "0.0.0.0",
    "adminPin": "secure_pin_here"
  },
  "audio": {
    "trackLockTime": 10
  },
  "reporting": {
    "enabled": true,
    "logDetail": "essential"
  },
  "debug": false
}

Party/Event Configuration

{
  "audio": {
    "trackLockTime": 30,
    "autoDJ": true,
    "maxPlaylistSize": 50
  },
  "visualization": {
    "enabled": true,
    "switchInterval": 15
  },
  "reporting": {
    "gemaCompliance": true
  }
}
Configuration Management: Consider using different config files for different environments and switching between them with environment variables or startup scripts.