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)
```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. JSON File (Second Priority)
```yaml
- 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)
```yaml
- MBID_URL=06f71b9e-639c-4903-bf6b-76b8893d3957
```
Processes a single MusicBrainz artist ID.

### JSON Format

For API or file input, use this JSON structure:
```json
[
  {
    "foreignId": "06f71b9e-639c-4903-bf6b-76b8893d3957"
  },
  {
    "foreignId": "c85cfd6b-b1e9-4a50-bd55-eb725f04f7d5"
  }
]
```

## Usage

### Docker Compose

1. Create your `docker-compose.yaml`:

```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:
```bash
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.