Music Grabber

General

Skip duplicates

When on, tracks already in your library, Navidrome, or Lidarr are skipped. Turn off if you want to re-download something. Duplicate checks still run for M3U path resolution either way. MusicBrainz Metadata

Looks up each download on MusicBrainz to correct artist/title tags, add release year, and verify track duration. Occasional false matches are possible for obscure tracks. Deezer Album Fallback

When MusicBrainz can't pin down an album (common for brand-new releases), asks Deezer instead so the track still gets an album and can be routed out of Singles/. Only fills the album when MusicBrainz left it blank. Fetch Lyrics (LRClib)

Downloads synced (.lrc) or plain lyrics from LRClib after each track is saved. Displayed by players that support LRC files (e.g. Navidrome, foobar2000). Reject Live Versions

When a downloaded track is confidently identified as a live recording (and you did not ask for a live version), bin it and try again. Songs that simply have 'live' in the title, like 'Live and Let Die', are never affected. Tag Playlist Names in Comment

Writes the watched-playlist name(s) a track belongs to into its Comment tag, so macOS Music can build smart playlists from them. A track on several playlists gets all their names. Off by default; use the one-shot backfill to tag your existing library. Search Sources Controls which sources appear in search results. Fallback retries a failed download on another source. Health checks temporarily hide sources that are down.

Check interval (min) Cooldown (min) Searches per source

Each provider gets this many simultaneous searches across interactive and automatic work. Default 1, maximum 5. Download concurrency remains an internal conservative limit. Audio Format

Convert to

Keep source stores the audio in the format supplied by the provider and avoids an unnecessary re-encode. Convert to re-encodes each download to your selected format. Quality note: FLAC and ALAC can preserve a lossless source, but converting lossy MP3, AAC, Opus, YouTube, or SoundCloud audio to them cannot restore lost quality. Normalise Loudness (lossy sources)

Evens out the wild volume differences between YouTube (and other lossy web source) downloads by normalising them to a streaming-standard -14 LUFS as they arrive. Pure gain adjustment, no compression or pumping. Lossless sources (Monochrome, Soulseek) are never touched. Write ReplayGain Tags

Measures each finished download and writes ReplayGain 2.0 track gain and peak tags (reference -18 LUFS). The audio itself is never re-encoded, so unlike Normalise Loudness above this is completely reversible and safe on lossless files; your player does the turning-down. Album gain and peak are added once all of an album's tracks have landed. Supported for FLAC, MP3, M4A, Ogg and Opus. Replace Existing ReplayGain Tags

Off (recommended): files that already carry ReplayGain tags are left exactly as they are, on the assumption whoever wrote them meant it. On: MusicGrabber's own measurement wins every time. Organise by Artist

On: Singles/Artist Name/Track.ext
Off: Singles/Artist Name - Track.ext (flat, all in one folder) Include Track Number in Filename

When metadata has a track number, saved files use 1 - Track.ext. Flat layouts keep the artist prefix: Artist Name - 1 - Track.ext. Auto-album routing for singles

When on, singles with a MusicBrainz album match land in Artist/Album/Track.ext (Singles or Albums folder, see below) with track number tags. Falls back to Singles/Artist/Track.ext for new or unrecognised tracks. Route to Albums folder

When on, album-routed singles land in Albums/Artist/Album/Track.ext instead of the Singles folder. Requires auto-album routing to be enabled. Group playlists as one compilation

When on, tracks downloaded into a playlist folder are tagged with the playlist name as the album, album artist Various Artists, and the compilation flag. Stops Plex/Navidrome creating a separate one-track album per song. Handy for Shazam-style mixed playlists. Singles-only mode

Hides album browsing for everyone (the Artists tab still follows artists and grabs singles). Handy when you're feeding Navidrome with singles only and don't want family members poking at the album browser. Reload required.

AcoustID API Key Used for audio fingerprinting to improve metadata accuracy. A shared fallback key is built in but may hit rate limits if many people are using it. Register your own free key at acoustid.org to avoid this.

Minimum Audio Bitrate (kbps) Downloads below this bitrate are rejected. 0 = no minimum. Separate from track upgrades below: this gates new downloads, not existing files.

Track Upgrades (scan for better copies)

When on, MusicGrabber periodically scans library files it downloaded (Singles and playlist tracks, never Albums) and flags any sitting below the quality you already download at, so you can hold out for a lossless or higher-bitrate copy. The scan only looks; it never searches, downloads, or touches a file on its own. Off by default.

Upgrade Scan Interval (hours) How often the library scan runs. Cheap and network-free, so daily (24) is plenty.

Singles Subfolder

Choose an existing folder, use the music root, or pick Custom path….

Playlists Subfolder

Separate folder for playlist downloads. Leave disabled to keep playlist tracks in Singles. When set, playlist tracks are saved as Artist - Title.ext inside a named subfolder.

Albums Subfolder

Folder for album downloads from the album browser (Artists tab). Files are organised as Albums/Artist/Album/Track.flac.

Auto-Import Copy Folder Copies every finished download into this folder, as seen from inside the container. Mount your macOS Music Automatically Add to Music.localized folder here and new tracks import themselves. The library copy stays put; leave empty to disable.

Downloaded File Permissions

Permissions applied to each downloaded file. 666 is fine for most setups. Use 777 if your NAS or media server refuses to write to files owned by root.

Navidrome

URL

Username

Password

For accurate M3U playlist entries, add ND_SUBSONIC_DEFAULTREPORTREALPATH: "true" to your Navidrome docker-compose environment. Test Connection will check whether this is enabled.

Jellyfin

URL

API Key

