Settings - Lidarr YouTube Downloader

Automation

Scheduler Status

Enable automatic periodic checks for missing albums

Auto Download

Automatically download missing albums when found

Check Interval (Minutes)

How often to check for missing albums

Max Albums per Cycle

Maximum number of albums to queue per scheduler run. Set to 0 for unlimited.

Retry After (Hours)

Skip auto-downloading an album that was already attempted (success or failure) within this many hours, so the scheduler works through the rest of the library before retrying the same one. Set to 0 to disable.

Back Off Failing Tracks

A track that keeps failing (e.g. a song that simply isn't on YouTube) waits twice as long after each failure instead of being retried every cycle forever — capped at 30 days, so it is still found if it appears later. Turn off to retry every run.

Max Retries per Track

Give up on a track for good after this many consecutive failures. Set to 0 to never give up (just keep backing off). Adding an album to the queue by hand always retries everything immediately.

Download Options

XML Metadata Files

Generate XML metadata files alongside audio files (useful for Lidarr integration)

Save cover.jpg in Album Folder

Write the album artwork as cover.jpg next to the audio files. Disable to save disk space if you don't want artwork stored on disk. (Cover is still embedded in ID3 tags and used for notifications regardless.)

Trigger Lidarr Rename After Import

After files are imported into Lidarr, send a RenameFiles command so Lidarr applies its configured naming convention (also fires Lidarr's "on rename" connections).

Save YouTube Playlist Imports to Library

For "Playlist creation from YouTube": write the downloaded tracks into your Lidarr music library path (instead of only the download folder) and ask Lidarr to scan them, so they show up in Jellyfin/Lidarr (Lidarr imports whatever it can match). Requires LIDARR_PATH configured. Off keeps the files in the download folder only.

AcoustID Fingerprinting

Fingerprint downloaded tracks and look up MusicBrainz recording IDs via AcoustID

AcoustID API Key

Get a free key at acoustid.org

Concurrent Track Downloads

Number of tracks downloaded simultaneously per album. Higher values speed up downloads but increase the risk of being rate-limited or banned by YouTube. Recommended: 2.

YouTube Search Artist

Which artist to use when building the YouTube search query for a track. "Lidarr Album Artist" is instant but shows "Various Artists" for compilations, so those tracks often can't be found. The other options resolve the real per-track artist via MusicBrainz and/or iTunes before falling back to the album artist — more accurate, but adds up to ~1s per track (MusicBrainz rate limit) to the search step.

Checking audio conversion…

Audio Format

M4A and Opus prefer the native YouTube stream and stream-copy without re-encoding (no quality loss). MP3 always transcodes.

Audio Quality (kbps)

Target bitrate when transcoding (MP3 always, M4A/Opus only if the native codec isn't available). Stream-copied audio keeps the YouTube source bitrate regardless of this setting.

yt-dlp Format Override

Advanced. Force a specific yt-dlp format selector (e.g. 141 for 256 kbps AAC with a YouTube Premium account). The built-in selectors are used as a fallback when the requested format isn't available. Leave empty for automatic best-audio selection. Use "List formats" below to see a video's available format IDs.

Loudness Normalization

Apply EBU R128 loudness normalization (−14 LUFS) so volume is consistent across tracks. Forces a re-encode (M4A/Opus won't stream-copy when enabled).

ReplayGain Tags

Measure each track's loudness and write ReplayGain tags (REPLAYGAIN_TRACK_GAIN/PEAK) so players like Jellyfin/Navidrome can normalize volume — without re-encoding the audio (non-destructive, unlike Loudness Normalization). Adds a short ffmpeg analysis pass per track.

Save Synced Lyrics (.lrc)

Fetch time-synced lyrics from LRCLIB and write a .lrc file next to each track, so Jellyfin/Navidrome/Plex can show synced lyrics. Falls back to plain lyrics when synced aren't available.

YouTube PO Token

Optional. Helps with "Sign in to confirm you're not a bot" / format-unavailable errors. Paste one or more po_token values (comma-separated) from yt-dlp. Leave empty unless you hit those errors.

PO Token Provider URL

Optional, recommended over a manual token: URL of a bgutil PO token provider run as a sidecar (e.g. http://bgutil-provider:4416). yt-dlp fetches tokens automatically when needed. See the bundled docker-compose.

YouTube Search Filters

Custom Forbidden Words

Add your own words to filter out (e.g. "slowed and reverb"). Matched against the YouTube title using the same rules as the built-in list.

Duration Tolerance (seconds)

Allowed difference between track duration and YouTube video length. Recommended: 5-15 seconds.

Minimum Match Score

Minimum YouTube match score (0.0–1.0) required to accept a track when AcoustID verification is unavailable. Recommended: 0.8.

YouTube Cookies

Cookies File Path

Absolute path inside the container to a Netscape-format cookies.txt. Required when YouTube asks for sign-in or returns 403. Upload below to write to /config/cookies.txt automatically.

Upload cookies.txt

Pick a Netscape-format cookies.txt exported from your browser (e.g. "Get cookies.txt LOCALLY" extension). It will be saved to /config/cookies.txt and the path above will be set automatically.

yt-dlp Engine

yt-dlp

...

Telegram Notifications

Bot Token

Your Telegram Bot API token from @BotFather

Chat ID

The chat ID where notifications will be sent

Notification Filters

Choose which log types to receive via Telegram

🎵 Download Started ✅ Download Success / Partial ✅ Import Success / Partial ❌ Album Error

Send Test Message

Verify your bot token and chat ID by sending a test message right now

Discord Notifications

Webhook URL

Your Discord channel webhook URL (Server Settings > Integrations > Webhooks)

Notification Filters

Choose which events to receive via Discord

🎵 Download Started ✅ Download Success / Partial ✅ Import Success / Partial ❌ Album Error

Send Test Message

Verify your webhook URL by posting a test message right now

Ntfy Notifications

Topic

Your Ntfy topic name (e.g. lidarr-music)

Server URL

Ntfy server URL (default: https://ntfy.sh, or your self-hosted instance)

Access Token (Optional)

Bearer token if your Ntfy topic requires authentication

Priority

Default notification priority

Notification Filters

Choose which events to receive via Ntfy

🎵 Download Started ✅ Download Success / Partial ✅ Import Success / Partial ❌ Album Error

Send Test Message

Verify your Ntfy setup by sending a test notification right now

Import / Export Configuration

Export Settings

Download your current configuration as a JSON file

Import Settings

Upload a previously exported config.json to restore settings

Backup Database

Download a full backup of the app database — download history, logs, queue, banned URLs and playlist imports. Keep it safe to restore after a reset or on a new install. (Your config.json is exported separately, above.)

Restore Database

Upload a previously downloaded backup to replace the current database. The app restarts to apply it. Not available while a download is running.

Lidarr Download Client

Expose this app to Lidarr as a native Newznab indexer + SABnzbd download client. Lidarr then searches, grabs and imports automatically — no need to push from here.

In Lidarr add a Newznab indexer and a SABnzbd download client, both pointing at this app's host/port, using the API key below. Enable Completed Download Handling.

Enable Download Client

Turn on the Newznab + SABnzbd endpoints so Lidarr can use this app.

API Key

Use this same key for both the Newznab indexer and the SABnzbd client in Lidarr.

Environment Variables

⚠️ Note: Changes to these paths require an application restart to take full effect.

Automation

Download Options

YouTube Search Filters

YouTube Cookies

yt-dlp Engine

Telegram Notifications

Discord Notifications

Ntfy Notifications

Import / Export Configuration

Lidarr Download Client

Environment Variables

Save Changes