Your music library,
repaired in place.

A large library goes wrong slowly. One artist ends up spelled three different ways across a handful of albums. A compilation splits into a dozen separate entries because nothing ever wrote an album artist. A vinyl rip and an SACD rip of the same record show up as identical rows with nothing to tell them apart. None of it is visible until you try to browse the collection, and none of it is safe to fix by hand at scale, because bulk tag edits are exactly the kind of change you cannot easily take back.

Luthier starts by recording every tag in the library. That snapshot is small, usually a few tens of megabytes even for a large collection, and every fix applied afterward can be undone from it. Finding problems and reviewing proposed repairs both happen before anything is written, so cleaning up a library stops being a one-way risk.

A console built for deciding what to run.

The command line does the writing; the console handles the part that is genuinely hard to get right from a terminal. It shows what is wrong with the library, what each fix would actually change, and how much to trust it, before offering to write anything.

Standing on a fix explains it in five fixed sections: what, why, risk, options and impact. Impact is the new part. It says what the pass touches, what it writes and what it leaves alone, then lists every album, folder, field or rule it would change, each with the value it holds now above the value it would get.

Every item has a tick, and so does every row behind it. Untick one album from a fix that is right about the other forty, and the count, the preview and the write all follow. What you untick is remembered by folder, field or rule rather than by position, so it survives re-analysing. Rows opens every finding a pass produced, including what it looked at and declined, in a table you can filter, tick and open in the browser when it needs more room.

A strip under every tab says which snapshot the session is planning from and warns when it has gone stale: when it is over a day old, when a folder changed after it was taken, or when the library holds albums it has never seen. When a snapshot describes another drive, or there is none, preview and apply are disabled with the reason on screen rather than merely warned about.

The Settings tab keeps the library, snapshot and incoming folders, so a plain luthier opens straight into your library. It also holds the genre rules: add a genre at the top of the match order, move it, edit its pattern, or reset to the built-in list. The command line reads the same rules with no flag needed.

What it fixes today.

• Stray bytes. Invisible characters left behind by old taggers, the kind that quietly split one artist into two.
• Non-standard tag keys. ALBUM ARTIST, ALBUM_ARTIST and BAND folded into the one key servers actually read.
• Artist spellings. Case, punctuation and stray diacritics reconciled across every field that names a person, including composers and sort names most taggers skip. Names spelled on purpose, like dEUS, can be pinned from the console so no vote overrules them.
• Missing artists. Recovered from the rest of the library's own tags rather than guessed from the folder name.
• Missing album artists. The single most common reason a library browses badly, fixed where the evidence is unambiguous.
• Genre sprawl. Dozens of near-duplicate genre strings folded onto one consistent list, decided per album rather than per track.
• Editions. A CD rip, a vinyl rip and an SACD of the same record labelled so they read as different pressings instead of duplicates.
• Folder names. Album folders renamed to Artist - (Year) Album from their own tags, keeping whatever else the old name said, like (CD, UK) or [WEB]. Every rename is logged, restores still find the files, and Undo puts the last run back.

Each of these is a dry run by default. Luthier also finds duplicate and near-duplicate audio, tells you whether new arrivals are already in the library, checks that files actually decode, and fetches missing cover art for review on a contact sheet, all without touching anything until you tell it to.

Quick start.

In the console

1. Open it. Unpack the download and run luthier. The first time, it opens on Settings and asks where the library and snapshots live. After that it opens straight into the library.
2. Take a baseline. On the Snapshots tab, choose New snapshot or press s. This is the safety net: every tag in the library, recorded before anything is written.

   

3. Analyse. Press a. The counts on the Fixes tab fill in pass by pass, and the Library tab sums up what was found.

   

4. Choose what to fix. Tick fixes on the Fixes tab. Read the Impact section for each one, untick anything it gets wrong, and press d to see every row behind the count.

   

5. Preview, then apply. Press p to list every write the selection would make, in the order it runs. Nothing you unticked appears. When it reads right, press r or Apply selected.

   Spellings of the same ARTIST        6 changes    review first
      artist            SCANN-TEC      →  Scann-Tec    10 files
   Missing ALBUMARTIST                 7 changes    safe
      ALBUMARTIST       (none)         →  Norah Jones  _incoming/Norah Jones - 2004 …

6. Changed your mind? Restore from this on the Snapshots tab writes out the exact restore command to paste into a terminal. Folder renames have their own Undo on the Folder names row.

From the command line

# 1. the safety net, before anything else
luthier snapshot /music -o ~/tags-2026-09-23.jsonl.gz

# 2. what state is this library actually in?
luthier report ~/tags-2026-09-23.jsonl.gz

# 3. run a pass as a dry run, read it, then apply it
luthier albumartist ~/tags-2026-09-23.jsonl.gz --root /music
luthier albumartist ~/tags-2026-09-23.jsonl.gz --root /music --apply

# 4. changed your mind
luthier restore /music ~/tags-2026-09-23.jsonl.gz --only ALBUMARTIST --apply

Nothing writes without --apply. Every pass that writes takes --only PREFIX to limit its writes to part of the library while still reading all of it, and luthier <command> --help lists each command's options.