101 lines
4.3 KiB
Markdown
101 lines
4.3 KiB
Markdown
# 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:** 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)
|
|
|
|
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`:
|
|
|
|
```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
|
|
```
|
|
|
|
### 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`.
|
|
|
|
```bash
|
|
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.
|
|
|
|
```bash
|
|
docker compose up mbid-poller
|
|
```
|
|
|
|
The script will fetch the IDs, then loop through them. For each ID, it will:
|
|
|
|
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. |