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