¶ Table of Contents
- Table of Contents
- Quick Start Setup Guide
- Startup
- Media Management
- Book Naming
- Folders
- Importing
- File Management
- Root Folders and Calibre Integration
- Download Clients
- How to import your existing organized media library
- Add New Books
¶ Quick Start Setup Guide
This page is still in progress and not complete. Contributions are welcome
For a more detailed breakdown of all the settings, check Readarr =>Settings
In this guide we will try to explain the basic setup you need to do to get started with Readarr. We're going to skip some options that you may see on the screen. If you want to dive deeper into those, please see the appropriate page in the FAQ and docs for a full explanation.
Please note that within the screenshots and GUI settings in
orangeare advanced options, so you will need to clickShow Advancedat the top of the page to make them visible.
¶ Startup
After installation and starting up, you open a browser and go to http://{your_ip_here}:8787
¶ Media Management
First we’re going to take a look at the Media Management settings where we can setup our preferred naming and file management settings.
Settings => Media Management
¶ Book Naming
- Enable/Disable Renaming of your books (as opposed to leaving the names that are currently there or as they were when you downloaded them).
- If you want illegal characters replaced or removed (
\ / : * ? " < > | ~ - % & + { }). - Here you will select the naming convention for the actual book files. Note that the Book folder name is defined here as well.
(Advanced Option) This is where you will set the naming convention for the Author folder.
This does not apply if Calibre is used as Calibre handles file/folder naming using its own internal schema.
¶ Folders
- (Advanced Option) Create Empty Author Folders - Enable to create empty author folders when a new author is added to Readarr.
- (Advanced Option) Delete Empty Folders - Enable to delete empty author folders when there are no remaining books for that author.
One of those boxes can be checked, but they should not BOTH be checked.
This does not apply if Calibre is used as Calibre handles file/folder naming using its own internal schema.
¶ Importing
- (Advanced Option) Skip Free Space Check - If enabled skip checking free space prior to importing
- (Advanced Option) Minimum Free Space - Enter the minimum free space for the drive to have before importing stops.
- (Advanced Option) Use Hard links instead of Copy - Check this box to use Hard links instead of Copies (for Torrents). Note that this is enabled by default.
You should ideally use this wherever possible. In order for hard links to be used, you must have your source/destination on the same file system (drive, partition) and mount points. See TRaSH's Hardlink Guide for more information
- Import Extra Files - If enabled import specified extra files located within the folder of the book when its imported
- (Advanced Option) Import Extra Files - If Import Extra Files is enabled enter a comma separated list of extensions to import.
If you are using Readarr for audiobooks, you should add .cue to this list, as it holds your chapter information!
¶ File Management
-
Books deleted from disk are automatically unmonitored in Readarr.
-
Ignore Deleted Books - Check this box to unmonitor books detected as deleted or inaccessible from Readarr's root folder.
-
Download Proper & Repacks - Whether or not to automatically upgrade to Propers/Repacks. Use
Do not Preferto sort by preferred word score over propers/repacks- Prefer and Upgrade - Rank repacks and propers higher than non-repacks and non-propers. Treat new repacks and propers as upgrade to current releases.
- Do Not Upgrade Automatically - Rank repacks and propers higher than non-repacks and non-propers. Do not treat new repacks and propers as upgrade to current releases.
- Do Not Prefer - Effectively this ignores repacks and propers. You'll need to manage any preference for those with Preferred Words.
*
PROPER- means there was a problem with the previous release. Downloads tagged as PROPER shows that the problems have been fixed in that release. This is done by a Group that did not release the original.
*REPACK- means there was a problem with the previous release and is corrected by the original Group. Downloads tagged as REPACK shows that the problems have been fixed in that release. This is done by a Group that did release the original.
- (Advanced Option) Watch Root Folders for file changes - Check this box to trigger a rescan when it is detected that the root folder had changes.
- (Advanced Option) Rescan Author Folder after Refresh - Choose when to rescan an author folder after refreshing the author.
- Always - This will rescan author folders based upon Tasks Schedule
- After Manual Refresh - You will have to manually rescan the disk
- Never - Just as it says, never rescan the author folders.
- (Advanced Option) Allow Fingerprinting - Choose how to handle fingerprinting, which allows increased accuracy for book matching, at the expense of CPU/disk time.
- Always - Always use fingerprinting if possible
- For new imports only - Only fingerprint newly imported releases
- Never - Just as it says, never use fingerprinting
- (Advanced Option) Change File Date - Change file date on import/rescan
- None - Readarr will not change the date that shows in your given file browser
- Book Release Date - The date the book was released.
- (Advanced Option) Recycling Bin - Book files will go here when deleted instead of being permanently deleted
- (Advanced Option) Recycling Bin Cleanup - This is how old a given file can be before it is deleted permanently
It is highly recommended that you use a Recycling Bin. It's easy to delete files, and recovering them is easy if you use the bin.
¶ Root Folders and Calibre Integration
Here we will add the root folder that Readarr will be using to import your existing organized media library and where Readarr will be importing (copy/hardlink/move) your media after your download client has downloaded it.
The user and group you configured Readarr to run as must have read & write access to this location.
You may also elect to use Calibre to manage your library on this screen. Doing so will require you to run the Calibre Content Server. This is NOT Calibre-Web.
Non-Windows Users:
* If you're using an NFS mount ensurenolockis enabled.
* If you're using an SMB mount ensurenobrlis enabled.
If you are going to use Calibre, the books you want to have Readarr recognize on initial library import must already be in Calibre. Books within the folder and not in Calibre will be ignored. Hard links are not used when adding Calibre integration.
Note that you cannot add Calibre integration to a root folder after it's created.
Your download client downloads to a download folder, and Readarr imports it to your media folder (final destination) that your media server uses. Your download folder and media folder can’t be the same location!
Don’t forget to save your changes.
¶ Calibre Content Server (Optional)
If you are going to use Calibre to manage your books, you need to set up the Calibre Content Server. Again, this is not Calibre-Web, but a piece of Calibre itself. You must be running Calibre, and you must set up the Content Server.
If you choose to use Calibre - you cannot change anything in Calibre's database. Failure to heed this warning will result in you needing to deleting your Readarr database and starting over
If you're using docker, your Calibre mounted book directory and your Readarr mounted book directory must be the same.
Please note that while Readarr is in beta; if you use Calibre it is recommended to disable Renaming in Readarr just in case an unintended bug slips through.
To do this, open Calibre, and click Preferences / Sharing over the net
First, add a user account. The account DOES need "make changes" access.
Then you will need to restart Calibre. Once back in, configure and start up the content server. It should show you that it's running. Set it to run automatically on startup. After saving, you will again need to restart Calibre. Make sure the sever is started when it comes back up, then you can move to the next section.
You must select "Require username and password to access the content server" in order for Readarr to properly work. If you do not, you will get an error that says "Anonymous users are not allowed to make changes" when Readarr import a book!
¶ Calibre Integration
The below are Calibre Specific Settings and only display if Use Calibre is enabled
- Use Calibre - Enable / Disable the use of Calibre Content Server to manage your Root Folder.
* Only for use with ebooks, cannot be used for audiobooks!
* Note that this cannot be enabled on an existing root folder.
* Note that this cannot be disabled on an existing Calibre enabled root folder.
* Note that this requires Calibre Content Server and will not work with Calibre Web nor Calibre.
* Note that hard links do not work with Calibre integration.
* Note that this requires that Calibre to haveRequire username and password to access the content serverto be enabled.
* Failure to haveRequire username and password to access the content serverenabled in Calibre will result in an error ofAnonymous users are not allowed to make changes
There was a change in Calibre 7.2.0 which starts listening on ipv6, and it can cause a problem with readarr connections. To fix it, change the Calibre setting "The interface to listen for connections" to 0.0.0.0 in Preferences->Sharing over the net->Advanced, in calibre, and restart calibre. This should resolve the issue.
If you choose to use Calibre - you cannot change anything in Calibre's database. Failure to heed this warning will result in you needing to deleting your Readarr database and starting over. You cannot add books, delete books, re-tag books, or convert books inside Calibre. This includes updating the metadata.
- Calibre Host - The IP/domain of the host of the Calibre Content Server
- Calibre Port - The Port that Calibre Content Server is listening on
- (Advanced) Calibre URL Base - Add a prefix to the Calibre URL e.g.
http://[host]:[port]/[urlBase] - Calibre Username - Username to use to access Calibre Content Server
- Calibre Password - Password to use to access Calibre Content Server
- Calibre Library - Calibre Content Server library name. Leave blank for default
- Convert to Format - (Optional) Ask Calibre Content Server to convert to other formats with a comma separated list.
- Review the (i) icon within the app for a current list of options.
- Options are: MOBI, EPUB, AZW3, DOCX, FB2, HTMLZ, LIT, LRF, PDB, PDF, PMLZ, RB, RTF, SNB, TCR, TXT, TXTZ, ZIP
- Calibre Output Profile - Select the Calibre Content Server Output Profile to use
- The output profile tells the Calibre Content Server conversion system how to optimize the created document for the specified device (such as by resizing images for the device screen size). In some cases, an output profile can be used to optimize the output for a particular device, but this is rarely necessary.
- Use SSL - Enable or Disable the use of SSL (HTTPS) for Calibre Content Server
If you add an individual book, and select
None* for the metadata profile, only that book will show up under the author when it's added. If you want other books for that author added, choose an appropriate metadata profile.
* Note thatNonedoes not apply any metadata filters and you may get unwanted foreign editions. To work around these create a metadata profile as prescribed in the faq
¶ Download Clients
Settings => Download Clients
Downloading and importing is where most people experience issues. From a high level perspective, the software needs to be able to communicate with your download client and have access to the files it downloads. There is a large variety of supported download clients and an even bigger variety of setups. This means that while there are some common setups there isn’t one right setup and everyone’s setup can be a little different. But there are many wrong setups.
See the settings page, at the More Info (Supported) page for this section, and TRaSH's Download Client Guides for more information.
- Readarr will send a download request to your client, and associate it with a label or category name that you have configured in the download client settings.
- Examples: movies, tv, series, music, etc.
- Readarr will monitor your download clients active downloads that use that category name. It monitors this via your download client's API.
- When the download is completed, Readarr will know the final file location as reported by your download client. This file location can be almost anywhere, as long as it is somewhere separate from your media folder and accessible by Readarr
- Readarr will scan that completed file location for files that Readarr can use. It will parse the file name to match it against the requested media. If it can do that, it will rename the file according to your specifications, and move it to the specified media location.
- Atomic Moves (instant moves) are enabled by default. The file system and mounts must be the same for your completed download directory and your media library. If the the atomic move fails or your setup does not support hard links and atomic moves then Readarr will fall back and copy the file then delete from the source which is IO intensive.
- If the "Completed Download Handling - Remove" option is enabled in Readarr's settings leftover files from the download will be sent to your trash or recycling via a request to your client to delete/remove the release.
- Readarr will send a download request to your client, and associate it with a label or category name that you have configured in the download client settings.
- Examples: movies, tv, series, music, etc.
- Readarr will monitor your download clients active downloads that use that category name. This monitoring occurs via your download client's API.
- Completed files are left in their original location to allow you to seed the file (ratio or time can be adjusted in the download client or from within Readarr under the specific download client). When files are imported to your media folder Readarr will hardlinkthe file if supported by your setup or copy if not hard links are not supported.
- Hard links are enabled by default. A hard link will allow not use any additional disk space. The file system and mounts must be the same for your completed download directory and your media library. If the hard link creation fails or your setup does not support hard links then Readarr will fall back and copy the file.
- If the "Completed Download Handling - Remove" option is enabled in Readarr's settings, Readarr will delete the torrent from your client and ask the client to remove the torrent data, but only if the client reports that seeding is complete and torrent is stopped (paused on completion).
¶ How to import your existing organized media library
Note that Readarr does not regularly search for Books. See these two FAQ Entries for details to understand how Readarr works.
How does Readarr find books? and How does Readarr work?
After setting up your profiles/quality sizes and added your indexers and download client(s) it’s time to import your existing organized media library.
Coming soon - Contributions Welcome
¶ Importing Existing Media
Coming soon - Contributions Welcome