Deploying Headphones

Introduction

Headphones is an automated music downloader for NZB and Torrent written in Python. It monitors your favorite artists and automatically downloads their albums when they become available. Headphones integrates with popular download clients like SABnzbd, NZBget, Transmission, Deluge, and qBittorrent to fetch music from Usenet and torrent sources.

Built for music enthusiasts who want to maintain a comprehensive library, Headphones uses MusicBrainz for metadata, ensuring accurate album information and proper organization. The application features a web-based interface for managing artists, monitoring downloads, and configuring automation rules.

Key highlights of Headphones:

• Automated Downloads: Monitor artists and download new releases automatically
• Multiple Sources: Support for NZB (Usenet) and Torrent downloads
• Download Clients: Integration with SABnzbd, NZBget, Transmission, Deluge, and more
• MusicBrainz Integration: Accurate metadata and album matching
• Quality Preferences: Set preferred audio quality and format
• Post-Processing: Automatic file organization and renaming
• Notifications: Alerts for new downloads and errors
• Web Interface: Manage your music queue from any browser

This guide walks through deploying Headphones on Klutch.sh using Docker, configuring download clients, and setting up automated music acquisition.

Prerequisites

Before deploying Headphones on Klutch.sh, ensure you have:

• A Klutch.sh account
• A GitHub account with a repository for your Headphones configuration
• A download client (SABnzbd, NZBget, or torrent client)
• Usenet or torrent indexer accounts
• Basic familiarity with Docker and containerization concepts

Preparing Your Repository

Create a GitHub repository with the following structure:

headphones-deploy/
├── Dockerfile
├── .dockerignore
└── README.md

Creating the Dockerfile

Create a Dockerfile using the LinuxServer Headphones image:

FROM lscr.io/linuxserver/headphones:latest

# Environment variables for configuration
ENV PUID=${PUID:-1000}
ENV PGID=${PGID:-1000}
ENV TZ=${TZ:-Etc/UTC}

# Expose the web interface port
EXPOSE 8181

# Health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=30s --retries=3 \
  CMD curl -f http://localhost:8181/ || exit 1

Advanced Dockerfile with Custom Settings

FROM lscr.io/linuxserver/headphones:latest

ENV PUID=${PUID:-1000}
ENV PGID=${PGID:-1000}
ENV TZ=${TZ:-Etc/UTC}
ENV UMASK=022

# Create necessary directories
RUN mkdir -p /config /downloads /music

EXPOSE 8181

HEALTHCHECK --interval=30s --timeout=10s --start-period=30s --retries=3 \
  CMD curl -f http://localhost:8181/ || exit 1

Environment Variables Reference

Variable	Required	Default	Description
PUID	No	1000	User ID for file ownership
PGID	No	1000	Group ID for file ownership
TZ	No	Etc/UTC	Container timezone
UMASK	No	022	File permission mask

Deploying Headphones on Klutch.sh

Push Your Repository to GitHub

git init
git add Dockerfile .dockerignore README.md
git commit -m "Initial Headphones deployment configuration"
git remote add origin https://github.com/yourusername/headphones-deploy.git
git push -u origin main

Create a New Project on Klutch.sh

Navigate to the Klutch.sh dashboard and create a new project named “headphones” or “music-downloader”.

Create a New App

Within your project, create a new app. Connect your GitHub account and select your Headphones repository.

Configure HTTP Traffic

• Select HTTP as the traffic type
• Set the internal port to 8181

Set Environment Variables

Configure the following environment variables:

Variable	Value
PUID	1000
PGID	1000
TZ	Your timezone (e.g., America/New_York)

Attach Persistent Volumes

Mount Path	Recommended Size	Purpose
/config	5 GB	Headphones configuration and database
/downloads	100+ GB	Downloaded music files
/music	500+ GB	Organized music library

Deploy Your Application

Click Deploy to start the build process. Klutch.sh will build the container, attach volumes, and start Headphones with HTTPS enabled.

Access Headphones

Once deployment completes, access Headphones at https://your-app-name.klutch.sh.

Configuring Headphones

Initial Setup

1. Access the web interface
2. Navigate to Settings
3. Configure your download client connection
4. Set up indexer credentials
5. Configure music library paths

Download Client Configuration

SABnzbd Setup

1. Go to Settings > Download Settings
2. Select SABnzbd as your download client
3. Enter your SABnzbd URL and API key
4. Configure download categories

Torrent Client Setup

1. Go to Settings > Download Settings
2. Select your torrent client (Transmission, Deluge, etc.)
3. Enter connection details
4. Set up download directories

Adding Artists

1. Navigate to Manage > Add Artists
2. Search for an artist by name
3. Select the correct artist from results
4. Choose which albums to monitor
5. Headphones will search for missing albums

Quality Settings

1. Go to Settings > Quality & Post Processing
2. Set preferred audio quality (FLAC, 320kbps, etc.)
3. Configure file naming templates
4. Set up post-processing scripts if needed

Notifications

Configure notifications for new downloads:

1. Go to Settings > Notifications
2. Enable your preferred notification method
3. Available options include:
   • Email
   • Pushover
   • Pushbullet
   • Join
   • Telegram

Troubleshooting

Downloads Not Starting

• Verify download client connection settings
• Check indexer credentials are valid
• Ensure download client is accessible from Headphones

Artist Not Found

• Search using different name variations
• Check MusicBrainz for correct artist ID
• Try adding artist manually with MusicBrainz ID

Permission Issues

• Verify PUID/PGID match your storage permissions
• Check volume mount paths are correct
• Ensure download and music directories are writable

Additional Resources

• Headphones GitHub Repository
• LinuxServer Headphones Docker
• LinuxServer Documentation
• MusicBrainz
• Klutch.sh Persistent Volumes
• Klutch.sh Deployments

Conclusion

Deploying Headphones on Klutch.sh provides an automated music acquisition system that monitors your favorite artists and downloads their releases automatically. With support for multiple download clients and sources, quality preferences, and post-processing, Headphones streamlines building and maintaining your music library. The persistent storage ensures your configuration and downloaded music are preserved across deployments.