Audiobookshelf metadata matching: Match vs Quick Match and fixing wrong titles or chapters

Match lets you pick the right search result and choose which details to keep. Quick Match takes the first result and, by default, only fills in details that are empty.

Both are separate from a library scan. A scan only reads what’s already on your disk: folder names, tags inside the audio files, and any metadata files next to them. The one exception is covers: with Find covers on in the server settings, a scan looks one up online for books that have none. So a fresh book can show up with a bare title until you match it.

Where does a scan get its details?

By default, Audiobookshelf reads these sources in order, and a later one wins over an earlier one:

1. Folder names (author, series and title)
2. Tags inside the audio files, or the details inside an ebook file
3. An .nfo file
4. .txt files (desc.txt and reader.txt)
5. An .opf file
6. Audiobookshelf’s own metadata.json

You can change the order in a library’s settings, under Metadata order of precedence. When you edit a book in Audiobookshelf, it saves your changes to metadata.json, which is last in the default order. So your edits beat what the files say on the next scan.

What’s the difference between Match and Quick Match?

Match lets you pick. Open a book, click the edit (pencil) button and go to the Match tab. Choose a provider, search, pick the right result, then tick which details to copy over before you save.

Quick Match doesn’t ask. It searches the library’s metadata provider and takes the first result. It only fills in details that are empty and adds a cover if the book has none. Turn on Prefer matched metadata in the server settings if you want Quick Match to replace what’s already there.

To quick match many books, select them in the library (click the small circle on each cover), open the three-dot menu in the bar along the top and choose Quick Match. You need to be an admin.

Which provider a library uses is set when you edit the library, under Metadata Provider. New libraries start on Google Books. For audiobooks, an Audible store is often the better fit, since it lists narrators and series.

What does Quick Embed do?

Matching changes what Audiobookshelf shows, not the tags inside your audio files. Embedding writes the details into the audio files themselves, so other players see them too.

• Embed Metadata (on the book’s Tools tab, then Open Manager) writes the details and cover into the files, and the chapters too if the book is a single file. It backs up the originals first unless you turn that off.
• Quick Embed does the same in one click, from the same tab or for many selected books. It does not make a backup, and it says so before it starts.

Keep a copy of your audio files before you quick embed a large batch.

Why does my book show the series name as the title?

A tag inside the audio file holds the series name. For the title, Audiobookshelf reads the album tag first and the title tag if there’s no album, and tags win over the folder name in the default order. So this happens when the album tag holds the series name, or when the album tag is empty and the title tag holds it. If every book in the series has it, they all show the same title.

1. Open the book, click the edit (pencil) button and type the right title on the Details tab. Save.
2. Run Match if you also want the cover and description.
3. Optional: Quick Embed, so the file’s own title tag is fixed for other apps too.

For a whole series, select the books and use the batch edit (pencil) button in the selection bar.

Why are my chapters wrong after matching?

Chapter times depend on the exact edition. A book that Audible sells in two parts has different chapters from the single-volume edition, and the same goes for abridged and unabridged releases.

In Audiobookshelf, online chapters come from Lookup on the book’s chapter editor, and it looks them up by ASIN (Audible’s ID for the book). If a match set the ASIN of a different edition, the chapters drift.

1. Open the book, click the edit (pencil) button, go to the Chapters tab and click Edit Chapters (or Add Chapters if it has none).
2. Click Lookup. Check the ASIN is the one for your edition and search.
3. Compare Duration found with Your audiobook duration. If they differ, a warning says your audiobook is shorter or longer.
4. If they’re far apart, find the ASIN for your edition on Audible and search again. When they line up, click Apply Chapters, then Save in the chapter editor.

Why doesn’t Audiobookshelf read the series from my EPUB?

Audiobookshelf reads a series from an EPUB, or from an .opf file, only when it uses Calibre’s series tags (calibre:series and calibre:series_index). If your EPUB stores the series some other way, Audiobookshelf won’t read it.

Add the series by hand on the Details tab, or set it in Calibre before you add the file.

More fixes for matching

• New books getting the wrong metadata covers books that take another book’s details on network storage.
• Server crashes after a quick match covers the series error that can stop the server.
• Series in the wrong order covers sequence numbers.