Narratorr’s settings are organized into sections, accessible from Settings in the sidebar. This page gives an overview of each section. Individual topics have dedicated pages linked below.
| Setting | Description |
|---|
| Log Level | Controls how verbose Narratorr’s logs are. Options: error, warn, info, debug. Default: info. Turn up to debug when troubleshooting. |
| Event Retention | How many days to keep event history entries. Range: 1–365. Default: 90. |
| Recycle Retention | Days before recycling bin entries are auto-purged. Range: 0–365. Default: 30. Set to 0 to disable auto-cleanup. See Recycling Bin. |
| Setting | Description |
|---|
| Audible Region | Region used for metadata lookups (cover art, descriptions). Options: us, ca, uk, au, fr, de, jp, it, in, es. Default: us. Can also be set via the AUDIBLE_REGION environment variable. |
| Setting | Description |
|---|
| Library Path | Root directory where Narratorr stores your audiobooks. In Docker, this maps to /audiobooks. |
| 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 |
|---|
| Enabled | Toggle automatic searching on/off. |
| Interval | How often (in minutes) Narratorr searches for missing books. Range: 5–1440. Default: 360 (6 hours). |
| Blacklist TTL | How many days temporary blacklist entries last. Range: 1–365. Default: 7. See Blacklist. |
Controls which releases are eligible to grab and how downloads are evaluated. See Quality Gates for full details.
| Setting | Description |
|---|
| Grab Floor | Minimum quality in MB/hour. Default: 0 (disabled). |
| Protocol Preference | Prefer usenet, torrent, or none. Default: none. |
| Min Seeders | Minimum seeders for torrent releases. Default: 0. |
| Reject Words | Comma-separated words to exclude from results. |
| Required Words | Comma-separated words — at least one must appear. |
| Search Immediately | Immediately search when adding a new book. Default: off. |
| Monitor for Upgrades | Auto-enable upgrade monitoring for new books. Default: off. |
| Setting | Description |
|---|
| Proxy URL | HTTP/HTTPS/SOCKS5 proxy for outbound requests. See Network & Proxy. |
| Setting | Description |
|---|
| Delete After Import | Remove the downloaded files from the download client after successful import. |
| Minimum Seed Time | For torrents: minimum time (in minutes) a torrent must seed before Narratorr will import it. Prevents premature removal from swarms. |
| Minimum Free Space | Minimum free disk space (in GB) required before importing. Default: 5. Import is skipped if disk is below this threshold. |
| Max Concurrent Processing | Maximum number of imports running simultaneously. Default: 2. |
Audio processing requires ffmpeg. In Docker, ffmpeg is pre-installed. For manual installs, install ffmpeg and configure its path.
| Setting | Description |
|---|
| Enabled | Toggle audio processing on/off. |
| ffmpeg Path | Path to the ffmpeg binary. Auto-detected in Docker. |
| Output Format | Target format: m4b or mp3. |
| Keep Original Bitrate | When enabled, the target bitrate setting is ignored and the source file’s bitrate is retained. |
| Bitrate | Target bitrate in kbps (32–512). Default: 128. Ignored when keep original bitrate is enabled. |
| Merge Behavior | When to merge multi-file downloads: always, multi-file-only, or never. |
| Post-Processing Script | Custom script to run after each import. See Features Reference. |
| Script Timeout | Maximum execution time in seconds. Default: 300. |
See Audio Processing for more detail.
| Setting | Description |
|---|
| Enabled | Toggle tag writing on/off. |
| Mode | populate_missing (only fill empty fields) or overwrite (replace all). Default: populate_missing. |
| Embed Cover | Embed cover art into audio files. Default: off. |
See Tagging & Cover Art for details.
| Setting | Description |
|---|
| Enabled | Toggle RSS sync on/off. Default: off. |
| Interval | Poll frequency in minutes. Range: 5–1440. Default: 30. |
See RSS Feeds for details.
| Setting | Description |
|---|
| Enabled | Toggle discovery engine on/off. Default: off. |
| Interval | Refresh frequency in hours. Range: 1–168. Default: 24. |
| Max Per Author | Maximum suggestions per author. Range: 1–50. Default: 5. |
| Expiry Days | Days before unused suggestions expire. Default: 90. |
| Snooze Days | Days a snoozed suggestion stays hidden. Default: 30. |
| Weight Multipliers | Per-category weights (author, series, genre, narrator, diversity). 0–1. Default: 1 for all. |
See Discovery & Recommendations for details.
| Setting | Description |
|---|
| Backup Interval | Minutes between automatic backups. Range: 60–43,200. Default: 10,080 (weekly). |
| Backup Retention | Number of backups to keep. Range: 1–100. Default: 7. |
| Dismissed Update Version | Version string to suppress the update notification for. |
See Backup & Restore for details.
