# 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)

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

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

### Development Setup

```bash
# 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:

```env
# 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

```bash
# 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](https://atisket.pulsewidth.org.uk/) - For adding new releases
   - [Harmony](https://harmony.pulsewidth.org.uk/) - 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](https://lidarr.audio/) - Music collection manager
- [SAMBL](https://github.com/Lioncat6/SAMBL-React) - MusicBrainz comparison tool
- [a-tisket](https://atisket.pulsewidth.org.uk/) - MusicBrainz submission tool
- [Harmony](https://harmony.pulsewidth.org.uk/) - MusicBrainz metadata aggregator