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.

💡 Acknowledgements

The core logic for the polling mechanism in this project is based on an existing script generously shared by GitHub user kchiem.

We are utilizing and adapting the Perl script found in the following public Gist:

Original Script: kchiem/lidarr-ping.dist
Link: https://gist.github.com/kchiem/eb998ac3c6f5a96cbec03b8e8c3b21a6

We appreciate kchiem's contribution to the community!

🚀 Setup and Usage

This project is designed to run as a service alongside a Lidarr instance using Docker Compose.

1. Prerequisites

Before starting, ensure you have:

Docker and Docker Compose installed.
A running Lidarr instance.
The project files (Dockerfile, poller.pl, docker-compose.yaml, etc.) in a single directory.

2. Configure Docker Compose

The mbid-poller container needs to communicate with your Lidarr instance.

Rename the Example: Rename the provided docker-compose.yaml.example to docker-compose.yaml.
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.
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:

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)

3. Choose the MBID Input Source

The poller.pl script supports three different ways to provide MBIDs, in order of priority:

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.

In your docker-compose.yaml, only one of these should be uncommented and set.

A. Using a JSON File (Recommended for simple setups)

Place your list of IDs in an ids.json file in the project directory (or adjust the volume mount).

In docker-compose.yaml, comment out MBID_API_URL and uncomment MBID_JSON_FILE:

# ... 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

4. Build and Run

With your files and docker-compose.yaml configured, you can build and run the poller.

Build the Container: This compiles the Perl dependencies using the Dockerfile.
```
docker compose build mbid-poller
```
Run the Poller: Since the restart policy is set to "no", this command will run the script once and exit.
```
docker compose up mbid-poller
```

The script will fetch the IDs, then loop through them. For each ID, it will:

Ping the external MusicBrainz API until a successful response is received.
Use the Lidarr API to automatically add the artist and set it to monitored.
Output a confirmation or error message before moving to the next artist.