mbid-poller/README.md

mbid-poller

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.

https://gist.github.com/kchiem/eb998ac3c6f5a96cbec03b8e8c3b21a6

Features

• 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

Prerequisites

• 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

Environment Variables

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

Input Sources (choose one)

The script supports three input methods in order of priority:

1. API URL (Highest Priority)

- 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. JSON File (Second Priority)

- MBID_JSON_FILE=/config/ids.json

Reads from a local JSON file with the same format as the API.

3. Single ID/URL (Lowest Priority)

- MBID_URL=06f71b9e-639c-4903-bf6b-76b8893d3957

Processes a single MusicBrainz artist ID.

JSON Format

For API or file input, use this JSON structure:

[
  {
    "foreignId": "06f71b9e-639c-4903-bf6b-76b8893d3957"
  },
  {
    "foreignId": "c85cfd6b-b1e9-4a50-bd55-eb725f04f7d5"
  }
]

Usage

Docker Compose

1. Create your docker-compose.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"]

2. Build and run:

docker-compose up --build

Finding Profile IDs

To find your Quality and Metadata Profile IDs:

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

Logging

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

Debug Level

Verbose logging for troubleshooting:

[DEBUG] attempt 1: making request...
[DEBUG] Lidarr API Response Code: 201
[INFO] SUCCESS: Artist added to Lidarr

Set LOG_LEVEL=debug to enable debug logging.

How It Works

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

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.