lidarr-mb-gap/README.md

lidarr-mb-gap

A tool to identify missing albums on MusicBrainz from Deezer releases for artists monitored in Lidarr, and generate submission links for easy import.

Features

• 🔍 Automated Discovery: Finds missing albums by comparing Lidarr monitored artists with Deezer releases via SAMBL
• 📊 Dual Reports: Generates both JSON and interactive HTML reports
• 🔗 Submission Links: Automatically generates a-tisket and Harmony links for MusicBrainz submissions
• 🎯 Smart Filtering:
  • Identifies albums that need to be added to MusicBrainz (missing)
  • Identifies albums that need to be updated (exist but need linking/updates)
• 🎨 Interactive HTML Report: Filter by type (add/update) and by artist
• 🐍 Python-based: Clean, functional codebase with proper logging
• ❄️ Nix Support: Fully packaged with Nix flake for reproducible builds

Requirements

• Lidarr instance with API access
• SAMBL instance (defaults to https://sambl.lioncat6.com)
• Python 3.8+ (or use Nix)

Installation

Using Nix (Recommended)

# Run directly
nix run .#lidarr-mb-gap

# Or build and install
nix build .#lidarr-mb-gap
nix profile install .#lidarr-mb-gap

Development Setup

# Enter development shell
nix develop

# Run the script
python src/main.py

# Format code
black src/

Configuration

Create a .env file in the project root:

# Required
LIDARR_URL=http://your-lidarr-instance:8686
LIDARR_API_KEY=your-api-key-here

# Optional
SAMBL_URL=https://sambl.lioncat6.com
MAX_ARTISTS=5  # Limit number of artists processed (0 = no limit)

Getting Your Lidarr API Key

1. Open Lidarr web interface
2. Go to Settings → General
3. Copy your API Key

Usage

Basic Usage

# Using Nix
nix run .#lidarr-mb-gap

# Or if installed
lidarr-mb-gap

The script will:

1. Fetch all artists from Lidarr with monitorNewItems set to "new" or "all"
2. For each artist, query SAMBL to find missing albums on MusicBrainz
3. Generate submission links (a-tisket and Harmony)
4. Create two output files:
   • missing_albums.json - Machine-readable JSON report
   • missing_albums.html - Interactive HTML report with filters

Output Files

missing_albums.json

Contains structured data with:

• albums_to_add: Albums not in MusicBrainz
• albums_to_update: Albums that exist but need updates/linking
• summary: Counts and totals

missing_albums.html

Interactive HTML report with:

• Filter buttons for type (Add/Update/All)
• Filter buttons for each artist
• Clickable submission links (a-tisket and Harmony)
• Direct links to Deezer and MusicBrainz

Project Structure

.
├── src/
│   ├── __init__.py
│   ├── main.py              # Main application logic
│   ├── html_report.py       # HTML report generation
│   └── pyproject.toml      # Python package configuration
├── flake.nix                # Nix flake definition
├── .env                     # Environment variables (create this)
└── README.md

How It Works

1. Lidarr Integration: Queries Lidarr API for monitored artists
2. Deezer Search: Uses Deezer API to find artist IDs
3. SAMBL Comparison: Calls SAMBL's /api/compareArtistAlbums endpoint to compare Deezer releases with MusicBrainz
4. Categorization:
   • Red status or no MBID → Album to ADD
   • Orange status → Album to UPDATE
5. Link Generation: Creates submission links using:
   • a-tisket - For adding new releases
   • Harmony - For adding/updating releases

Logging

The application uses Python's logging module with systemd-friendly output:

• [INFO] - Informational messages
• [WARNING] - Warnings (e.g., missing MusicBrainz ID)
• [ERROR] - Errors (e.g., missing configuration, API failures)

Perfect for running as a systemd service.

Example Output

[INFO] Fetching monitored artists from Lidarr...
[INFO] Found 10 monitored artists
[INFO] ================================================================================
[INFO] Artist: Angus & Julia Stone
[INFO] MusicBrainz ID: abc123-def456-...
[INFO] Albums to ADD (3):
[INFO]       📀 Life Is Strange
[INFO]          Deezer: https://www.deezer.com/album/12345
[INFO]          a-tisket: https://atisket.pulsewidth.org.uk/?url=...
[INFO]          Harmony: https://harmony.pulsewidth.org.uk/release?url=...
...

Troubleshooting

"LIDARR_URL not set" or "LIDARR_API_KEY not set"

• Ensure your .env file exists and contains the required variables
• Check that the file is in the project root directory

"No artists found"

• Verify that you have artists in Lidarr with monitorNewItems set to "new" or "all"
• Check your Lidarr API key is correct

"ModuleNotFoundError: No module named 'html_report'"

• Make sure you're running from the project root
• If using Nix, ensure the flake is properly built

Contributing

1. Format code with black src/
2. Ensure the flake builds: nix flake check
3. Test your changes: nix run .#lidarr-mb-gap

License

This project is open source. Use it as you wish!

Acknowledgments

• Lidarr - Music collection manager
• SAMBL - MusicBrainz comparison tool
• a-tisket - MusicBrainz submission tool
• Harmony - MusicBrainz metadata aggregator