Features Reference
This page covers features that don’t need a full dedicated guide. For the major features, see their dedicated pages in the sidebar.
Activity Page
Section titled “Activity Page”The Activity page (/activity) is your command center for monitoring what Narratorr is doing. It has two sections:
Active Downloads — shows all in-progress downloads with real-time progress bars (via SSE streaming). Each card shows download speed, ETA, and progress percentage. Downloads in pending_review status show quality gate data with Approve, Reject, and Reject & Search buttons. See Quality Gates for details.
Event History — a chronological log of everything that’s happened:
| Event Type | Fires When |
|---|---|
grabbed | A release was sent to a download client |
grab_failed | Sending a release to the download client failed |
download_completed | Download finished successfully |
download_failed | Download failed |
imported | Book was imported into the library |
import_failed | Import failed |
book_added | A book record was created (e.g. via library scan or manual add) |
metadata_fixed | Book metadata was corrected via fix-match |
wrong_release | A release was rejected as the wrong match |
merge_started | A book merge was started |
merged | A book merge completed |
merge_failed | A book merge failed |
deleted | A book was deleted |
renamed | A book’s files were renamed/moved |
file_tagged | Audio file tags were written |
held_for_review | Quality gate held a download for manual review |
recording_review_skipped | An import-list book matched an owned title but couldn’t be confidently classified as the same recording, so it was held for review instead of added — see Multiple Editions |
Events can be filtered by type and searched by book title. Individual events and bulk cleanup are supported.
Library Scan
Section titled “Library Scan”Library scan discovers and catalogs audiobooks that are already in your library folder. It’s useful when:
- Migrating an existing collection to Narratorr
- Files were added to the library folder outside of Narratorr
- You want to re-scan after manually reorganizing files
Trigger a scan from the Library Actions menu on the Library page (Refresh Library). The scan discovers audio files in subfolders, matches them to metadata, and creates book records.
The Library Actions menu gathers the library’s page-level actions in one place: Import Files and Import Existing Library, Refresh Library, Search Wanted, the bulk operations (Rename, Re-tag, Write Sidecars), and Remove Missing Books. Actions that would run against a busy library (a bulk job already in flight) are disabled until it finishes, and an in-progress bulk job shows its progress and any failures on the menu button itself.
Rescan
Section titled “Rescan”A rescan re-enriches existing books — updating metadata and file-based quality information (codec, bitrate, duration). Useful after manually replacing files.
Search Pipeline
Section titled “Search Pipeline”When you search for a book (manually, via scheduled search, or RSS), Narratorr:
- Queries all enabled indexers simultaneously
- Removes blacklisted releases
- Enriches each result with language (detects and normalizes the release language)
- Filters multi-part Usenet posts
- Applies quality gate filters (reject/required words, format, min seeders, size floors/caps, grab floor) and partitions results by language
- Ranks results by quality (MB/hour), with protocol preference as a tiebreaker
The scheduled search job runs on a configurable interval (Settings > Search > Interval, default: 360 minutes / 6 hours) and searches for all books with status wanted.
Prowlarr Sync
Section titled “Prowlarr Sync”If you use Prowlarr to manage your indexers, you can have it push them to Narratorr automatically instead of configuring each one manually. Narratorr exposes a Readarr-compatible API (the Prowlarr-compat shim), so Prowlarr treats Narratorr like any other Readarr application and syncs indexers into it.
The setup happens entirely inside Prowlarr — there is no sync screen in Narratorr:
- In Prowlarr, go to Settings > Apps and add Narratorr as a Readarr application
- Point it at your Narratorr URL and API key
- Prowlarr then pushes its torznab/newznab indexers into Narratorr automatically, keeping them in sync as you add or change indexers in Prowlarr
Narratorr accepts Readarr’s echo-only fields liberally (it strips unknown fields rather than rejecting them), so Prowlarr’s app-sync works without extra configuration.
Health Checks
Section titled “Health Checks”Narratorr periodically runs health checks and displays results in the sidebar. Checks include:
| Check | What It Monitors |
|---|---|
| Indexers | Tests each enabled indexer’s connection |
| Download Clients | Tests each enabled client’s connection |
| Library Root | Verifies the library path exists and is writable |
| Disk Space | Warns when free space drops below threshold |
| ffmpeg | Verifies ffmpeg is accessible (if configured) |
| Hardcover | Tests the Hardcover API connection when a Hardcover API key is configured in Settings > Search > Metadata (skipped if no key is set) |
| Stuck Downloads | Flags downloads with no progress for over an hour |
Each check reports healthy, warning, or error. State transitions trigger notifications if you have health event notifications configured.
Real-Time Updates (SSE)
Section titled “Real-Time Updates (SSE)”Narratorr uses Server-Sent Events to push updates to the browser without polling. The UI automatically reflects:
| Event | What Updates |
|---|---|
download_progress | Progress bar, speed, ETA on active downloads |
download_status_change | Download card status badge |
book_status_change | Book status on library/detail pages |
import_complete | Library refreshes to show new import |
grab_started | Activity page shows new download |
review_needed | Toast notification for pending review |
If your browser disconnects, the UI falls back to periodic polling.
Post-Processing Script
Section titled “Post-Processing Script”Run a custom script after each successful import. Configure in Settings > Post Processing.
| Setting | Description |
|---|---|
| Post-Processing Script | Path to the script or command to execute |
| Script Timeout | Maximum execution time in seconds. Default: 300 (5 min). Minimum: 1. |
The script receives the audiobook path as its first argument, plus these environment variables:
| Variable | Description |
|---|---|
NARRATORR_BOOK_TITLE | Book title |
NARRATORR_BOOK_AUTHOR | Author name (empty string if unknown) |
NARRATORR_IMPORT_PATH | Final library path |
NARRATORR_IMPORT_FILE_COUNT | Number of audio files |
Use this to trigger media server scans, send custom notifications, or run format conversions that Narratorr doesn’t handle natively. Script failures don’t block the import — they’re logged as warnings.
Author Page
Section titled “Author Page”The author detail page shows all books by an author, organized by series. It displays:
- Author name and metadata
- Series sections with books in order, showing owned vs. missing entries
- Standalone books (not part of a series)
- Quality badges and status indicators for each book
Click any book to go to its detail page.
Version Check
Section titled “Version Check”Narratorr periodically checks GitHub for new releases. When a newer version is available, a notification banner appears in the UI with a link to the release page.
You can dismiss the notification for a specific version — it won’t reappear until an even newer version is available. The dismissed version is stored automatically when you dismiss the banner; it is internal state, not a field you edit in Settings.
Pagination
Section titled “Pagination”All list views (library, activity, event history, blacklist) support pagination. Use the controls at the bottom of the list to navigate pages or change the page size.