Headphones

Automated music downloader with artist monitoring

Headphones - Automated Music Downloader

Headphones is an automated music downloader written in Python that monitors your favorite artists and automatically downloads new releases. It supports multiple download clients including SABnzbd, NZBget, Transmission, µTorrent, Deluge, and Blackhole.

What is Headphones?

Headphones is a music collection manager that:

Supported Integrations

Installation

Install from the Dashboard

Open App Dashboard → Package Management (/dashboard?mode=packages), find Headphones in the catalog (browse the Automation category or search), and click Install. The dashboard streams the install log live and Headphones appears in your Application Control panel when it finishes. Reinstall and Remove are in the same Package Management panel. To update, use the amber Update badge on the Headphones row in the App Dashboard.

What you see is gated by your account: admins manage any user’s apps; regular users manage their own. See App Management for the full flow.

The installer sets up an isolated Python 3.11 virtual environment, clones the latest Headphones release, registers a systemd service for automatic startup, and configures the web UI behind your nginx reverse proxy.

Install from the CLI (automation)

The CLI runs the same scripts as the Dashboard and is suited to automation and scripting:

qb install headphones -u username
qb reinstall headphones -u username
qb update headphones -u username
qb remove headphones -u username

Full flag reference: CLI Reference.

Enhanced Features

Headphones on QuickBox Pro includes several advanced features:

Service Management

Headphones runs as a systemd service for reliable operation:

Check Service Status

systemctl status headphones@username

Restart Service

systemctl restart headphones@username

View Live Logs

journalctl -u headphones@username -f

Manual Service Control

Start Headphones:

systemctl start headphones@username

Stop Headphones:

systemctl stop headphones@username

Configuration

Initial Setup

After installation, access the Headphones web interface:

First-Time Configuration

1. Download Client Setup

   • Navigate to Settings → Download Settings
   • Select your download client (SABnzbd, NZBget, Transmission, etc.)
   • Enter connection details (host, port, API key)

2. Music Folder Configuration

   • Go to Settings → Quality & Post Processing
   • Set your Destination Directory for downloaded music
   • Configure Folder Format: $Artist/$Album [$Year]
   • Set File Format: $Track $Artist - $Album [$Year] - $Title

3. Search Providers

   • Navigate to Settings → Search Providers
   • Configure NZB indexers or torrent trackers
   • Add API keys for your providers

4. Quality Settings

   • Choose preferred quality (MP3, FLAC, etc.)
   • Set preferred bitrate (e.g., 320kbps for MP3)
   • Enable lossless if desired

Configuration Files

Adding Artists

Manual Artist Addition

1. Click Add Artist in the web interface
2. Search for artist by name
3. Select the correct artist from MusicBrainz
4. Choose albums to monitor
5. Click Add Artist

Import Existing Library

1. Navigate to Manage → Import
2. Select your music directory
3. Headphones will scan and match existing artists
4. Review and confirm imports

Want List

• Headphones monitors all added artists
• Automatically searches for new releases
• Downloads based on your quality preferences
• Organizes and renames files automatically

Advanced Features

Automatic Post-Processing

File Renaming:

Original: 01-track_name.mp3
Renamed: 01 Artist Name - Album Name [2024] - Track Title.mp3

Folder Organization:

Album Art Embedding:

• Automatically downloads album artwork
• Embeds art into audio files
• Saves folder.jpg in album directory

Quality Management

Preferred Quality Options:

• Any quality (fastest downloads)
• Lossless only (FLAC)
• Specific bitrates (320kbps, V0, etc.)
• Quality upgrade automation

Search Interval

Configure how often Headphones searches for new releases:

• Default: 1440 minutes (24 hours)
• Aggressive: 360 minutes (6 hours)
• Conservative: 2880 minutes (48 hours)

Filters and Rules

Required Words:

• Force specific keywords in release names
• Example: FLAC, WEB, Vinyl

Ignored Words:

• Exclude unwanted releases
• Example: REPACK, PROPER, LIMITED

Official Releases Only:

• Skip bootlegs and unofficial releases
• Uses MusicBrainz official release flag

Accessing Headphones

After installation, access the web interface at:

Or via your QuickBox Pro dashboard navigation.

Web Interface Sections

• Home - Overview of wanted albums
• Manage - Your artist library
• Upcoming - New releases from monitored artists
• History - Download history
• Settings - Configuration options
• Logs - Application logs and debugging

Troubleshooting

Common Issues

Headphones not starting:

# Check service status
systemctl status headphones@username
 
# View logs
journalctl -u headphones@username -n 50
 
# Check Python environment
ls -la /opt/username/lib/python/Headphones/.venv/
 
# Reinstall if needed
qb reinstall headphones -u username

Downloads not working:

# Verify download client is running
systemctl status sabnzbd@username  # or transmission@username
 
# Check download client settings in Headphones
# Settings → Download Settings
 
# Test connection to download client
# Headphones will show connection status

Artists not being monitored:

# Check search providers are configured
# Settings → Search Providers
 
# Verify API keys are valid
# Check search interval isn't too long
# Settings → General → Search Interval
 
# Force a search
# Manage → Select artist → Force Search

Python version mismatch after update:

# Update will automatically recreate venv if needed
qb update headphones -u username
 
# Or reinstall to force rebuild
qb reinstall headphones -u username

Permission errors:

# Fix permissions
chown -R username:username /home/username/.config/Headphones
chown -R username:username /opt/username/Headphones
 
# Or reinstall
qb reinstall headphones -u username

Integration with Download Clients

SABnzbd Integration

1. Get SABnzbd API key from SABnzbd web interface
2. In Headphones: Settings → Download Settings
3. Select SABnzbd as download method
4. Enter:
   • Host: localhost
   • Port: 8085 (or your SABnzbd port)
   • API Key: Your SABnzbd API key
5. Test connection

Transmission Integration

1. In Headphones: Settings → Download Settings
2. Select Transmission as download method
3. Enter:
   • Host: localhost
   • Port: 9091
   • Username/Password: Your Transmission credentials
4. Test connection

NZBget Integration

1. Get NZBget username/password
2. In Headphones: Settings → Download Settings
3. Select NZBget as download method
4. Enter:
   • Host: localhost
   • Port: 6789
   • Username: nzbget
   • Password: Your NZBget password
5. Test connection

Best Practices

Additional Resources

Related Applications