Narratorr’s settings are accessible from Settings in the sidebar. The sidebar has these tabs: General, Audio Tools, Post Processing, Indexers, Download Clients, Search, Notifications, Connectors, Blacklist, Security, Import Lists, and System. Each tab stacks one or more sections on a single scrolling page.
This page documents the settings sections grouped by the tab they live under. Indexers, Download Clients, Notifications, Connectors, Blacklist, Security, and Import Lists have dedicated pages — linked at the bottom.
The General tab stacks the Library, File Naming, Import, Network, Discovery, Ebooks, Appearance, and Onboarding sections.
| Setting | Description |
|---|
| Library Path | Root directory where Narratorr stores your audiobooks. In Docker, this maps to /audiobooks. |
| Setting | Description |
|---|
| Preset | Apply a naming preset (Standard, Detailed, Audiobookshelf, Plex, Last-First) that fills in both formats below; choosing your own tokens shows as “Custom”. |
| Separator | Word separator applied to every rendered token. Options: Space, Period, Underscore, Dash. Default: Space. |
| Case | Casing transform applied to rendered names. Options: Default, lowercase, UPPERCASE, Title Case. Default: Default (no change). |
| Folder Format | Template for organizing audiobook folders. Uses tokens like {author}/{title}. See Folder Format Tokens. |
| File Format | Template for renaming audiobook files within folders. |
| Setting | Description |
|---|
| Delete After Import | Remove the downloaded torrent from the download client after files are imported. |
| Minimum Seed Time | For torrents: minimum time (in minutes) a torrent must seed before Narratorr removes it. Only applies when Delete After Import is on. Default: 60. |
| Minimum Seed Ratio | Minimum upload ratio before removing a torrent. Only applies when Delete After Import is on. Default: 0 (disabled). |
| Redownload Failed | Automatically search for and grab a different release when a download fails. Default: on. |
| Minimum Free Space | Block imports when free disk space (in GB) is below this threshold. Default: 5. Set to 0 to disable. |
| Setting | Description |
|---|
| Proxy URL | HTTP/HTTPS/SOCKS5 proxy for indexer search and test requests. A per-indexer “Route through proxy” toggle decides which indexers use it. See Network & Proxy. |
| Setting | Description |
|---|
| Enable Discovery | Toggle the recommendation engine on/off. Default: on. |
| Refresh Interval | Refresh frequency in hours. Range: 1–168. Default: 24. |
| Max Suggestions Per Author | Maximum suggestions per author. Range: 1–50. Default: 5. |
| Suggestion Expiry | Days before unused suggestions expire. Default: 90. |
See Discovery & Recommendations for details.
| Setting | Description |
|---|
| Enable ebook support | Show ebooks already stored in a book’s folder, ready to download from the book page. Narratorr doesn’t search for or download ebooks. Enabling this also exposes them over the API, which is how Narratorr Requests offers Download and Send to Kindle. Default: off. |
| Setting | Description |
|---|
| Dark Mode | Switch between the light and dark theme. Stored per-browser, not in the database. |
| Setting | Description |
|---|
| Welcome tour | Re-display the welcome modal that reviews key defaults and feature highlights. |
The Search tab stacks the “When a New Book Is Added”, Search (including the RSS Sync subsection), Metadata, Filtering, and Quality sections.
Defaults applied whenever a book is added (manually, via import lists, or via discovery).
| Setting | Description |
|---|
| Search Immediately | Trigger a search as soon as a book is added. Default: off. |
| Setting | Description |
|---|
| Enable Scheduled Search | Toggle automatic searching on/off. Default: on. |
| Search Interval | How often (in minutes) Narratorr searches for wanted books. Range: 5–1440. Default: 360 (6 hours). |
| Blacklist TTL | How many days temporary blacklist entries last. Range: 1–365. Default: 7. See Blacklist. |
| Search Priority | Order results by Audio Quality (higher bitrate) or Narrator Accuracy (match the narrator from metadata). Default: Narrator Accuracy. |
| Protocol Preference | Prefer usenet, torrent, or no preference. Affects result ordering but does not exclude results. Default: no preference. |
The RSS Sync subsection (at the bottom of the Search section) controls the RSS poller:
| Setting | Description |
|---|
| Enable RSS Sync | Toggle RSS sync on/off. Default: off. |
| RSS Interval | Poll frequency in minutes. Range: 5–1440. Default: 30. |
See RSS Feeds for details.
| Setting | Description |
|---|
| Region | Audible region used for metadata lookups (cover art, descriptions, narrators). Options: us, ca, uk, au, fr, de, jp, it, in, es. Default: us. |
| Hardcover API Key | Optional key that populates the Series card on book pages with Hardcover-canonical members. Without a key, Series cards show only library books sharing the series name. Has a Test button to validate the key. |
Gates which search results survive before quality evaluation.
| Setting | Description |
|---|
| Languages | Multi-select of languages to allow. Results in unselected languages are excluded; results with no detected language always pass through. Default: English. Deselect all to disable language filtering. |
| Minimum Duration | Minimum runtime (in minutes) a release must have. Filters promo excerpts, TTS knockoffs, and supplementary clips. Default: 30. Set to 0 to disable. |
| Reject Words | Comma-separated words that exclude a result if matched against its release (NZB) name, raw title, title, author, or narrator. Default: Virtual Voice, Free Excerpt, Sample, Behind the Scenes, Abridged. |
| Required Words | Comma-separated words — at least one must appear in a result’s release name, raw title, title, author, or narrator for it to be kept. |
Controls the minimum bar a release must clear to be eligible to grab. See Quality Gates for full details.
| Setting | Description |
|---|
| MB/hr Grab Minimum | Minimum quality in MB/hour. Releases below this are hidden. Default: 0 (disabled). |
| Minimum Seeders | Minimum seeders for torrent releases (does not affect Usenet). Default: 1. Set to 0 to disable. |
| Min Download Size | Minimum download size in MB. Filters tracker-test uploads, single-track previews, and corrupt releases. Default: 50. Set to 0 to disable. |
| Max Download Size | Maximum download size in GB. Larger releases are hidden. Default: 5. Set to 0 to disable. |
The Audio Tools tab holds the Merge & Convert section — the engine settings applied wherever audio is merged or converted: the per-book Merge button, bulk Convert, and auto-merge downloads.
Audio processing requires ffmpeg, but there is no path to configure — Narratorr auto-detects the binary (the FFMPEG_PATH environment variable if set, then /usr/bin/ffmpeg, then the system PATH) and shows the result in a status row at the top of the tab, including the detected version and path. In Docker, ffmpeg is pre-installed and always found. For manual installs, install ffmpeg on the system PATH, or point the FFMPEG_PATH environment variable at the binary. There is no master on/off toggle either — merge, convert, and Tag Embedding simply stay off until ffmpeg is detected.
| Setting | Description |
|---|
| Output Format | Target format: m4b or mp3. Default: m4b. (MP3 does not support embedded chapter markers.) |
| Target Bitrate | Target bitrate in kbps (32–512). Default: 128. Ignored when “Keep original” is on. |
| Keep original | When on, the source file’s bitrate is used instead of the target. Note: files are still re-encoded — this drops the bitrate cap, it is not a lossless copy. Default: on. |
| Merge Behavior | When to merge multi-file downloads into a single chaptered file: always, multi-file-only, or never. Default: multi-file-only. |
| Max Concurrent Jobs | Maximum number of merge jobs that can run simultaneously — manual and automatic merges share this cap. Range: 1–8. Default: 1. |
The Post Processing tab holds the automations that run on their own after a download lands — none run on Library Import or Manual Import. Merge and convert are manual by default (per-book Merge or bulk Convert), but the Auto-merge multi-file downloads toggle opts completed downloads into an automatic merge after import, using the Merge & Convert settings from the Audio Tools tab.
| Setting | Description |
|---|
| Auto-merge multi-file downloads | Automatically merge a completed download’s audio files into a single file once it lands in the library. Applies to downloads only — never Library Import or Manual Import. Default: off. |
| Post-Processing Script | Absolute path to a custom script run after each successful import. See Features Reference. |
| Script Timeout | Maximum script execution time in seconds. Required when a script is set. Default: 300. |
Tagging is nested within this same tab as the Tag Embedding toggle, rather than a separate top-level section:
| Setting | Description |
|---|
| Tag Embedding | Write book metadata into audio file tags on import. Requires ffmpeg. Default: off. |
| Tag Mode | populate_missing (only fill empty fields) or overwrite (replace all). Default: populate_missing. |
| Embed Cover Art | Embed cover art into audio files. Default: off. |
| OPF Metadata Sidecar | Write a metadata.opf file into each book folder so media servers (Audiobookshelf especially) can read narratorr’s metadata. Works independently of Tag Embedding — no ffmpeg needed. Default: off. See Tagging & Cover Art. |
See Audio Processing and Tagging & Cover Art for more detail.
The System tab holds the health dashboard, the Backup Schedule and Backup & Restore sections, system info, the Housekeeping and Logging sections, scheduled tasks, and the Licenses & Third-Party Notices section — attribution and license texts for the FFmpeg binary bundled in the Docker image.
| Setting | Section | Description |
|---|
| Backup Interval | Backup Schedule | Minutes between automatic backups. Range: 60–43,200. Default: 10,080 (weekly). |
| Backup Retention | Backup Schedule | Number of backups to keep. Range: 1–100. Default: 7. |
| Event History Retention | Housekeeping | How many days to keep event history entries before pruning. Range: 1–365. Default: 90. |
| Log Level | Logging | How verbose Narratorr’s logs are. Options: error, warn, info, debug, trace. Default: info. Turn up to debug when troubleshooting. |
See Backup & Restore for details.
