A collection of Python scripts and a web UI for managing a local FLAC music library using Discogs metadata.
Core philosophy: tags are set by the user via a dedicated tagger (e.g. Yate on macOS). Scripts enrich and organise — they never overwrite user-set tags arbitrarily, and everything else they write is derived from Discogs and refreshed whenever it disagrees. The DISCOGS_RELEASE_ID tag anchors every album to an exact Discogs release, eliminating the ambiguity that automated taggers introduce.
If you have multiple versions of the same album (original, remaster, SACD, Qobuz 24/96), automated music tools will happily collapse them into one. I've tried many; they've all mangled my collection at some point. Assigning a Discogs release ID to every album means I always know exactly which version I'm listening to, and can recover from any accidental tag overwrite as long as the release ID survives.
- Web UI — FastAPI + HTMX interface: browse your library, trigger scans, fetch lyrics, organise files, sync to remote
- Configurable link buttons — up to 5 toolbar buttons linking to any URL (favicons auto-cached)
- Tag enrichment — pulls release date, original release date, and format info from the Discogs API
- File organisation — moves FLACs into
Artist/Album/track_title.flac, creates MP3 mirrors via ffmpeg - Dynamic Range scoring — per-track and per-album DR values written as FLAC tags; DR column links to loudness-war.info
- Lyrics — parallel tag reading (8 workers) with lrclib requests sent one at a time under shared adaptive pacing, deferred retry of tracks lrclib could not answer, a warning for every track with no match, TXT-to-LRC upgrade (an existing LRC is never replaced, only corrected in place: headers, characters, capitalization), and a lyrics cache that is written only on change and pruned of stale entries
- AcoustID fingerprinting — generates and stores acoustic fingerprints
- Library sync — runs your own sync script; the template makes ROCK pull the library from the NAS with rsync over SSH (no detour through the Docker host)
- Syslog forwarding — optional structured log forwarding to a Synology log server
- Docker support — runs on Docker Desktop (Mac) or Synology NAS
brew install taglib --HEAD ffmpeg rsgain
# drcalc: download from https://github.com/koehntopp/drcalc/releases and put it on PATH
cp config_demo.py config/config.py # fill in your paths and API key
uv run webui.pyCreate docker-compose.yml (gitignored — may contain credentials):
services:
discogs:
build: .
ports:
- "8000:8000"
volumes:
- ./config:/config
- /path/to/flac:/flac
environment:
- CONFIG_DIR=/config
- PORT=8000docker compose up --build./build_synology.sh # builds discogs-synology-amd64.tar
# Upload via Container Manager → Image → Add → Import from fileThen use docker-compose-synology.yml as a reference for container settings.
./deploy-linux.sh # builds, ships, and reloads the image over SSHBuilds a linux/amd64 image, copies the tarball via SCP to /tmp on the Docker host
(192.168.1.97), loads it, deletes the tarball, and then has Dockge recreate the stack:
docker exec dockge-dockge-agent-1 sh -c 'cd /opt/stacks/discogs && docker compose up -d --remove-orphans'.
The stack's compose.yml and .env are managed in Dockge, and its stacks folder lives on the
NAS (only visible inside the Dockge container). Don't keep a copy of the compose file on the
host: an old copy in /opt/stacks/discogs used to silently overwrite the Dockge stack with
stale local mounts. To change volumes or environment variables, edit the stack in Dockge.
The container's persistent data is on the NAS (NFS), not on the host:
| Container path | NAS path |
|---|---|
/config |
/volume1/docker/discogs/discogs/config (config.py, logs, lyrics/) |
/root/.ssh |
the SSH folder with the key used by the Sync script, e.g. /volume1/docker/discogs/discogs/ssh (read-only) |
/flac |
SMB share //192.168.1.98/flac |
The full host setup is documented in AGENTS.md in the docker discogs folder.
Copy config_demo.py to config/config.py and set:
| Key | Description |
|---|---|
config_dir |
Base directory for config, logs, and data files (/config in Docker; must match CONFIG_DIR env var) |
discogs_api_key |
From https://www.discogs.com/settings/developers |
tagger_scheme |
URL scheme for deep-linking into your tagger app (e.g. yate://load) |
flacroot |
Root of your organised FLAC library (container-internal path) |
mp3root |
MP3 mirror root |
nzbdir |
Staging directory for newly tagged FLACs |
flacroot_local |
Path as seen by the browser (for tagger deep links) |
sync_script |
Script run by the Sync button; a bare name is looked up in the config directory (see sync_demo.sh) |
tagwright_url |
Tagwright's address, e.g. http://192.168.1.97:8780; the web UI's album list comes from its /api/library/albums.csv (ADR 0011) |
albums_refresh_minutes |
How often the album list is fetched again, also in an open page (default 5; 0 = off) |
cover_max_size |
Resize embedded cover art above this dimension (px) |
musicbrainz_languages |
True (default): fixtags.py writes LYRICS_LANGUAGE per track from MusicBrainz (needs MUSICBRAINZ_ALBUMID); False switches the lookup off |
rsgain_loudness / rsgain_clip_mode / rsgain_max_peak / rsgain_true_peak / rsgain_skip |
ReplayGain tagging settings passed to rsgain |
syslog_host / syslog_port |
Optional Synology log server |
log_file |
Log filename (written to config_dir) |
log_level |
Log verbosity: INFO, SUCCESS, WARNING, or ERROR |
log_rotation / log_retention |
Log file rotation size and retention period |
All config values are also editable via the Settings modal in the web UI.
config.py is gitignored — it contains credentials.
- Primary Anchor: Assign
DISCOGS_RELEASE_IDfor every album using Yate or your preferred tagger (mandatory anchor for metadata enrichment). - Optional MusicBrainz Tags: MusicBrainz IDs (
MUSICBRAINZ_ALBUMID,MUSICBRAINZ_ARTISTID,MUSICBRAINZ_TRACKID,MUSICBRAINZ_RELEASETRACKID) populated by your tagger are preserved.fixtags.pyusesMUSICBRAINZ_ALBUMIDto write a per-trackLYRICS_LANGUAGEtag (the sung language from MusicBrainz, e.g.eng,ksh,gle), whichlrc_fix.pyuses to pick the transcription language;fixtags.py --languages-onlydoes just that across a library without any Discogs lookups. - Cover Art: Embedded cover art is automatically resized if larger than 1500px.
- Format Tag: Set
ALBUM_FORMATfor physical or digital source media (e.g."CD","SACD","Blu-ray","Vinyl"). Defaults to"CD". - Edition Tag: Set
ALBUM_EDITIONfor special pressings (e.g."Deluxe Edition","40th Anniversary Remaster"). - User Overrides:
ALBUM_TITLE_OVERRIDE: Custom title to override the Discogs master album title.ALBUM_ARTIST_OVERRIDE: Manual correction for a wrongALBUMARTIST, applied only byfixtags.py(writes the override straight intoALBUMARTIST, permanently replacing whatever was there — not derived from or checked against Discogs). Everywhere else — player displays, bliss paths, album lists — reads the realALBUMARTIST/ARTISTtags directly; none of them consult the override tag itself.
- Tag FLAC Files: Assign
DISCOGS_RELEASE_IDtag in Yate or your tagger (along with optional MusicBrainz tags and cover art). - Stage Files: Drop new album folders into
nzbdir(staging directory). - Run Pipeline (
nzbfix.py): Run./nzbfix.py(or click Refresh in the web UI) to execute post-processing:dot_clean: Strips macOS.DS_Store/._*AppleDouble junk.- Parallel tasks:
calculate_dr(DR scores),rsgain(ReplayGain tags),calculate_fp(AcoustID fingerprints). - Sequential tasks:
fixtags(Discogs metadata enrichment & player date tags),update_lyrics(LrcLib.net lyrics download).
- Organise & Mirror (
bliss.py): Run./bliss.pyto move FLACs intoArtist/Album/track.flacstructure inflacroot(multi-disc albums getDisc Nsubfolders, which Roon uses for box sets) (with non-destructive overwrite protection) and generate optional MP3 mirrors. - Browse & Manage (
webui.py): Use the FastAPI/HTMX web UI to browse, search, and manage the library.
| Script | Purpose |
|---|---|
webui.py |
Web interface (FastAPI + HTMX) |
nzbfix.py |
Pipeline orchestrator (dot_clean → calculate_dr / rsgain / calculate_fp → fixtags → update_lyrics) |
fixtags.py |
Discogs API tag enrichment & date tag mapping |
bliss.py |
File organisation + MP3 sync (with overwrite protection) |
album_list.py |
Album inventory scan → CSV + DR chart (the web UI no longer uses it: its album list comes from Tagwright, ADR 0011) |
disc_layout.py |
Shared helpers for the Disc N folder layout of multi-disc albums (no CLI) |
update_lyrics.py |
Parallel lyrics fetch from lrclib.net (8 workers, one lrclib request at a time, adaptive pacing, retries failed tracks, warns when nothing is found; marks tracks tagged LYRICS_LANGUAGE=zxx instrumental without asking lrclib) |
lrc_fix.py |
Local LRC realignment (demucs vocal isolation + whisperx + onset-snapping) |
lrc_audit.py |
Audit of suspect synced lyrics: lrclib input vs our tools (compares tag, lrclib and a lrc_fix transcript) and, with fix --apply, repair by tier from the cache (safe realignments, instrumentals marked, shifted timestamps, one-timestamp tags; old tags saved, revert restores) |
lrclib_submitter.py |
Submit FLAC file lyrics to LRCLIB (lrclib.net) with PoW challenge solver |
lrclib_client.py |
Shared lrclib.net client identification (User-Agent + public Lrclib-App-Id); no CLI |
calculate_dr.py |
Dynamic Range calculation |
scan_progress.py |
Shared progress display for directory scanners (rich bar in a terminal, periodic log lines in the web app); no CLI |
check_multidisc.py |
Read-only CSV (with Yate links) of albums that look multi disc: disc count > 1, several SET SUBTITLE values, or mixed sample rate / bit depth |
calculate_fp.py |
AcoustID fingerprint generation |
migrate_tags.py |
Tag schema migration to discrete ALBUM_* tags |
build_synology.sh |
Build Docker image tar for Synology upload |
deploy-linux.sh |
Build, ship, and reload the Docker image on a Linux server via SSH (Dockge-managed) |
All Python scripts feature executable shebang lines (#!/usr/bin/env -S uv run) and declare dependencies via PEP 723 headers — run them directly from your shell:
./fixtags.py /path/to/album
./nzbfix.py /path/to/staging
./bliss.py
# Realign LRC timestamps locally (demucs + whisperx):
uv run lrc_fix.py /path/to/album_or_song.flac --dry-run
uv run lrc_fix.py /path/to/album_or_song.flac
# Key options:
# --whisper-model medium Whisper model size (default: medium)
# --device cpu|cuda|mps Compute device (default: cpu)
# --jobs / -j N Parallel demucs jobs (default: min(4, cpu count))
# --all Also reprocess files already LRC-timestamped
# --no-isolate-vocals Skip demucs vocal separation
# --no-snap-onsets Skip onset-snapping
# --no-vocal-check Skip the VAD fallback check on zero-match alignment
# --min-match FRACTION Skip files where fewer lines matched (default 0.6), tag left unchanged
# --no-quality-gate Write the alignment even if too few lines matched
# --find-missing-lyrics Scan for/tag tracks with no LYRICS tag at all
# --dump-words Print the raw ASR word/timestamp transcript
# Submit a FLAC file's LYRICS tag to LRCLIB:
uv run lrclib_submitter.py /path/to/song.flac --dry-run
uv run lrclib_submitter.py /path/to/song.flac- Python ≥ 3.14 (managed automatically by uv)
- ffmpeg, rsgain, drcalc, openssh-client — included in the Docker image; install separately for local use (
drcalcmust be onPATH)
Structured logging via structlog:
- Pretty coloured output when running in a terminal
- JSON to stdout when running as a subprocess (captured and re-logged cleanly by the web UI)
- JSON log file at
config_dir/log_file - Optional syslog forwarding: set
syslog_hostandsyslog_portin config.py - Set
LOG_LEVELenv var to control verbosity (default:INFO)
- discogs_client — Discogs API
- mutagen — FLAC audio tag read/write
- stable-whisper — MLX-accelerated word-level Whisper STT alignment
- drcalc — Dynamic Range calculation (Rust port of drmeter)
- pyacoustid — AcoustID fingerprinting
- lrclib.net — synced lyrics API
- rsgain — ReplayGain tag calculation
- openai-whisper — local speech-to-text for LRC timestamp alignment
- FastAPI + HTMX — web UI
- structlog — structured logging