Add README.md for lidarr-mb-gap project
- Created a comprehensive README.md file detailing the purpose, features, installation instructions, usage, and project structure for the lidarr-mb-gap tool. - Included sections on requirements, configuration, and troubleshooting to assist users in setting up and using the application effectively. - Provided examples of output and logging for better understanding of the tool's functionality.
This commit is contained in:
Danilo Reyes
185
README.md
Normal file
185
README.md
Normal file
@@ -0,0 +1,185 @@
|
|||||||
|
# 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
|
||||||
|
|
||||||
Reference in New Issue
Block a user