LibraForge Your Audiobookshelf companion tool to forge your library into shape.
Global preferences

Settings

Configure appearance, metadata policies, library paths, reports, accounts, and connected services.

About LibraForge

LibraForge is a self-hosted companion tool for your Audiobookshelf library: it matches Audible metadata, converts and tags M4Bs, organizes folders into a consistent layout, and can download owned titles directly, all from one web UI with dry-run-first writes.

View the project on GitHub →

Appearance

Title noise patterns

Shared expressions prevent generic marketing text from becoming a book title or folder. Changes apply to both maintained scripts.

Publishers

Canonical publishers/imprints are stripped from search queries and from leaked author/narrator tags. Recognized special editions (GraphicAudio, Soundbooth Theater) flag a suggestion to use their dedicated abs-agg endpoint. Publishers seen during runs are learned here for review.

Library

Folders to ignore (prefix or exact name, e.g. . hides hidden dirs, @eaDir hides Synology system dirs)

Persistent skip patterns (one per line, merged into the run when "Include persistent patterns" is checked on the Forge page)

Report retention

LibraForge saves a .report.json and .log.txt file for every run. Enable either or both limits below; they are applied automatically after each completed run and when you click Save.

days
reports

Audible accounts

LibraForge uses Audible to look up book metadata and (optionally) download your purchases. Connect one or more accounts and switch between them whenever you like.

Tip: a dedicated empty Audible account is ideal for metadata lookups. For the Library Downloader, sign in with the account that owns the books you want to download.

Auth files are stored unencrypted under /auth inside the container (mounted from your configured host path). The active account lives at /auth/audible-metadata.json; others are kept in /auth/accounts/.

Connect an Audible account

Not using Audible? You can skip this step and use Audiobookshelf or abs-agg as metadata providers instead.
Signing in with Audible enables both direct API access for batch runs and ABS/abs-agg for manual review.

Audiobookshelf connection

LibraForge can use your Audiobookshelf instance as a metadata provider — no Audible account required. It supports Audible (via ABS's own connection), Google Books, iTunes, Open Library, and more.

Create a dedicated API key in your ABS instance: Settings → Users → API Keys. Name it libraforge, associate it with an admin user. API key documentation →

GraphicAudio / SoundBooth Theater

Optional. LibraForge can search a range of specialty audiobook services via abs-agg (a separate service): GraphicAudio, SoundBooth Theater, LibriVox, Storytel, Audioteka, BookBeat, Big Finish, ARD Audiothek, Die drei ???, Goodreads, and Hardcover. The last two need a GOODREADS_KEY / HARDCOVER_TOKEN configured on the abs-agg service itself (not here) to show up. Manual searches use this URL directly, and it's always available as an automatic fallback during batch runs regardless of the run's main provider.

Goodreads / Kindle

Optional. LibraForge can search Goodreads and Kindle via abs-tract (a separate service). Manual searches use this URL directly. Batch Goodreads fallback also requires enabling the fallback checkbox on the run screen; use only 5 search workers when enabling it because Goodreads rate-limits aggressively. Kindle is used only for high-quality cover art and its ebook ASIN is never written.

Developer

What gets traced?

When enabled, every run emits a structured log of the decisions made while matching your audiobooks. Three categories are traced:

ALTER -- text cleaning and transformation functions. Logs the input value and what it became after normalization, stripping, or sanitization (e.g. author names, titles, series strings, sequences, tag values).
CHOOSE -- selection and routing decisions. Logs what options were available and which one was picked (e.g. which search query to fire, which book number to trust, which provider to use, whether a path override was applied).
SCORE -- match scoring. Logs the score components and final result for each candidate considered during matching (title similarity, author match, duration delta, series/sequence conflicts, omnibus range).

Output goes to the log file path below. Leave the path blank to send trace output to the container's stderr instead (visible in docker compose logs libraforge). To review a saved log file, set a path under /reports/ -- the reports/ folder is bind-mounted to your host, so the file is accessible outside the container at reports/debug-trace.log (or whatever name you choose).

Danger zone

Clean up sidecars

Permanently delete the JSON files LibraForge writes next to your audio (orphaned sidecars left when a folder's layout changes). Audio files are never touched.