What needs attention
Point LibraForge at a folder and it'll tell you what's missing, what's ready, and what's already in shape - across tagging, conversion, and organization.
Guide: what the badges and modes mean
Edit modes
- Full metadata writes everything the match provided: title, author, series, sequence, narrator, year, genre, ASIN.
- Series only writes only the series name, not the sequence number, and leaves title and other fields untouched. Used when the match confirms series and author confidently but title identity is uncertain, so a possibly-correct local title is never clobbered, and the sequence number is left alone since this mode exists precisely for cases where that number isn't trustworthy yet.
Write modes
- Smart: only writes if the current embedded tags differ from the match.
- Fill missing fields only: never touches a field that already has a value, only fills blanks.
- Overwrite: always writes every matched field, unconditionally.
How does Smart mode decide what counts as "already matching"?
Smart mode compares each field the match would write against what's already embedded in the file: title, author, series, genre, and ASIN, plus sequence, narrator, and year when the edit mode is Full. It only marks the book Smart-skipped (nothing written) when every one of those checked fields already matches. If even one differs, the file is written normally.
Force reprocess only bypasses the "already processed" check, so the book is re-searched and re-matched from scratch. It does not override what the write mode decides once a fresh match is found:
- Smart + Force: re-matches from scratch, but if the fresh match's fields are identical to what's already embedded, the book still shows Smart-skipped. Force restarts the search, not the write.
- Fill missing + Force: still only fills currently-blank fields either way, a no-op if nothing's blank.
- Overwrite + Force: the only combination that reliably rewrites everything, since Overwrite always writes the full fresh match regardless of what's already there.
Suggested Workflow
Optional first step: stage new books in one folder, e.g. _unorganized. Not strictly necessary, but keeps newly-added books separate from your organized library.
- Dry run with backupMetadata Forge, Apply off, Back up and cache on. Pre-populates the cache before anything is written.
- Review report, generate Suspect ReportCheck Matched and Manual Review, then run Suspect Report to catch likely false positives.
- Fix bad matches manuallyResolve anything in Manual Review by hand.
- ApplyWrites the matched metadata for real.
- Organizer: Index library (one time only)Refreshes the destination-structure cache before the first real run.
- Organizer: dry run + consolidatePreviews the planned moves. Consolidation should always be checked as a full-root dry run first.
- Review the plan, generate Suspect ReportCatch bad destination paths and move anything wrong manually.
- ApplyCommits the previewed moves.
Report Badge Legend
Every status and badge a book can show in a report, and what it means for that file.
| Badge | Meaning |
|---|---|
| Match Report card | |
| Matched | A confident match was found. Will write or wrote metadata per the active write/edit mode. |
| Smart-skipped | Write mode is Smart and every checked field already matched. Nothing written. |
| Skipped | Explicitly excluded before matching (skip pattern, ignored folder), or no usable match was found. The badge also shows the reason, e.g. "Skipped — no usable Audible match". This is also what puts a book in Manual Review with the no match tag below. |
| Not Matched | Fallback for a status LibraForge doesn't recognize. Shouldn't normally appear — every real outcome is one of the other statuses on this list. |
| Error | Something failed while processing this file. |
| Manually Applied | This book's metadata was set by hand via Manual Review. Automatic runs skip it permanently from then on (regardless of score), so a later run can never overwrite your manual work by accident. Force reprocess is the only way to make it reprocess again. Also shown in the Manual Review list, using this same badge, for the same reason. |
| 87% | Match confidence. |
| Full metadata | Which edit mode was used for this book: Full metadata or Series only. |
| Audible | Which source produced the match: Audible, ABS, abs-agg (LibriVox, Storytel, Audioteka, BookBeat, Big Finish, ARD Audiothek, Die drei ???), GraphicAudio, Soundbooth Theater, Goodreads, or Kindle. |
| GR LIMITED | Goodreads (abs-tract) was tried for this book but the circuit breaker was open (Goodreads was rate-limiting us), so the lookup was skipped rather than counted as a genuine no-match. A warning explains this and suggests a lower search-worker count when a run trips the breaker. |
| written | What actually happened on disk: written, smart-skipped, no-op, skipped, or error. |
| Multi-file | This book spans multiple audio files that were grouped and treated as one item for matching and writing. |
| Manual Review reason tags | |
| no match | Skipped because no usable match was found (the Skipped status above). Other red reason tags: asin conflict, low score, missing metadata, unsafe match, no metadata, status:skipped, mode:none, or an N% duration-diff tag. |
| Suspect Report | |
| critical high medium low info | Severity, most to least urgent. Shown on Suspect Report cards, generated on demand from the last run's report (Metadata Forge and Folder Forge both produce one). |
| 2 files | The specific field or fact (duplicate ASIN, missing series, number conflict, etc.) that flagged this item, or how many related files were involved. |
| no series | A group of books share strong identity signals (author, narrator, publisher) but have no series tag at all. Opens the Fix Series dialog. |
| series drift | A group of books already tagged with a series have inconsistent or drifting series data across the group. Opens the Fix Series dialog. |
metadata.json
An Audiobookshelf-native metadata.json sidecar is written for every matched book. It's LibraForge's one guaranteed, universal output, independent of audio format or whether embedded-tag writing is even possible or desired (--metadata-json-only skips tags entirely; metadata.json is written either way).
On repeat runs it follows the same write-mode skip logic as tags, so there is no needless rewrite once nothing's changed. But it is not the same file as libraforge.json, which sits right alongside it and holds LibraForge's own internal tracking: whether and how a book was processed, cached duration data, and more.
Because they're separate files: Audiobookshelf's own Store metadata with item server setting only controls where Audiobookshelf writes its own copy of metadata.json: next to the book if enabled, or internally under /metadata/items/ if not. Either way it never touches libraforge.json, so LibraForge's own tracking is unaffected.
Recommended setup: keep Store metadata with item OFF, so Audiobookshelf never overwrites the metadata.json LibraForge wrote. This still works because Audiobookshelf's scanner reads whatever metadata.json is already sitting in the book's folder regardless of that setting, it only governs Audiobookshelf's own writes, not what the scanner reads. Then set the library's Scanner metadata priority to Audiobookshelf metadata file highest, Audio file meta tags second, Folder structure lowest, so LibraForge's matches win. See Audiobookshelf's own Book Scanner guide for the exact settings.
Report types
What each tool produces, and where to find it.
- Metadata Forge report: per-book match/write outcome (the badges above), downloadable after a run.
- M4B Tool report: conversion/merge outcomes.
- Folder Forge report: planned/applied moves.
- Library Downloader report: per-book download outcome.
- Suspect Report: generate a report based on the last run. Targets full matches passing certain triggers, to simplify finding a bad full write manually. Note: some false positives will always show up, the idea is to significantly narrow down manually reviewing a full run report, without affecting the actual matching capability.
Owned badge & duplicate handling
Duplicate handling when downloading an Owned title: Keep both copies, Replace the existing copy, or Choose per item.
Supports local and network-mounted paths - the path must be accessible from within the container
(e.g. /mnt/nas/audiobooks).
Scan result
Missing an ASIN or a core tag (title, author, or narrator). The Metadata Forge fills these in.
Review in Metadata Forge →Run the full pipeline
Tags whatever needs tagging, converts whatever needs converting, then plans moves for everything that's ready - one combined report at the end.
Or go straight to a stage