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 Headphones

Install Headphones for a specific user:

qb install headphones -u username

Installation Process

During installation, QuickBox Pro will:

1. Create Python 3.11 virtual environment - Isolated dependency management
2. Install Node.js 18 - Required for certain functionality
3. Clone Headphones repository - Latest stable version from GitHub
4. Configure systemd service - Auto-start on boot
5. Setup nginx reverse proxy - Secure web access
6. Initialize configuration - Default settings and database

Default port: 8004

CLI Commands

Basic Operations

Usage Examples

Install Headphones:

qb install headphones -u myuser

Update Headphones:

qb update headphones -u myuser

Reinstall (fix corrupted installation):

qb reinstall headphones -u myuser

Remove Headphones and clean up:

qb remove headphones -u myuser

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:

https://your-server-ip/username/headphones

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:

/music/Artist Name/Album Name [2024]/

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:

https://your-server-ip/username/headphones

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

Use Cases

Automated Music Collection

Monitor your favorite artists and automatically download new releases:

• New Album Releases - Get albums as soon as they’re available
• Back Catalog - Automatically fill gaps in your collection
• Quality Upgrades - Replace low-quality files with better versions

Smart Organization

Keep your music library organized:

• Consistent Naming - All files follow the same naming pattern
• Proper Metadata - Accurate artist, album, and track information
• Album Artwork - Beautiful album art for all releases

Quality Control

Maintain a high-quality music library:

• Lossless Priority - Prefer FLAC over lossy formats
• Bitrate Standards - Enforce minimum quality requirements
• Format Conversion - Optional transcoding to preferred formats

Tips & Best Practices

Optimize Search Settings

Configure multiple search providers:

• Use both NZB indexers and torrent trackers
• More sources = better availability
• Redundancy for hard-to-find releases

Adjust search interval:

• Daily checks for active artists
• Weekly for back catalog searches
• Balance between timely downloads and server load

Library Management

Use consistent folder structure:

Regular maintenance:

• Review wanted albums weekly
• Check for failed downloads
• Update search providers as needed

Quality Settings

For archival quality:

• Enable lossless only (FLAC)
• Set minimum bitrate to 1000kbps
• Enable album art embedding

For balanced storage:

• Prefer 320kbps MP3 or V0
• Allow FLAC with transcoding
• Set reasonable quality buffers

Additional Resources

Related Applications