A web UI for automatically organising your Audiobookshelf library. Reads your metadata directly from ABS, renames audio files consistently, and reorganises your folders into a clean hierarchy — all with a live preview before anything is touched.

• Scans your ABS library and shows statistics — books, authors, series, total play-time and size
• Proposes changes as diff cards showing exactly what folder and file names will change
• Dry Run mode simulates every move with zero changes made to disk
• Selective apply — tick the books you want moved instead of doing them all at once
• Rollback — one click to undo the last apply run, even after a page reload
• Collision detection — warns you before applying if two books would resolve to the same path
• Cleans empty directories left over after moves
• Persistent settings — naming templates survive container restarts

curl -O https://raw.githubusercontent.com/Donald-Win/abs-tidy-library/main/compose.yaml

volumes:
  - /your/audiobooks:/library   # same host path as your ABS compose (see note below)
  - /any/config/folder:/config  # any persistent folder for settings

environment:
  ABS_SERVER_URL: "http://192.168.1.100:13378"   # your server's LAN IP
  ABS_TOKEN:      "your-api-key-here"             # from ABS → Settings → API Keys

docker compose up -d

Open http://your-server:5050 — if your env vars are set it will connect automatically. Hit Scan Library.

Volume path must match your ABS setup The left side of the audiobooks volume mount must point to the same host directory that ABS is already serving. The right side (container path) can be anything, but must match LIBRARY_PATH.

# Your ABS compose might have:
- /media/Audiobooks:/audiobooks

# So this tool needs the same left side:
- /media/Audiobooks:/library

Use your LAN IP, not localhost Even if ABS is running on the same machine, containers can't reach each other via localhost or 127.0.0.1. Use the actual LAN IP of your server (e.g. 192.168.1.100).

The API key needs to be from an admin account The tool reads library metadata and triggers rescans. A non-admin token won't have access to do this.

LIBRARY_PATH must match your volume mount If you mount as :/library, set LIBRARY_PATH: "/library". They must agree.

The config mount must be a folder, not a file Docker will create it automatically if it doesn't exist yet, as long as the path doesn't conflict with an existing file.

Templates are configured in the Settings drawer and save automatically. Available tokens:

Default output looks like:

Brandon Sanderson/
├── The Way of Kings/
│   └── Brandon Sanderson - The Way of Kings.m4b
└── Mistborn/
    ├── 01 The Final Empire/
    │   └── Brandon Sanderson - Mistborn 01 - The Final Empire.m4b
    └── 02 The Well of Ascension/
        ├── Brandon Sanderson - Mistborn 02 - The Well of Ascension (Part 01 of 08).m4b
        └── Brandon Sanderson - Mistborn 02 - The Well of Ascension (Part 02 of 08).m4b

Nothing is moved until you explicitly click Apply.

1. Scan — reads metadata from ABS, builds the change plan
2. Review — inspect every proposed change in the diff cards
3. Dry Run — simulates all moves and logs them, nothing touches disk
4. Apply (or Apply Selected for a subset)
5. Rollback if anything looks wrong — reverts all files from the last apply

If you hit permission errors, add a user line matching your host user:

services:
  abs-tidy-library:
    user: "1000:1000"   # run `id` on your host to find your UID:GID

docker compose pull && docker compose up -d

MIT — see LICENSE.