maxqual

PyPI Python 3.10+ CI

Build a music library at the highest quality the source serves, with complete tags, cover art and per-release organization.

maxqual is a standalone CLI for people who curate permanent local libraries (e.g. for Jellyfin/Plex/navidrome). It resolves release metadata, matches tracks, downloads audio natively (no re-encode), tags it properly, and organizes it into per-release folders with playlists and artwork.

• Zero-transcode pipeline. Streams are kept in their native container. Audio is never re-encoded, so what you keep is exactly what the source served — no generational loss.
• Quality-tier preference. When a higher audio tier is available to the session you supply, it is preferred automatically; otherwise the best publicly available stream is used.
• Discography-aware. Point it at an artist and it fetches albums, EPs and singles as separate, properly numbered releases with an .m3u8 each.
• Open metadata first. Release/track metadata comes from Deezer's public API (no key, no quota dance) for artist and album URLs; Spotify playlists/albums are supported with client credentials (your own app key, or a shared fallback with retries).
• Cover art maintenance. maxqual covers re-embeds artwork when a strictly larger image can be found, and writes folder.jpg per release.

metadata source (Deezer / Spotify)
 │ release, tracklist, durations, artwork URL
 ▼
track matching (yt-dlp search, duration-scored)
 │
 ▼
audio download (yt-dlp; native formats only)
 │ m4a / opus, no conversion
 ▼
tagging + organization (mutagen)
 NN - Artists - Title.ext + Release.m3u8 + folder.jpg

Requires Python 3.10+, ffmpeg on PATH, and (recommended) a deno binary — YouTube's JS challenges need a JS runtime that yt-dlp can find.

pipx install maxqual # recommended (isolated env)
pip install maxqual # or plain pip

From source:

git clone https://github.com/mareekkk/maxqual
pipx install ./maxqual

maxqual download "Artist Name" -o ~/Music # full discography
maxqual download "https://open.spotify.com/playlist/..." -o ~/Music
maxqual covers ~/Music # upgrade cover art

# an artist's discography (Deezer metadata; albums + EPs + singles)
maxqual download "Jeff Kaale" -o ~/Music
# a specific album or playlist
maxqual download "https://www.deezer.com/album/123456" -o ~/Music
maxqual download "https://open.spotify.com/playlist/..." -o ~/Music
# use a logged-in browser session (recommended; tokens rotate, so export fresh)
maxqual download "https://open.spotify.com/playlist/..." \
 --cookies-from-browser firefox --refresh-cookies -o ~/Music
# upgrade embedded cover art across a library
maxqual covers ~/Music

Resumable by design: existing files are skipped, so re-running a command retries only what is missing.

Some streams require a proof-of-origin token. If you run the community bgutil-ytdlp-pot-provider server locally (loopback only), yt-dlp picks it up automatically and maxqual benefits with no extra configuration:

docker run -d --init --restart unless-stopped \
 -p 127.0.0.1:4416:4416 brainicism/bgutil-ytdlp-pot-provider

Session cookies are credentials. maxqual exports them to a mode-600 file when you pass --refresh-cookies, never prints them, and you should delete the file when you are done. Anonymous operation also works and simply resolves to the best public stream.

src/maxqual/
 audio.py # yt-dlp wrapper: search, native download, cookie export
 sources.py # Deezer + Spotify metadata
 tags.py # mutagen tagging, covers, m3u, folder.jpg
 covers.py # cover-art upgrade pass
 cli.py # command line interface

maxqual is a tool. It does not host, index or redistribute any content, and it ships without credentials of any kind.

• You are responsible for what you download and for complying with the terms of the platforms you interact with and the copyright of the material involved.
• Intended uses include: content you own or created, content published under permissive licenses (e.g. Creative Commons, public domain), and anything you are licensed to archive.
• The authors do not condone infringement and provide no support for it.

Extraction technology is a moving target; if a source changes its player response format, this tool inherits whatever yt-dlp handles.

MIT — see LICENSE.