# Lidarr

Music collection manager with Deezer integration via arr-scripts.

## Service Info

| Property | Value |
|----------|-------|
| **Host** | Atlantis (192.168.0.200) |
| **URL** | http://192.168.0.200:8686 |
| **Compose file** | `hosts/synology/atlantis/arr-suite/docker-compose.yml` |
| **Config volume** | `/volume2/metadata/docker2/lidarr` |
| **Portainer stack** | arr-stack (stack ID 560, env 2) |
| **API key** | `2084f02ddc5b42d5afe7989a2cf248ba` |

## arr-scripts / Deezer Integration

Lidarr uses [arr-scripts by RandomNinjaAtk](https://github.com/RandomNinjaAtk/arr-scripts) to download music from Deezer via deemix. This is the primary download source since usenet indexers have zero coverage for non-English music (Italian, Japanese, etc.).

### How it works

1. arr-scripts runs as s6 services inside the Lidarr container
2. The `Audio` service polls Lidarr's missing albums queue every cycle
3. For each missing album, it searches Deezer using fuzzy title matching (Damerau-Levenshtein distance)
4. On match, it calls `deemix` to download at 320kbps MP3 (Deezer Premium)
5. Files are placed in `/config/extended/import/` and Lidarr is notified via API to import them

### File locations on Atlantis

| Path | Purpose |
|------|---------|
| `/volume2/metadata/docker2/lidarr/extended.conf` | arr-scripts config — **not in git** (contains ARL token) |
| `/volume2/metadata/docker2/lidarr-scripts/custom-cont-init.d/scripts_init.bash` | Init script that runs on every container start |
| `/volume2/metadata/docker2/lidarr-scripts/custom-services.d/` | s6 service definitions (populated automatically on first start) |

### extended.conf key settings

```bash
enableAutoConfig="true"      # Required sentinel — all services check this first
enableAudio="true"           # Set to "false" to pause downloads
dlClientSource="deezer"
audioFormat="native"
audioBitrate="high"          # "high" = FLAC (maxBitrate=3 in deemix_config.json)
arlToken="..."               # Deezer session cookie — expires ~3 months, not in git
enableBeetsTagging="true"
beetsMatchPercentage="70"    # Lowered from 90 — stricter caused too many import failures
matchDistance="6"            # Raised from 3 — more tolerant fuzzy album matching
enableReplaygainTags="true"
```

> **ARL token**: Get from deezer.com → DevTools → Application → Cookies → `arl`. Requires Deezer Premium.

### Pausing/resuming downloads

**Quick (via Portainer console exec into `lidarr`):**
```sh
s6-svc -d /run/service/custom-svc-Audio   # pause
s6-svc -u /run/service/custom-svc-Audio   # resume
```

**Persistent (survives restarts):**
Edit `/volume2/metadata/docker2/lidarr/extended.conf`, set `enableAudio="false"`, restart container.

### scripts_init.bash — why it exists

`setup.bash` (downloaded from GitHub) silently fails to install several Python packages on Alpine due to setuptools build errors. `scripts_init.bash` re-installs them explicitly after `setup.bash` runs:

- `yq` — Python yq whose `xq` binary replaces Alpine's `xq` (v1.x outputs XML passthrough instead of JSON)
- `pyxdameraulevenshtein` — Damerau-Levenshtein distance for fuzzy album title matching
- `deemix` — actual Deezer downloader
- `colorama`, `pylast`, `mutagen`, `langdetect`, `apprise`, `r128gain` — supporting packages

Without these, downloads fail silently or the scripts get stuck in a "not ready" loop forever.

## Compose volumes

```yaml
volumes:
  - /volume2/metadata/docker2/lidarr:/config
  - /volume1/data:/data
  - /volume3/usenet:/sab
  - /volume2/metadata/docker2/lidarr-scripts/custom-services.d:/custom-services.d
  - /volume2/metadata/docker2/lidarr-scripts/custom-cont-init.d:/custom-cont-init.d
```

## Indexers

Usenet indexers (NZBgeek, NzbPlanet, etc.) have near-zero coverage for non-English music. Deezer via arr-scripts is the primary source. Usenet indexers still handle English/mainstream releases when they appear.

## Download Clients

| Client | Type | Purpose |
|--------|------|---------|
| **Arr-Extended** | Usenet Blackhole | arr-scripts deemix integration — primary source |
| **SABnzbd** | Usenet | Mainstream/English releases from NZB indexers |

SABnzbd is at `192.168.0.200:8080`. Remote path mapping: `/data/complete/` → `/sab/complete/`.

## Quality Profile

All artists use the **"Any"** profile with:
- `upgradeAllowed: true` — will upgrade MP3 → FLAC if found
- `cutoff: 1005` (Lossless group) — stops upgrading once FLAC/ALAC/APE is obtained
- Deemix downloads FLAC by default (`maxBitrate=3`) so existing lossless files are **not overwritten**

## Import Behaviour & Known Issues

### Auto-import failures
Lidarr's internal match threshold is **80%**. Releases that score below this are marked `importFailed` and require manual import. Common causes:

| Cause | Example | Action |
|-------|---------|--------|
| Bootleg/unofficial release not in MusicBrainz | Drake-No More Thank Yous-Bootleg | Manual import |
| Compilation with wrong artist match | Doris Day And Peggy Lee 2CD | Manual import |
| Album has fewer tracks than existing release | 311 Grassroots (correct — skip) | Already have better |
| Not an upgrade for existing files | Four Tops MP3 (correct — skip) | Already have lossless |
| Archive not extracted | Lloyd Banks zip | Extract manually in SABnzbd |

### Fingerprinting
Set to `allFiles` (2026-03-18) — Lidarr acoustically fingerprints every track via AcoustID for better MusicBrainz matching. Previously only fingerprinted new files.

### Queue stuck with `downloadClientUnavailable`
Happens when SABnzbd restarts. Clear via:
```bash
# Via API
curl -s -X DELETE "http://192.168.0.200:8686/api/v1/queue/<id>?removeFromClient=true&blocklist=false" \
  -H "X-Api-Key: "REDACTED_API_KEY"
```
Or bulk clear all stuck items — see `docs/troubleshooting/common-issues.md`.

### Force rescan/reimport
```bash
curl -s -X POST "http://192.168.0.200:8686/api/v1/command" \
  -H "X-Api-Key: "REDACTED_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "DownloadedAlbumsScan"}'
```

## Troubleshooting

See [arr-scripts troubleshooting](../../troubleshooting/common-issues.md#arr-scripts-lidarr-deezer) for the full list of known issues and fixes.