homelab-optimized/docs/services/individual/lidarr.md

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

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

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

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:

# 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

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 for the full list of known issues and fixes.