mbid-poller/README.md

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.

---

💡 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:

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.

2. Configure Docker Compose

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

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: Verify the LIDARR_BASE environment variable in the mbid-poller service points to your Lidarr instance.

   # Example for the default setup:
   - LIDARR_BASE=http://lidarr:8686 
   

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)

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:

   # ... mbid-poller environment section
   environment:
     # ...
     - LIDARR_BASE=http://lidarr:8686
     # - 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.

1. Build the Container: This compiles the Perl dependencies using the Dockerfile.

   docker compose build mbid-poller
   

2. 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, pinging the external MusicBrainz API until a successful response is received. It then outputs a Lidarr search URL for you to manually or automatically trigger the import in Lidarr.