KansaiGaijin/mbid-poller
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Added better debugging. Corrected Lidarr import. Updated README.md

Browse Source
This commit is contained in:
Jamie Miller
2025-09-28 06:57:46 +00:00
parent e40ec97435
commit 4658c38890
3 changed files with 595 additions and 347 deletions
Download Patch File Download Diff File Expand all files Collapse all files

222
README.md
View File

@@ -1,101 +1,185 @@
# MBID Poller
# mbid-poller
This project provides a polling mechanism, packaged in a **Docker container**, to routinely check the MusicBrainz ID (MBID) status for items and then optionally trigger a search in a **Lidarr** instance.
A polling script to automatically add artists to Lidarr based on MusicBrainz IDs (MBIDs). The script fetches artist data from the Lidarr.audio API and adds them to your Lidarr instance with proper monitoring and quality profiles.
---
With thanks to @kchiem for their perl script as the key piece of this image.
## 💡 Acknowledgements
https://gist.github.com/kchiem/eb998ac3c6f5a96cbec03b8e8c3b21a6
The core logic for the polling mechanism in this project is based on an existing script generously shared by GitHub user **kchiem**.
## Features
We are utilizing and adapting the Perl script found in the following public Gist:
- **Multiple Input Sources**: Support for API endpoints, JSON files, or single artist IDs
- **Robust Error Handling**: Automatic retries for API timeouts and comprehensive error logging
- **Validation**: Skips artists without albums to avoid cluttering your library
- **Configurable Logging**: Switch between info and debug logging levels
- **Docker Support**: Run as a containerized service
* **Original Script:** `kchiem/lidarr-ping.dist`
* **Link:** https://gist.github.com/kchiem/eb998ac3c6f5a96cbec03b8e8c3b21a6
## Prerequisites
We appreciate kchiem's contribution to the community!
- Docker and Docker Compose
- A running Lidarr instance
- Lidarr API key (found in Lidarr Settings > General > API Key)
- Quality and Metadata profile IDs from your Lidarr instance
---
## Configuration
## 🚀 Setup and Usage
### Environment Variables
This project is designed to run as a service alongside a **Lidarr** instance using Docker Compose.
| Variable | Description | Required | Default |
|----------|-------------|----------|---------|
| `LIDARR_BASE` | URL to your Lidarr instance | Yes | `http://localhost:8686` |
| `LIDARR_API_KEY` | Your Lidarr API key | Yes | - |
| `LIDARR_ROOT_FOLDER` | Music root folder path in Lidarr | Yes | `/music` |
| `LIDARR_QUALITY_PROFILE_ID` | Quality profile ID from Lidarr | No | `1` |
| `LIDARR_METADATA_PROFILE_ID` | Metadata profile ID from Lidarr | No | `1` |
| `LOG_LEVEL` | Logging verbosity (`info` or `debug`) | No | `info` |
### 1. Prerequisites
### Input Sources (choose one)
Before starting, ensure you have:
The script supports three input methods in order of priority:
1. **Docker** and **Docker Compose** installed.
2. A running **Lidarr** instance.
3. The project files (`Dockerfile`, `poller.pl`, `docker-compose.yaml`, etc.) in a single directory.
#### 1. API URL (Highest Priority)
```yaml
- MBID_API_URL=http://192.168.0.73:5110/artists
```
Fetches artist data from an API endpoint that returns JSON array with `foreignId` fields.
### 2. Configure Docker Compose
#### 2. JSON File (Second Priority)
```yaml
- MBID_JSON_FILE=/config/ids.json
```
Reads from a local JSON file with the same format as the API.
The `mbid-poller` container needs to communicate with your Lidarr instance.
#### 3. Single ID/URL (Lowest Priority)
```yaml
- MBID_URL=06f71b9e-639c-4903-bf6b-76b8893d3957
```
Processes a single MusicBrainz artist ID.
1. **Rename the Example:** Rename the provided `docker-compose.yaml.example` to `docker-compose.yaml`.
2. **Network Setup:** Ensure the `lidarr` and `mbid-poller` services are on the **same Docker network** (e.g., `example_network`). If you use a different setup (like host network), update `LIDARR_BASE` accordingly.
3. **Lidarr Base URL:** The script uses the Lidarr API to automatically add the polled artists. You must set the following environment variables in the mbid-poller service:
### JSON Format
| Environment Variable | Description | Source in Lidarr |
| :--- | :--- | :--- |
| `LIDARR_BASE` | The internal URL of your Lidarr instance. | N/A (Docker network alias) |
| `LIDARR_API_KEY` | Your Lidarr API key. | Settings > General > API Key |
| `LIDARR_ROOT_FOLDER` | The path for your music root folder as seen by Lidarr. | Settings > Media Management > Root Folders |
| `LIDARR_QUALITY_PROFILE_ID` | The numerical ID for the desired Quality Profile. (Default is 1) | Settings > Profiles > Quality Profiles (Inspect element to find ID) |
| `LIDARR_METADATA_PROFILE_ID` | The numerical ID for the desired Metadata Profile. (Default is 1) | Settings > Profiles > Metadata Profiles (Inspect element to find ID) |
For API or file input, use this JSON structure:
```json
[
{
"foreignId": "06f71b9e-639c-4903-bf6b-76b8893d3957"
},
{
"foreignId": "c85cfd6b-b1e9-4a50-bd55-eb725f04f7d5"
}
]
```
### 3. Choose the MBID Input Source
## Usage
The `poller.pl` script supports three different ways to provide MBIDs, in order of priority:
### Docker Compose
| Environment Variable | Priority | Description |
| :--- | :--- | :--- |
| `MBID_API_URL` | **1st** (Highest) | A URL that returns a JSON array of objects, each containing a `foreignId` field. |
| `MBID_JSON_FILE` | **2nd** | A path to a local JSON file (like `ids.json`) containing the MBID array. |
| `MBID_URL` | **3rd** (Lowest) | A single MusicBrainz URL or ID to process. |
1. Create your `docker-compose.yaml`:
In your `docker-compose.yaml`, **only one** of these should be uncommented and set.
```yaml
services:
mbid-poller:
build: .
container_name: mbid-poller
environment:
# Lidarr Configuration
- LIDARR_BASE=https://your-lidarr-instance.com
- LIDARR_API_KEY=your_api_key_here
- LIDARR_ROOT_FOLDER=/data/music
- LIDARR_QUALITY_PROFILE_ID=1
- LIDARR_METADATA_PROFILE_ID=1
# Logging
- LOG_LEVEL=info # Use 'debug' for troubleshooting
# Input Source (choose one)
- MBID_API_URL=http://your-api-server:5110/artists
# - MBID_JSON_FILE=/config/ids.json
# - MBID_URL=06f71b9e-639c-4903-bf6b-76b8893d3957
volumes:
- ./ids.json:/config/ids.json:ro # Only needed if using JSON file
restart: "no" # Run once
command: ["/app/poller.pl"]
```
#### A. Using a JSON File (Recommended for simple setups)
2. Build and run:
```bash
docker-compose up --build
```
1. Place your list of IDs in an `ids.json` file in the project directory (or adjust the volume mount).
2. In `docker-compose.yaml`, **comment out** `MBID_API_URL` and **uncomment** `MBID_JSON_FILE`:
### Finding Profile IDs
```yaml
# ... mbid-poller environment section
environment:
# ...
- LIDARR_BASE=http://lidarr:8686
- LIDARR_API_KEY=your_lidarr_api_key_here
- LIDARR_ROOT_FOLDER=/music # Example
- LIDARR_QUALITY_PROFILE_ID=1 # Example
- LIDARR_METADATA_PROFILE_ID=1 # Example
# - MBID_API_URL=
- MBID_JSON_FILE=/config/ids.json
# - MBID_URL=...
volumes:
- ./ids.json:/config/ids.json:ro # Maps your local file into the container
```
To find your Quality and Metadata Profile IDs:
### 4. Build and Run
1. Go to Lidarr Settings > Profiles > Quality Profiles
2. Note the ID number in the URL when editing a profile
3. Go to Lidarr Settings > Profiles > Metadata Profiles
4. Note the ID number in the URL when editing a profile
With your files and `docker-compose.yaml` configured, you can build and run the poller.
## Logging
1. **Build the Container:** This compiles the Perl dependencies using the `Dockerfile`.
### Info Level (Default)
Clean output showing processing progress and results:
```
--- Processing (1/165): 00d0f0fa-a48c-416d-b4ff-25a290ce82d8 ---
- artist: Imagine Dragons
- artist already exists in Lidarr or validation failed
```
```bash
docker compose build mbid-poller
```
### Debug Level
Verbose logging for troubleshooting:
```
[DEBUG] attempt 1: making request...
[DEBUG] Lidarr API Response Code: 201
[INFO] SUCCESS: Artist added to Lidarr
```
2. **Run the Poller:** Since the `restart` policy is set to `"no"`, this command will run the script once and exit.
Set `LOG_LEVEL=debug` to enable debug logging.
```bash
docker compose up mbid-poller
```
## How It Works
The script will fetch the IDs, then loop through them. For each ID, it will:
1. **Fetch Artist List**: Retrieves MBIDs from your configured source
2. **Query Lidarr.audio API**: Gets detailed artist information for each MBID
3. **Validate**: Checks if artist has albums (skips if none)
4. **Add to Lidarr**: Creates artist entry with monitoring enabled
5. **Handle Duplicates**: Skips artists that already exist
1. Ping the external MusicBrainz API until a successful response is received.
2. Use the Lidarr API to automatically add the artist and set it to monitored.
3. Output a confirmation or error message before moving to the next artist.
## Error Handling
- **API Timeouts**: Automatic retry with exponential backoff (max 15 attempts)
- **Missing Data**: Validates required fields before processing
- **Duplicate Artists**: Gracefully handles artists already in Lidarr
- **Network Issues**: Comprehensive error logging with specific HTTP status codes
## Troubleshooting
### Common Issues
1. **Artists not being added**: Set `LOG_LEVEL=debug` to see detailed API responses
2. **Authentication errors**: Verify your `LIDARR_API_KEY` is correct
3. **Profile errors**: Ensure `LIDARR_QUALITY_PROFILE_ID` and `LIDARR_METADATA_PROFILE_ID` exist
4. **Path issues**: Check that `LIDARR_ROOT_FOLDER` exists and is writable
### Debug Mode
Enable debug logging to see:
- Full API request/response details
- Artist data field mapping
- Lidarr API payloads
- Step-by-step processing information
## Output
The script provides a summary at completion:
```
=== Processing Complete ===
Summary:
Total processed: 165
Successfully added: 142
Errors: 3
Skipped (validation failed): 20
```
## License
This project builds upon the original work by @kchiem and is provided as-is for personal use.