Lanternwright

For people who self-hostworking name

Shelfmend

A command-line tool. Open source, not published yet.

Fix your audiobook library without breaking it.

Every change starts as a plan you can read, and nothing is deleted outright.

shelfmend doctor ~/shelfmend-demo

Shelfmend doctor: ~/shelfmend-demo (read-only)
  41 books, 60 audio files, 271.0 KiB, 301.5 h of audio known (tags: mutagen)

  ERROR    Damaged or truncated audio files                    2
             Rosa Quill/Tide Tables/03 - Chapter 3.mp3
             Theo Brandt/The Brass Sparrow/The Brass Sparrow.m4b
  WARNING  Audio files that may be cut short                   1
  WARNING  Encrypted Audible files (.aax)                      1
  WARNING  Duplicate books                                     1
  WARNING  One ASIN on several volumes                         1
  WARNING  Narrator or publisher stored as the author          2
  WARNING  Folder layout problems                             10
  WARNING  Broken cover images                                 1
  info     Tidy-ups (7 checks; --all lists them)              78
             for example, titles and folder names with junk in them: Lena Ashby/Bell Tower 128k

doctor is read-only: nothing was changed.
Real output from the practice library that shelfmend demo makes. Every book, author and narrator in it is invented, and only the folder path was shortened.

Shelfmend is a command-line tool that checks an audiobook library and repairs it carefully: damaged and truncated audio, duplicates, a narrator or publisher filed as the author, a series split under two names, and folder and cover problems. Every change starts as a readable plan, stays a dry run until you say go, and goes into an undo journal. It works with plain folders and with Audiobookshelf through its API.

Why I made this

Shelfmend started after a duplicate cleanup ate a book in my own audiobook library. That's why it's so careful now.

What it does

  • One health report for the whole library. Damaged and truncated audio (checked without trusting file extensions), duplicates, misfiled authors, split series, and layout and cover problems. The result is a terminal summary and a single-file HTML page, and making it changes nothing.
  • Duplicate cleanup that doesn't eat books. Different volumes never get grouped, runtime alone never counts, a damaged copy is never the one kept, and anything doubtful gets held back.
  • Author and series repair, with the evidence. Series names are merged only when they differ mechanically, never across a real sub-series.
  • Plays nice with Audiobookshelf. It fixes metadata through the API, with no folder moves and no lost listening progress. It never forces a library scan or deletes a file.
  • Nothing happens until you say go. Every change starts as a plan to read and prune, stays a dry run until the go-ahead, and goes into an undo journal. Deletions sit in a reversible quarantine first.

What it doesn't do

  • It doesn't download books or search indexers.
  • It doesn't remove DRM; encrypted .aax files are left alone.
  • It never edits audio tags; Plex and Jellyfin need a tag editor.
  • It never deletes a damaged file on its own.
  • It doesn't share or upload books, covers or descriptions.

Screenshots

Shelfmend's library health report open in a browser: 41 books, 60 audio files, 2 errors and 17 warnings, then a summary table listing each check, its result, how many it found and what to do about it.
The one-page health report from shelfmend doctor, run on its sample practice library. Every book in it is invented.
The same Shelfmend health report in its dark theme: a plain-words verdict that 2 audio files are damaged or cut short, tiles for 41 books, 2 errors and 17 warnings, and the summary table below.
The same report in its dark theme. Same invented library.

Who it's for

People who keep their own audiobook library (DRM-free purchases, their own backups and CD rips), often served with Audiobookshelf. It isn't a downloader and it doesn't remove DRM.

What it keeps, and where

Shelfmend runs locally, collects nothing, and only ever talks to your own Audiobookshelf server, and only when asked.

Goes online only for: Audiobookshelf API mode (only when you ask for it); Series name lookups (off until you turn it on).

The full Shelfmend privacy section

Runs on, and what it'll cost

Runs on
Windows, macOS and Linux (Python 3.11 or newer, command line). A Docker image is planned.
Cost
Free and open source under the MIT license, with optional donations. A paid local review app is planned only if the free tool gets real traction.
License
MIT, so the code is open source.

Audiobookshelf is an independent open source project. Shelfmend is not affiliated with or endorsed by it.