Skip to content

Add your books

Tandem reads the ebooks and audiobooks you already have. There is no bookstore and no upload button in the usual sense: you point the server at two folders on disk, and it scans, reads metadata, and pairs each ebook with its audiobook.

Before you start

The server mounts two folders: one for ebooks, one for audiobooks. Folder depth inside each is up to you — Tandem reads folder and filename patterns to work out author, series and title, so how you organize files matters more than how deep you nest them.

Supported formats:

Kind Extensions
Ebooks .epub, .pdf, .mobi, .azw3
Audiobooks .mp3, .m4a, .m4b, .flac, .ogg, .wav, .aac, .wma

Only EPUB is fully usable. Chapter extraction, the readers, and text-to-audio alignment all work on EPUB. A PDF can be stored and paired with an audiobook, but it never aligns — there is no sentence text to extract from it. .mobi and .azw3 files are indexed but flagged as unsupported until you convert them.

An audiobook is one file. If a book was ripped as 01.mp3 … 30.mp3, Tandem does not import it at all — a folder of tracks is skipped and listed under System → Troubleshoot Library → Multi-file audiobooks. Merge the tracks into a single .m4b first — Audiobookshelf's Merge to M4B tool (Manage → Merge to M4B) does this and can keep chapter markers — then rescan.

Steps

  1. Scan the library. From System → Troubleshoot Library, click Run Verification Scan. It walks both folders, extracts metadata, and auto-pairs what it can match.
  2. Convert anything unsupported. A .mobi or .azw3 file shows up under System → Unsupported. Converting it runs Calibre in the server container and writes an .epub next to the original.
  3. Fix up the pairs. Anything the scan could not match confidently is left unpaired. Pair it by hand under Pairs → Unpaired.
  4. Check Troubleshoot for anything else that needs attention — multi-file audiobooks waiting to be merged, and unsupported formats waiting to be converted.

Metadata for each file comes from up to three places, in order, each overriding the last field by field: filename and path patterns are always tried first, embedded metadata (the EPUB's own details, or the audio file's tags) overrides the pattern's guess where present, and — only if you configure Audiobookshelf — an enrichment pass can fill in more. Online lookups (Google Books, Open Library, and others) are a manual step from a book's own page, never automatic.

A typical pattern for an audiobook path looks like Author/Series/17 - Title.m4b, which parses into author, series, book number, and title. Defaults exist for both ebooks and audiobooks and can be edited under System → Library Settings.

Auto-pairing after a scan compares unpaired ebooks against unpaired audiobooks and matches on title, author and series together — it favors being conservative over being wrong, so a marginal match is left for you to confirm rather than guessed at.

Why it is like this

One file per audiobook keeps the library and the pairing honest. Importing individual tracks as separate "books" used to happen, and it polluted both the library listing and the auto-matcher with fragments that were never meant to stand alone.

EPUB is the only format with text that can be pulled out sentence by sentence. Reading position sync depends on lining up a sentence of narration with a sentence of text, and a PDF or a MOBI file does not expose that in a form Tandem's readers can use — MOBI in particular flattens an entire book into a single chapter, which is not enough to build a page-level sync map from.

Go deeper