Import Lists
Import lists automatically sync books from external sources into your Narratorr library as “wanted” books. Once added, Narratorr searches for and downloads them like any other book.
Configure import lists in Settings > Import Lists.
List Types
Section titled “List Types”Two list types are available: NYT Bestsellers and Hardcover.
NYT Bestsellers
Section titled “NYT Bestsellers”Adds books from the New York Times bestseller lists. Good for automatically tracking popular new releases.
| Field | Description |
|---|---|
| Name | Display name for this list |
| API Key | NYT Developer API key (developer.nytimes.com) |
| Bestseller List | Dropdown with two choices: Audio Fiction (audio-fiction, default) or Audio Nonfiction (audio-nonfiction). |
Hardcover
Section titled “Hardcover”Syncs books from Hardcover (hardcover.app) — trending books, a specific shelf, or any Hardcover list by URL.
| Field | Description |
|---|---|
| Name | Display name for this list |
| API Key | Hardcover API key |
| List Type | trending (popular books), shelf (a specific shelf), or custom (any Hardcover list by URL) |
| Shelf ID | Required when list type is shelf — the Hardcover shelf ID to sync |
| List URL | Required when list type is custom — the list’s address on hardcover.app (e.g. https://hardcover.app/@username/lists/list-slug) |
| Import Max | Custom lists only — how many items to sync: 50 (default), 100, or All |
A custom list syncs the first Import Max items in list order; All pages through the entire list.
Common Settings
Section titled “Common Settings”Every import list has these shared settings:
| Setting | Description |
|---|---|
| Enabled | Toggle the list on/off without deleting it |
| Sync Interval | How often to sync, in minutes (minimum 5). Default: 1440 (daily). |
How Sync Works
Section titled “How Sync Works”- On each sync cycle, Narratorr fetches items from the external source
- Each item is enriched with metadata. When an item has an ASIN, Narratorr resolves it directly. If that ASIN doesn’t resolve to an audiobook (for example, a print or Kindle ASIN), Narratorr automatically falls back to a title/author metadata search and adopts the matching audiobook’s ASIN instead — so a non-audiobook ASIN no longer dead-ends. Items without an ASIN are matched the same way, by title/author search. An item that genuinely can’t be resolved is still added, but flagged as needing attention (a “failed” enrichment state) and retried automatically later (roughly hourly)
- If the book doesn’t already exist in your library, it’s added with status
wanted - Books you already own (the same recording) are skipped. A different recording of an owned title is added as a new book, and an ambiguous match is held rather than imported or silently dropped — it’s recorded as a “recording review skipped” event on the existing book’s history
- Newly added books appear in your library. If Search Immediately (Settings > Search, “When a New Book Is Added”) is enabled, an import-list-added book triggers a search right away; otherwise it’s picked up on the next scheduled search cycle
Testing and Preview
Section titled “Testing and Preview”- Test — verifies the connection and credentials are valid
- Preview — fetches the first 10 items from the list so you can see what would be imported before enabling
- Sync errors are stored and visible in the list settings — check here if a list stops syncing
- Books added by import lists track which list they came from, visible on the book detail page
- Deleting an import list doesn’t remove books it previously added