# Talearr
An ebook and audiobook collection manager, based on Chaptarr.
> This is the full reference: every Talearr change, setting and API route. Start with the [README](../README.md).
## What is Talearr?
Talearr is a fork of [Chaptarr](https://github.com/Chaptarr/chaptarr), which is itself a
fork of [Readarr](https://github.com/Readarr/Readarr) from the
[Servarr](https://wiki.servarr.com/) project family. It manages audiobook and ebook
libraries in one instance: narrator and edition aware metadata, separate audiobook and
ebook root folders, series handling, quality profiles and upgrades, and the usual
download client and indexer integrations.
Talearr tracks Chaptarr closely. The differences today are the name and icon, a separate
Talearr version, a "Works best with" block in System > Status (Allseerr, NoBookEnds), a
grab policy (see below), two import additions (completed downloads that only hold archives
are unpacked before import, and downloaded files whose own language is not the wanted one
are rejected; see [TALEARR_IMPORT.md](TALEARR_IMPORT.md)), fixes to edition choice,
release title matching, Audible duplicates and duplicate rows on add (see [TALEARR_MATCHING.md](TALEARR_MATCHING.md)),
audiobook naming tokens, multi-disc import and an optional merge to M4B (see
[TALEARR_AUDIOBOOKS.md](TALEARR_AUDIOBOOKS.md)), audiobook recordings (abridged and
unabridged, or two narrators, side by side, with a recording-aware upgrade guard; see
[TALEARR_RECORDINGS.md](TALEARR_RECORDINGS.md)), Audiobookshelf library awareness
(see [TALEARR_AUDIOBOOKSHELF.md](TALEARR_AUDIOBOOKSHELF.md)), and its own Docker
image and CI. The icon master is
`Logo/talearr-icon-master.png`.
Talearr behavior changes so far (all without schema changes, new settings or `config.xml` edits):
- **Metadata server probe.** A small GET to the root of the configured metadata server
every 15 minutes (10 s timeout, backing off from 2 to 30 minutes while it is down, 5 minutes
while slow or rate limited; a new problem is confirmed by a second probe 30 s later). Problems
show in System > Status. A refresh during an outage keeps existing authors and books as they
are and logs one warning per outage instead of an error per author. The server used is
unchanged. State is in memory only.
- **Rejection reasons in interactive search.** Every rejected release shows a short label
("Language", "Wrong book", "Pack", "Size", "Blocklisted", ...) with the full reasons in a
popover. The API adds `label` and `source` to each `rejectionDetails` entry; `rejections`
and every existing field are unchanged. A new decision specification is labelled from its
category or class name automatically.
- **Adding one book monitors only that book.** Through the UI or `POST /api/v1/book`, a book
for a new author monitors only that book, and future releases stay unmonitored unless the
request sets `monitorNewItems` / `audiobookMonitorNewItems` / `ebookMonitorNewItems`.
`addOptions.monitor = "all"` still monitors the whole catalog. The add-book modal defaults to
"Only this book" and "None"; saved browser defaults from before Talearr are switched once.
The new author also keeps only that book instead of its whole catalog (see
[Tracked authors](#tracked-authors)).
- **Merge duplicates (Library > Duplicates).** Lists authors with the same name and book rows
of one author with the same title and media type, and merges them: the kept row keeps its
ids, everything else (editions, book files, history, queue and blocklist matches, series and
narrator links) moves onto it, monitoring is combined, and the duplicate rows are removed in
one transaction. Files on disk are never moved or deleted. Ebook and audiobook rows of one
book are siblings and are never merged. A preview shows exactly what moves. API:
`GET /api/v1/talearr/merge/candidates`, `POST /api/v1/talearr/merge/authors|books`
(`targetId`, `sourceIds`, `dryRun`, `force`). Merges stay merged: the provider ids of the
removed rows are kept in `talearr.db` pointing at the kept row, so a later refresh or add that
still sees an old id updates the kept row instead of adding the duplicate again.
- **Large libraries.** Fewer full-library loads: the book index loads series links once with a
single scan, Wanted, Cutoff Unmet, the calendar and author pages read statistics for their
own authors only, and book routes by `titleSlug` (Allseerr links) look the slug up instead
of loading every book.
## Audiobooks
See [TALEARR_AUDIOBOOKS.md](TALEARR_AUDIOBOOKS.md).
- **Book title in names.** Folders and files are named after the book ("1984"), not the
matched edition's store listing ("Nineteen Eighty-Four (MP3 Book)"), and format noise such as
`(Audible Audio)`, `(Audio Cassette)` or `[Unabridged]` is dropped from the title.
- **Naming tokens.** `{Book SeriesPosition:00}` (zero padded), `{Book Year}` (empty when unknown),
`{Abridged}` / `{Abridgement}`, and ready-made layouts in the naming help, including
Audiobookshelf's `Author/Series/01 - 1994 - Title {Narrator}/files`.
- **Multi-disc import.** CD1/Disc 2/Part 03 folders and many-file rips import as one book in
playing order (track and disc tags, then disc folder numbers, then a natural sort); files with
the same name on different discs no longer overwrite each other; a folder holding two books
(by album tags) is matched as two books.
- **Merge to M4B.** Settings > Conversion > Merge after import (off by default) and a Convert to
M4B button on the book page merge multi-file mp3/m4a audiobooks into one chaptered M4B with
FFmpeg, keeping the cover and tags. The originals are removed only after the M4B is verified
(duration within 1%). Stored as the `talearr.audiobook.m4bafterimport` row in the `Config`
table through the new `/api/v1/config/talearrm4b` route.
**Convert library to M4B** in the same section merges every multi-file audiobook already in
the library, one book at a time (manual only; a failed book keeps its files).
- **Audio quality ladder and ebook formats.** Settings > Profiles ranks releases the quality
profile ranks equal: audio by tier (AAC 64 kbps+, MP3 128 kbps+ and lossless are good, under
32 kbps or implausibly small ranks last), read from the title or estimated from size against
the book's known runtime, and ebooks by a format order (EPUB > AZW3 > MOBI > PDF). Opt-in:
upgrading low bitrate audio to a clearly better copy of the same recording, upgrading an ebook
to a preferred format, and a minimum bitrate. `talearr.ladder.*` Config rows through
`/api/v1/config/talearrqualityladder`.
## Recordings
See [TALEARR_RECORDINGS.md](TALEARR_RECORDINGS.md).
- **More than one recording per audiobook.** Keep the abridged and the unabridged reading, or
two narrators, each with its own files and folder. The book page lists the recordings with
narrator, runtime, abridged or unabridged (and where that answer came from), Audible
marketplace and ASIN, and file status, and has "Add another recording" (unabridged, abridged,
another narrator, pick an edition) and "Remove this recording" (asks first, never the primary
recording, never automatic). Recordings are Chaptarr's own copy entries, so a rollback keeps
them.
- **Audible facts.** Narrator, runtime and abridged or unabridged per edition from the Audible
catalog of the chosen marketplace (US by default), cached in `talearr.db`. Audnexus is opt in.
The grab policy and the `{Abridged}` naming tokens use the same answer.
- **Own folder per recording.** When the naming format would put two recordings in one folder,
the copy gets ` (Abridged)`, the narrator, the edition year or the ASIN appended.
- **Upgrade guard.** An audiobook upgrade only replaces files of the same recording, never with
fewer channels or a lower measured bitrate, and bitrate gains count only within one codec. An
unabridged download for abridged files becomes its own recording (Keep both recordings).
When the guard rejects an upgrade download (the size estimate looked better, the real files
were not), the download is failed without a new search, which blocklists that release, and
automatic searches do not grab upgrades for that book for 7 days (an "Upgrade paused" soft
filter; interactive search can still grab). Explicit user grabs stay in the queue. The pause
is kept in `talearr.db`.
- **Per-book abridged policy.** A book can have its own Abridged audiobooks value (unabridged
only, abridged only, prefer unabridged, any), set by Allseerr through
`GET|PUT /api/v1/talearr/grabpolicy/book/{bookId}`. An abridged only book without files
monitors its best abridged edition before it is searched; when none is known, its history says
so. Additional recordings keep their own behaviour.
- **API** for Allseerr and NoBookEnds: `GET|POST /api/v1/talearr/recordings`,
`DELETE /api/v1/talearr/recordings/{bookId}`, `GET|PUT /api/v1/config/talearrrecordings`.
Storage: a separate `talearr.db` next to `chaptarr.db` (a rebuildable cache, plus the per-book
abridged values, which fall back to the global policy if it is lost), and `talearr.recordings.*`
and `talearr.upgrade.*` rows in the `Config` table. No schema change, no migrations, no
`config.xml` edits.
## Series
See [TALEARR_SERIES.md](TALEARR_SERIES.md).
- **Series page and Library > Series.** Every series with its books in order and the audiobook
and ebook status of each.
- **Monitor a series** as audiobooks, ebooks or both: every main book is monitored and searched,
and so is each new book that appears in the series later (applied after every author refresh
and every 6 hours). It never unmonitors anything, follows the grab policy for box sets and
leaves additional recordings alone.
- **API**: `GET|PUT /api/v1/talearr/series/{id}`, `GET /api/v1/talearr/series`,
`POST .../apply`, `POST .../authors`.
Storage: one `talearr.series.monitor.*` row per monitored series in the `Config` table.
## Wishlists
See [TALEARR_WISHLISTS.md](TALEARR_WISHLISTS.md).
- **Settings > Import Lists > Wishlists**: StoryGraph to-read and Audible wishlist exports,
Goodreads CSV exports, any title/author/ISBN/ASIN CSV, and Hardcover lists by URL (upstream's
Goodreads and Hardcover Library import lists are unchanged and cover shelves and Want to Read).
- Each row is matched (ASIN, ISBN, then title and author) and added with "Only this book": only
that book is monitored, in the chosen formats, once. Preview shows the matches first; Sync
Wishlists runs every 12 hours.
- **API**: `/api/v1/talearr/wishlists` (list, add, change, remove, preview, sync).
Storage: one `talearr.wishlist.*` row per wishlist in the `Config` table and uploaded files in
`talearr-wishlists/` in the config folder. Not an import list provider, so a rollback deletes
nothing.
## Tracked authors
See [TALEARR_TRACKED_AUTHORS.md](TALEARR_TRACKED_AUTHORS.md).
- **Only my books.** An author added for a book request (add-book modal, `POST /api/v1/book`,
Allseerr, wishlists, MAM filler imports) keeps only the books you added, requested, monitor or
have files for. Refresh updates them and adds none of the rest of the catalog. Adding an author
still follows all of its books.
- **Requested books pass the metadata profile.** An explicitly requested book is added even
when a profile rule (omnibus, parts and sets, ignored terms, popularity, ...) would skip it.
Import list exclusions still apply.
- **Switch any time** on the author page: **Follow all books** brings the catalog in, **Only my
books** (confirmed first) removes unmonitored, fileless catalog rows. Files are never touched.
- **API**: `GET|PUT /api/v1/talearr/authors/{id}/catalog` with `{"mode": "full" | "tracked"}`;
the author resource carries `talearrCatalogMode`.
Storage: one `talearr.authorcatalog.*` row per "Only my books" author in the `Config` table. A
rollback to Chaptarr treats every author as followed in full again.
## Author page groups
In the author page **All** view, the author's main works come first and collections, study
guides and graded readers, adaptations, other listings of the same book and other languages are
in a collapsed **Other listings** section. Monitored books and books with files are always main
works; nothing is hidden or removed. See [TALEARR_AUTHOR_PAGE.md](TALEARR_AUTHOR_PAGE.md).
## Book tags and genre filters
- **Book tags.** Tag single books with the same tags as authors (Settings > Tags): in the book's
Edit dialog or in bulk with Set Book Tags in the book index editor. Shown on the book page and
in the index Tags column.
- **Custom filters.** The book index adds Book Tags, Author Tags (for the book's format),
Format, Has File and Any Recording Narrator to the existing filters (genres, narrator,
monitored). Wanted > Missing and Cutoff Unmet get custom filters on book tags, author tags,
genres, narrator and monitored.
- **Metadata profile genres and content types.** Allowed and blocked genre lists, and Skip Short
Stories, Skip Novellas, Skip Anthologies and Skip Graphic Novels, applied on author add and
refresh like the other profile rules (manual adds and books with files are kept; books the
metadata has no genres for always pass). All off by default.
- **API**: `GET /api/v1/talearr/booktags`, `GET|PUT .../booktags/{bookId}`,
`PUT .../booktags/editor`, `GET /api/v1/talearr/genres`; `talearrContentFilter` on
`/api/v1/metadataprofile`; `talearrFilter` (JSON) on `/api/v1/wanted/missing` and `.../cutoff`.
Storage: book tag links in the `BookTags` table of `talearr.db` (lost only if that file is
recreated), one `talearr.metadataprofile.