a6d2e7f7df
- Updated `flake.nix` to import the new Nix package definition from `nix/package.nix`, streamlining the build process for the lidarr-mb-gap application. - Enhanced the README.md to include new features such as NixOS module support for automated deployment, detailed deployment instructions, and configuration options for SSH and output directories. - Added sections for troubleshooting output file issues and clarified the structure of the project, including new files for deployment and web serving.
234 lines
7.3 KiB
Markdown
234 lines
7.3 KiB
Markdown
# 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
|
|
- 🚀 **NixOS Module**: Automated deployment with systemd service and timer
|
|
- 🌐 **Web Serving**: Ready for deployment with Caddy or any web server
|
|
|
|
## 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)
|
|
OUTPUT_DIR=. # Directory where output files will be written (default: current directory)
|
|
```
|
|
|
|
### 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 in the directory specified by `OUTPUT_DIR` (or current directory):
|
|
- `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
|
|
├── nix/
|
|
│ └── package.nix # Shared Nix package definition
|
|
├── nixos/
|
|
│ ├── lidarr-mb-gap.nix # NixOS module for automated deployment
|
|
│ └── DEPLOYMENT.md # Detailed deployment guide
|
|
├── flake.nix # Nix flake definition
|
|
├── Caddyfile # Caddy configuration for serving reports
|
|
├── .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.
|
|
|
|
## Deployment
|
|
|
|
### NixOS Automated Deployment
|
|
|
|
This project includes a NixOS module for automated deployment with:
|
|
- Systemd service for report generation
|
|
- Systemd timer for periodic execution (configurable)
|
|
- Optional automatic rsync sync to VPS
|
|
- SSH key management for secure VPS access
|
|
- Caddy configuration for serving the HTML report
|
|
|
|
See [nixos/DEPLOYMENT.md](nixos/DEPLOYMENT.md) for detailed deployment instructions.
|
|
|
|
### Quick Start with NixOS
|
|
|
|
```nix
|
|
# In your NixOS configuration
|
|
services.lidarr-mb-gap = {
|
|
enable = true;
|
|
package = lidarr-mb-gap.packages.${system}.lidarr-mb-gap; # From flake
|
|
reportDir = "/var/lib/lidarr-mb-gap/reports";
|
|
envFile = "/var/lib/lidarr-mb-gap/.env";
|
|
runInterval = "daily";
|
|
|
|
# Optional: Auto-sync to VPS
|
|
syncToVPS = true;
|
|
vpsHost = "user@vps";
|
|
vpsPath = "/var/www/html";
|
|
sshKeyFile = "/var/lib/lidarr-mb-gap/.ssh/id_ed25519";
|
|
};
|
|
```
|
|
|
|
For complete setup instructions, including SSH key configuration and Caddy setup, see the [deployment guide](nixos/DEPLOYMENT.md).
|
|
|
|
## 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
|
|
|
|
### Output files not appearing
|
|
- Check that `OUTPUT_DIR` environment variable points to a writable directory
|
|
- Ensure the directory exists and has proper permissions
|
|
- Check logs for any permission errors
|
|
|
|
## 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
|
|
|