When configured, MusicGrabber triggers a Jellyfin library scan after each download so new tracks appear immediately. Only the music library is refreshed.

Lidarr

URL

API Key

When configured, MusicGrabber checks Lidarr for existing tracks before downloading. Tracks already in your Lidarr library are skipped automatically.

YouTube

Browser Cookies Export cookies from youtube.com while logged in using a browser extension like "Get cookies.txt LOCALLY". Re-export when you start getting 403 errors.

Spotify

Browser Cookies Export cookies from open.spotify.com while logged in using a browser extension like "Get cookies.txt LOCALLY". Enables access to private playlists and your personal library. The sp_dc cookie is required.

Apple Music

Music-User-Token Required for private library playlists. To get the token: open music.apple.com, log in, open DevTools (F12), go to the Network tab, load any playlist, and find a request to amp-api.music.apple.com. Copy the music-user-token request header value.

Notifications

Notify On

Singles Playlists Bulk imports Errors only

Choose which download types send notifications. "Errors only" limits all selected types to failure notifications.

Telegram Webhook

Full Telegram Bot API URL including your bot token and chat ID. Create a bot via @BotFather, then get your chat ID by messaging @userinfobot.

Webhook URL Receives a JSON POST on download completion with event, type, title, artist, status, etc.

Apprise URL Supports 50+ services: Gotify, ntfy, Discord, Pushover, Slack, and more. See Apprise docs for URL formats.

Email (SMTP)

SMTP Host

SMTP Port

Username

Password

From Address

To Address

Use STARTTLS

Normally on for port 587. Port 465 uses implicit TLS and is not supported by this toggle.

Blacklist

Reported tracks and blocked uploaders. Blacklisted videos are hidden from search results; blocked uploaders are penalised in ranking.

Loading...

Soulseek (slskd)

Downloads require a shared completed-downloads folder. Turn on Soulseek in Search Sources above, then add slskd credentials here. MusicGrabber can only import Soulseek downloads if slskd's completed downloads directory is mounted into this container and entered below. Use the path as MusicGrabber sees it, for example /downloads.

URL

Username

Password

Downloads Path The path slskd writes completed downloads to, as seen from MusicGrabber's container. This is usually a Docker volume mount, not the host path and not necessarily slskd's /downloads path.

Move completed downloads

Off by default: MusicGrabber copies the finished file and leaves slskd's own copy alone. Turn this on to move it instead, which saves keeping two copies but also stops you sharing that file back to Soulseek. Same filesystem is an instant rename; across filesystems the copy is checked by size and SHA-256 before the original is deleted, and if the check fails the original stays put.

Monochrome (Qobuz / Tidal)

Enable Monochrome in Search Sources above to get lossless FLAC from Qobuz via the Tidal catalogue. No account or API key required. The default public proxy is shared infrastructure, so be reasonable with it. You can point these at a self-hosted hifi-api + Qobuz proxy if you prefer.

hifi-api URL Tidal metadata proxy (hifi-api). Used for search and Tidal playlist import.

Qobuz Proxy URL Qobuz stream resolver. Fetches the actual FLAC CDN URL given an ISRC.

Use qbdlx direct-Qobuz fallback Hidden Monochrome fallback used when all configured Qobuz proxies fail.

Use browser-authenticated playback fallback Last resort after the Qobuz proxy and qbdlx. Keeps one SeleniumBase Chrome session alive to complete Monochrome's Turnstile flow and resolve authorised resources; media still downloads normally outside Chrome.

User Management

Spotify (Advanced)

Browser Timeout (seconds) Base timeout for large Spotify playlist extraction. Can also be set via SPOTIFY_BROWSER_TIMEOUT_SECONDS.

No-progress Stall Window (seconds) Stop scrolling when no new rows appear for this long. Can also be set via SPOTIFY_BROWSER_STALL_SECONDS.

Security

API Key (Server)

When set, all API requests require this key. Rate limit: 200 requests/minute per IP.

Session / Auth

In API key mode, MusicGrabber stores your key in this browser for future visits. "Clear Stored Key" removes it from this browser only; you'll be prompted to re-enter it next time.

Maintenance

Database housekeeping only. These tools never delete or move library audio. Preview the counts, then choose exactly what to clean.

Load Settings to preview maintenance.

Queue history to remove: Completed Completed with issues Failed Cancelled

Music Grabber

MusicGrabber

Change Password

Music Grabber

Followed Artists

Albums

Watched Playlists / Watched Upgrades ↓ / Audio Audit ↓

Watched Upgrades

Audio Provenance Audit

Download Queue / Downloadable to Device ↓

Downloadable to Device

Trash Bin

Statistics

Watch Mismatches

General

Navidrome

Jellyfin

Lidarr

YouTube

Spotify

Apple Music

Notifications

Blacklist

Soulseek (slskd)

Monochrome (Qobuz / Tidal)

User Management

Spotify (Advanced)

Security

Change My Password

Maintenance

Music Grabber

MusicGrabber

Change Password

Followed Artists

Albums

Watched Playlists / Watched Upgrades ↓ / Audio Audit ↓

Watched Upgrades

Audio Provenance Audit

Download Queue / Downloadable to Device ↓

Downloadable to Device

Trash Bin

Statistics

Watch Mismatches

General

Navidrome

Jellyfin

Lidarr

YouTube

Spotify

Apple Music

Notifications

Blacklist

Soulseek (slskd)

Monochrome (Qobuz / Tidal)

User Management

Spotify (Advanced)

Security

Change My Password

Maintenance

Edit Track Tags

Report Bad Track

Find Versions

Choose Destination Folder