Headphones

Headphones is a Python‑based automation engine that continuously monitors music catalogs, identifies new releases for user‑specified artists, and automatically downloads the corresponding files via NZB or Torrent services. At its core, it acts as a pull‑based scheduler that queries music metadata providers (e.g., MusicBrainz, Discogs) and cross‑references them against local library state. When a match is found, Headphones submits jobs to popular downloaders such as SABnzbd, NZBget, Transmission, µTorrent, Deluge, or a simple file‑system “blackhole” queue. This decouples the discovery logic from the download infrastructure, allowing developers to swap or extend any component without touching the main codebase.

Headphones follows a modular, event‑driven architecture written in Python 3. The core runtime is a Flask‑based web interface that exposes REST endpoints for status, queue manipulation, and configuration. Behind the UI lies a Celery worker pool that processes background tasks (catalog queries, download requests, post‑processing). Persistence is handled by a lightweight SQLite database for configuration and state tracking; however, the design allows swapping to PostgreSQL or MySQL with minimal changes. The application relies on third‑party libraries such as requests for HTTP interactions, feedparser for RSS feeds, and libtorrent for torrent handling. All components communicate via a message broker (default RabbitMQ, with Redis as an alternative), enabling horizontal scaling of workers.

• Artist & Album Tracking: Users can subscribe to artists; Headphones polls release feeds and matches new titles via MusicBrainz identifiers.
• Download Integration: Supports multiple downloaders through a unified interface; developers can implement new downloader adapters by extending the abstract Downloader base class.
• Webhooks & API: Exposes a JSON‑based REST API for external control, plus configurable webhooks that fire on events such as “download started” or “album added”.
• Post‑Processing Hooks: Custom scripts can be executed after a download completes, enabling integration with media servers (e.g., Plex) or automated metadata tagging.
• Extensibility: The plugin system allows adding new providers, downloaders, or UI components without modifying core code.

Headphones is intentionally lightweight, making it suitable for a single‑node deployment on home servers or Docker containers. A standard installation requires Python 3, pip, and a supported download service; the bundled Flask server can be run behind Nginx or Apache with uWSGI. For production, developers typically spin up a Docker Compose stack that includes the Headphones container, a RabbitMQ broker, and optional worker containers. The architecture scales horizontally by adding more Celery workers; each worker can be containerized and load‑balanced behind a reverse proxy. Resource usage is modest—typically < 200 MB RAM and negligible CPU when idle—allowing it to run on low‑power devices like Raspberry Pi.

The plugin API is designed for Python developers: any new provider or downloader must implement a single interface method, after which it can be registered via a configuration file. Headphones also supports webhooks that can trigger external services (e.g., sending a Slack notification when an album is added). The REST API offers endpoints for querying queue status, triggering manual downloads, and retrieving library metadata. Developers can also embed Headphones’ logic into larger media automation workflows (e.g., integrating with Sonarr or Radarr) by consuming its public API.

Headphones’ documentation is hosted on GitHub’s wiki, providing step‑by‑step guides for installation, configuration, and troubleshooting. The codebase follows standard Python conventions (PEP‑8) and includes extensive docstrings, making it approachable for contributors. The active community on IRC (#headphones on Freenode) and GitHub issues ensures timely support. Licensing under GPL‑v3 encourages open collaboration, though it mandates that any derivative work also remain open source. The project’s CI pipeline (Travis CI) guarantees continuous integration across branches, providing confidence in code quality.

• Automated Music Library Maintenance: Deploy Headphones on a NAS to keep an ever‑expanding music collection up‑to‑date without manual intervention.
• Media Server Integration: Combine Headphones with Plex or Emby to automatically fetch new releases and refresh library metadata.
• Custom Download Pipelines: Use the API to trigger downloads from a script that aggregates releases from multiple sources (e.g., RSS feeds, social media).
• Educational Projects: Students learning about event‑driven architecture or Python web services can study Headphones as a real‑world example.

Headphones offers performance (efficient background workers, lightweight UI) and flexibility (plugin architecture, multiple downloader support). Its GPL‑v3 license ensures that any enhancements remain free and open, fostering community growth. Compared to commercial solutions, Headphones requires no proprietary services and can run entirely on a developer’s own hardware, giving full control over data privacy and network traffic. The modular design also means that adding a new download method or metadata provider is often just a few dozen lines of code, making it an attractive choice for developers who need a tailored media automation stack.