@hansogj/music-audit
v0.2.0
Published
Music library audit CLI — library audit, interactive repair, Discogs enrichment
Readme
music-audit
Private, unpublished CLI for auditing and interactively repairing a local FLAC/MP3 music library. Not part of the published npm packages.
What it checks
| Check | Severity | Description |
|-------|----------|-------------|
| Folder starts with 4-digit year | SEVERE | e.g. 1984 No Return |
| Correct disc separator (∕ U+2215) | SEVERE | e.g. (Disc 1∕2) |
| Auxiliary info in [] not {} | SEVERE | |
| Artist under correct [A-Z] letter dir | SEVERE | Articles stripped for sorting |
| All required tags present | HIGH | TITLE, ARTIST, ALBUM, DATE, TRACKNUMBER |
| Filename matches TITLE tag | MODERATE | |
| Duplicate track numbers | MODERATE | |
| Year is the original release year | HIGH | Albums tagged with a Discogs release ID: folder/DATE year must match the master's year, not a reissue's (e.g. a 1989 reissue of In Rock → 1970). Needs Discogs; results are cached in ~/.cache/music-audit/original-years.json |
Usage
# Audit only (no Discogs lookups)
pnpm --filter @music/audit run audit -- --root /mnt/music --no-discogs
# Audit with Discogs suggestions (top 5 releases, scored against local track names)
pnpm --filter @music/audit run audit -- --root /mnt/music --token YOUR_TOKEN
# Point at a single album folder
music-audit --root /mnt/music/Z/ZAO/1976\ Kawana --token YOUR_TOKEN
# Interactive repair — step through issues album by album
sudo music-audit --repair --root /mnt/music --token YOUR_TOKEN
# Re-tag everything (including albums that already pass) with Discogs enrichment
sudo music-audit --retag --root /mnt/music --token YOUR_TOKEN
# Serve HTML report in browser
music-audit --ui --root /mnt/music --token YOUR_TOKENDISCOGS_TOKEN can also be set as an environment variable or in ~/.config/music-utils/.env (shared with the music-utils CLIs; under sudo the invoking user's home is used) instead of --token.
Flags
| Flag | Description |
|------|-------------|
| --root=<path> | Root of music library (default: cwd) |
| --token=<token> | Discogs personal access token |
| --no-discogs | Skip all Discogs API calls |
| --repair | Interactive repair mode |
| --retag | Like --repair but visits clean albums too |
| --ui | Serve HTML report at http://localhost:7171 |
| --json | Raw JSON output (incompatible with --repair/--ui) |
| --log[=<path>] | Append JSON Lines audit log to .audit-log/MM.dd.HH.mm-audit.log |
Repair mode
--repair (or --retag, which implies repair) walks album-by-album through issues and offers automated fixes:
- Folder renames — year prefix, disc separator, bracket style, letter-dir moves
- Discogs tagging — fetches tracklist, writes TITLE, ARTIST, ALBUM, DATE, ORIGINALDATE (
TORYfor MP3), TRACKNUMBER, DISCNUMBER, GENRE, COMMENT (Discogs URL), DISCOGS_RELEASE_ID; offers to rename files and folders (including the year) to match. DATE/ORIGINALDATE and ALBUM always come from the Discogs master (original year and title), not from the specific pressing; the pressing's year goes ininfo.txtasReissue: - Original year — sets DATE/ORIGINALDATE to the master year and renames the folder's year prefix
- Folder/artist rename — detects when Discogs artist or album title differs from local folder names
- Name/tag sync — rename file to match tag, or update tag to match filename
Release IDs are accepted as plain numbers (4565937), r4565937, [r4565937], or full Discogs URLs. Master IDs (m1439, [m1439], master URLs) are accepted too and resolve to the master's main release.
Each session writes two logs to .audit-log/:
MM.dd.HH.mm-audit.log— JSON Lines audit log (albums scanned, issues found, summary)MM.dd.HH.mm-repair.log— JSON Lines repair log (every fix attempt, crash-safe)
After Discogs tagging, an info.txt is written to the album folder with artist, tracklist, personnel, and durations.
Install the binary system-wide
sudo bash scripts/install-bins.sh