Skip to content
koehntoppPublic

About

Manage a local FLAC library with Discogs metadata: tag enrichment, lyrics, dynamic range, MP3 sync, FastAPI/HTMX web UI.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

275 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Discogs Music Library Manager

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.

Why?

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.

Features

  • 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

Quick Start

Local (macOS)

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

Open http://localhost:8000

Docker (local)

Create 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=8000
docker compose up --build

Synology NAS

./build_synology.sh          # builds discogs-synology-amd64.tar
# Upload via Container Manager → Image → Add → Import from file

Then use docker-compose-synology.yml as a reference for container settings.

Linux server (managed via Dockge)

./deploy-linux.sh            # builds, ships, and reloads the image over SSH

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

Configuration

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.

Tagging Guidelines & Contract

  • Primary Anchor: Assign DISCOGS_RELEASE_ID for 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.py uses MUSICBRAINZ_ALBUMID to write a per-track LYRICS_LANGUAGE tag (the sung language from MusicBrainz, e.g. eng, ksh, gle), which lrc_fix.py uses to pick the transcription language; fixtags.py --languages-only does 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_FORMAT for physical or digital source media (e.g. "CD", "SACD", "Blu-ray", "Vinyl"). Defaults to "CD".
  • Edition Tag: Set ALBUM_EDITION for 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 wrong ALBUMARTIST, applied only by fixtags.py (writes the override straight into ALBUMARTIST, permanently replacing whatever was there — not derived from or checked against Discogs). Everywhere else — player displays, bliss paths, album lists — reads the real ALBUMARTIST/ARTIST tags directly; none of them consult the override tag itself.

Typical Workflow

  1. Tag FLAC Files: Assign DISCOGS_RELEASE_ID tag in Yate or your tagger (along with optional MusicBrainz tags and cover art).
  2. Stage Files: Drop new album folders into nzbdir (staging directory).
  3. 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).
  4. Organise & Mirror (bliss.py): Run ./bliss.py to move FLACs into Artist/Album/track.flac structure in flacroot (multi-disc albums get Disc N subfolders, which Roon uses for box sets) (with non-destructive overwrite protection) and generate optional MP3 mirrors.
  5. Browse & Manage (webui.py): Use the FastAPI/HTMX web UI to browse, search, and manage the library.

Scripts

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

Requirements

  • Python ≥ 3.14 (managed automatically by uv)
  • ffmpeg, rsgain, drcalc, openssh-client — included in the Docker image; install separately for local use (drcalc must be on PATH)

Logging

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_host and syslog_port in config.py
  • Set LOG_LEVEL env var to control verbosity (default: INFO)

Libraries and Tools

About

Manage a local FLAC library with Discogs metadata: tag enrichment, lyrics, dynamic range, MP3 sync, FastAPI/HTMX web UI.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages