Skip to content

Commit 8daefb7

Browse files
Admin9705Admin9705
committed
initial push
1 parent 012cd94 commit 8daefb7

File tree

10 files changed

+965
-1
lines changed

10 files changed

+965
-1
lines changed

‎README.md‎

Lines changed: 322 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,322 @@
1-
TEST
1+
# Huntarr [Readarr Edition] - Force Readarr to Hunt Missing Books & Upgrade Book Qualities
2+
3+
<h2 align="center">Want to Help? Click the Star in the Upper-Right Corner! ⭐</h2>
4+
5+
<table>
6+
<tr>
7+
<td colspan="2"><img src="https://github.com/user-attachments/assets/3ea6d2a0-19fd-4e7c-9dfd-797e735b2955" width="100%"/></td>
8+
</tr>
9+
</table>
10+
11+
**NOTE**: This utilizes Readarr API Version - `1`.
12+
13+
## Table of Contents
14+
- [Overview](#overview)
15+
- [Related Projects](#related-projects)
16+
- [Features](#features)
17+
- [How It Works](#how-it-works)
18+
- [Configuration Options](#configuration-options)
19+
- [Installation Methods](#installation-methods)
20+
- [Docker Run](#docker-run)
21+
- [Docker Compose](#docker-compose)
22+
- [Unraid Users](#unraid-users)
23+
- [SystemD Service](#systemd-service)
24+
- [Use Cases](#use-cases)
25+
- [Tips](#tips)
26+
- [Troubleshooting](#troubleshooting)
27+
28+
## Overview
29+
30+
This script continually searches your Readarr library for books with missing files and books that need quality upgrades. It automatically triggers searches for both missing books and books below your quality cutoff. It's designed to run continuously while being gentle on your indexers, helping you gradually complete your book collection with the best available quality.
31+
32+
## Related Projects
33+
34+
* [Huntarr - Sonarr Edition](https://github.com/plexguide/Huntarr-Sonarr) - Sister version for TV shows
35+
* [Huntarr - Radarr Edition](https://github.com/plexguide/Huntarr-Radarr) - Sister version for movies
36+
* [Huntarr - Lidarr Edition](https://github.com/plexguide/Huntarr-Lidarr) - Sister version for music
37+
* [Unraid Intel ARC Deployment](https://github.com/plexguide/Unraid_Intel-ARC_Deployment) - Convert videos to AV1 Format (I've saved 325TB encoding to AV1)
38+
* Visit [PlexGuide](https://plexguide.com) for more great scripts
39+
40+
## PayPal Donations – Building My Daughter's Future
41+
42+
My 12-year-old daughter is passionate about singing, dancing, and exploring STEM. She consistently earns A-B honors and dreams of a bright future. Every donation goes directly into her college fund, helping turn those dreams into reality. Thank you for your generous support!
43+
44+
[![Donate with PayPal button](https://www.paypalobjects.com/en_US/i/btn/btn_donate_LG.gif)](https://www.paypal.com/donate?hosted_button_id=58AYJ68VVMGSC)
45+
46+
## Features
47+
48+
- 🔄 **Continuous Operation**: Runs indefinitely until manually stopped
49+
- 🎯 **Dual Targeting System**: Targets both missing books and quality upgrades
50+
- 🎲 **Random Selection**: By default, selects books randomly to distribute searches across your library
51+
- ⏱️ **Throttled Searches**: Includes configurable delays to prevent overloading indexers
52+
- 📊 **Status Reporting**: Provides clear feedback about what it's doing and which books it's searching for
53+
- 🛡️ **Error Handling**: Gracefully handles connection issues and API failures
54+
- 🔁 **State Tracking**: Remembers which books have been processed to avoid duplicate searches
55+
- ⚙️ **Configurable Reset Timer**: Automatically resets search history after a configurable period
56+
- 📦 **Modular Design**: Modern codebase with separated concerns for easier maintenance
57+
- ⏲️ **Configurable Timeouts**: Adjustable API timeout for large libraries
58+
- 🗓️ **Future Release Filtering**: Option to skip books with future release dates
59+
- 👩‍💼 **Author Metadata Refresh**: Option to refresh author metadata before processing books
60+
61+
## How It Works
62+
63+
1. **Initialization**: Connects to your Readarr instance and analyzes your library
64+
2. **Missing Books**:
65+
- Identifies books without files
66+
- Optionally filters out future releases
67+
- Randomly selects books to process (up to configurable limit)
68+
- Refreshes metadata and triggers searches
69+
3. **Quality Upgrades**:
70+
- Finds books that don't meet your quality cutoff settings
71+
- Processes them in configurable batches
72+
- Uses smart selection to distribute searches
73+
4. **State Management**:
74+
- Tracks which books have been processed
75+
- Automatically resets this tracking after a configurable time period
76+
5. **Repeat Cycle**: Waits for a configurable period before starting the next cycle
77+
78+
## Configuration Options
79+
80+
The following environment variables can be configured:
81+
82+
| Variable | Description | Default |
83+
|------------------------------|-----------------------------------------------------------------------|---------------|
84+
| `API_KEY` | Your Readarr API key | Required |
85+
| `API_URL` | URL to your Readarr instance | Required |
86+
| `API_TIMEOUT` | Timeout in seconds for API requests to Readarr | 60 |
87+
| `MONITORED_ONLY` | Only process monitored books | true |
88+
| `SKIP_FUTURE_RELEASES` | Skip processing books with release dates in the future | true |
89+
| `HUNT_MISSING_BOOKS` | Maximum missing books to process per cycle | 1 |
90+
| `HUNT_UPGRADE_BOOKS` | Maximum upgrade books to process per cycle | 5 |
91+
| `SLEEP_DURATION` | Seconds to wait after completing a cycle (900 = 15 minutes) | 900 |
92+
| `RANDOM_SELECTION` | Use random selection (`true`) or sequential (`false`) | true |
93+
| `STATE_RESET_INTERVAL_HOURS` | Hours which the processed state files reset (168=1 week, 0=never reset) | 168 |
94+
| `REFRESH_AUTHOR` | Refresh author metadata before processing book (`true` or `false`) | true |
95+
| `DEBUG_MODE` | Enable detailed debug logging (`true` or `false`) | false |
96+
97+
### Detailed Configuration Explanation
98+
99+
- **API_TIMEOUT**
100+
- Sets the maximum number of seconds to wait for Readarr API responses before timing out.
101+
- This is particularly important when working with large libraries.
102+
- If you experience timeout errors, increase this value.
103+
- For libraries with thousands of books, values of 90-120 seconds may be necessary.
104+
- Default is 60 seconds, which works well for most medium-sized libraries.
105+
106+
- **SKIP_FUTURE_RELEASES**
107+
- When set to `true`, books with release dates in the future will be skipped during missing book processing.
108+
- This prevents searching for content that isn't yet available.
109+
- Set to `false` if you want to process all missing books regardless of release date.
110+
111+
- **HUNT_MISSING_BOOKS**
112+
- Sets the maximum number of missing books to process in each cycle.
113+
- Once this limit is reached, the script stops processing further missing books until the next cycle.
114+
- Set to `0` to disable missing book processing completely.
115+
116+
- **HUNT_UPGRADE_BOOKS**
117+
- Sets the maximum number of upgrade books to process in each cycle.
118+
- When this limit is reached, the upgrade portion of the cycle stops.
119+
- Set to `0` to disable quality upgrade processing completely.
120+
121+
- **RANDOM_SELECTION**
122+
- When `true`, selects books randomly, which helps distribute searches across your library.
123+
- When `false`, processes books sequentially, which can be more predictable and methodical.
124+
125+
- **STATE_RESET_INTERVAL_HOURS**
126+
- Controls how often the script "forgets" which books it has already processed.
127+
- The script records the IDs of missing books and upgrade books that have been processed.
128+
- When the age of these records exceeds the number of hours set by this variable, the records are cleared automatically.
129+
- This reset allows the script to re-check books that were previously processed, so if there are changes (such as improved quality), they can be processed again.
130+
- Setting this to `0` will disable the reset functionality entirely - processed items will be remembered indefinitely.
131+
- Default is 168 hours (one week) - meaning the script will start fresh weekly.
132+
133+
- **REFRESH_AUTHOR**
134+
- When set to `true`, the script will refresh author metadata before processing a book.
135+
- This can help ensure that all book information is up-to-date before searching.
136+
- Particularly useful if you've recently added new authors or if you suspect metadata may be out of date.
137+
- Set to `false` to skip this step and potentially speed up processing.
138+
139+
- **DEBUG_MODE**
140+
- When set to `true`, the script will output detailed debugging information about API responses and internal operations.
141+
- Useful for troubleshooting issues but can make logs verbose.
142+
143+
---
144+
145+
## Installation Methods
146+
147+
### Docker Run
148+
149+
The simplest way to run Huntarr is via Docker:
150+
151+
```bash
152+
docker run -d --name huntarr-readarr \
153+
--restart always \
154+
-e API_KEY="your-api-key" \
155+
-e API_URL="http://your-readarr-address:8787" \
156+
-e API_TIMEOUT="60" \
157+
-e MONITORED_ONLY="true" \
158+
-e SKIP_FUTURE_RELEASES="true" \
159+
-e HUNT_MISSING_BOOKS="1" \
160+
-e HUNT_UPGRADE_BOOKS="5" \
161+
-e SLEEP_DURATION="900" \
162+
-e RANDOM_SELECTION="true" \
163+
-e REFRESH_AUTHOR="true" \
164+
-e STATE_RESET_INTERVAL_HOURS="168" \
165+
-e DEBUG_MODE="false" \
166+
huntarr/huntarr-readarr:1.0
167+
```
168+
169+
To check on the status of the program, you should see new files downloading or you can type:
170+
```bash
171+
docker logs huntarr-readarr
172+
```
173+
174+
### Docker Compose
175+
176+
For those who prefer Docker Compose, add this to your `docker-compose.yml` file:
177+
178+
```yaml
179+
version: "3.8"
180+
services:
181+
huntarr-readarr:
182+
image: huntarr/huntarr-readarr:1.0
183+
container_name: huntarr-readarr
184+
restart: always
185+
environment:
186+
API_KEY: "your-api-key"
187+
API_URL: "http://your-readarr-address:8787"
188+
API_TIMEOUT: "60"
189+
MONITORED_ONLY: "true"
190+
SKIP_FUTURE_RELEASES: "true"
191+
HUNT_MISSING_BOOKS: "1"
192+
HUNT_UPGRADE_BOOKS: "5"
193+
SLEEP_DURATION: "900"
194+
RANDOM_SELECTION: "true"
195+
REFRESH_AUTHOR: "true"
196+
STATE_RESET_INTERVAL_HOURS: "168"
197+
DEBUG_MODE: "false"
198+
```
199+
200+
Then run:
201+
202+
```bash
203+
docker-compose up -d huntarr-readarr
204+
```
205+
206+
To check on the status of the program, you should see new files downloading or you can type:
207+
```bash
208+
docker logs huntarr-readarr
209+
```
210+
211+
### Unraid Users
212+
213+
Run from the Unraid Command Line. This will eventually be submitted to the Unraid App Store:
214+
215+
```bash
216+
docker run -d --name huntarr-readarr \
217+
--restart always \
218+
-e API_KEY="your-api-key" \
219+
-e API_URL="http://your-readarr-address:8787" \
220+
-e API_TIMEOUT="60" \
221+
-e MONITORED_ONLY="true" \
222+
-e SKIP_FUTURE_RELEASES="true" \
223+
-e HUNT_MISSING_BOOKS="1" \
224+
-e HUNT_UPGRADE_BOOKS="5" \
225+
-e SLEEP_DURATION="900" \
226+
-e RANDOM_SELECTION="true" \
227+
-e REFRESH_AUTHOR="true" \
228+
-e STATE_RESET_INTERVAL_HOURS="168" \
229+
-e DEBUG_MODE="false" \
230+
huntarr/huntarr-readarr:1.0
231+
```
232+
233+
### SystemD Service
234+
235+
For a more permanent installation on Linux systems using SystemD:
236+
237+
1. Save the script to `/usr/local/bin/huntarr-readarr.sh`
238+
2. Make it executable: `chmod +x /usr/local/bin/huntarr-readarr.sh`
239+
3. Create a systemd service file at `/etc/systemd/system/huntarr-readarr.service`:
240+
241+
```ini
242+
[Unit]
243+
Description=Huntarr Readarr Service
244+
After=network.target readarr.service
245+
246+
[Service]
247+
Type=simple
248+
User=your-username
249+
Environment="API_KEY=your-api-key"
250+
Environment="API_URL=http://localhost:8787"
251+
Environment="API_TIMEOUT=60"
252+
Environment="MONITORED_ONLY=true"
253+
Environment="SKIP_FUTURE_RELEASES=true"
254+
Environment="HUNT_MISSING_BOOKS=1"
255+
Environment="HUNT_UPGRADE_BOOKS=5"
256+
Environment="SLEEP_DURATION=900"
257+
Environment="RANDOM_SELECTION=true"
258+
Environment="REFRESH_AUTHOR=true"
259+
Environment="STATE_RESET_INTERVAL_HOURS=168"
260+
Environment="DEBUG_MODE=false"
261+
ExecStart=/usr/local/bin/huntarr-readarr.sh
262+
Restart=on-failure
263+
RestartSec=10
264+
265+
[Install]
266+
WantedBy=multi-user.target
267+
```
268+
269+
4. Enable and start the service:
270+
271+
```bash
272+
sudo systemctl enable huntarr-readarr
273+
sudo systemctl start huntarr-readarr
274+
```
275+
276+
## Use Cases
277+
278+
- **Library Completion**: Gradually fill in missing books in your collection
279+
- **Quality Improvement**: Automatically upgrade book quality as better versions become available
280+
- **New Book Setup**: Automatically find newly added books
281+
- **Background Service**: Run it in the background to continuously maintain your library
282+
- **Smart Rotation**: With state tracking, ensures all content gets attention over time
283+
- **Large Library Management**: With optimized performance and configurable timeouts, handles even the largest libraries
284+
- **Release Date Awareness**: Skip books that aren't released yet, focusing only on currently available content
285+
- **Author Management**: Refreshes author metadata to ensure all book data is up-to-date
286+
287+
## Tips
288+
289+
- **First-Time Use**: Start with default settings to ensure it works with your setup
290+
- **Adjusting Speed**: Lower the `SLEEP_DURATION` to search more frequently (be careful with indexer limits)
291+
- **Batch Size Control**: Adjust `HUNT_MISSING_BOOKS` and `HUNT_UPGRADE_BOOKS` based on your indexer's rate limits
292+
- **Monitored Status**: Set `MONITORED_ONLY=false` if you want to download all missing books regardless of monitored status
293+
- **System Resources**: The script uses minimal resources and can run continuously on even low-powered systems
294+
- **Debugging Issues**: Enable `DEBUG_MODE=true` temporarily to see detailed logs when troubleshooting
295+
- **API Timeouts**: If you have a large library, increase the `API_TIMEOUT` value to 90-120 seconds to prevent timeout errors
296+
- **Future Releases**: Use `SKIP_FUTURE_RELEASES=true` to avoid searching for books not yet released
297+
- **Author Metadata**: If you notice that book information is incomplete, set `REFRESH_AUTHOR=true` to refresh author metadata
298+
299+
## Troubleshooting
300+
301+
- **API Key Issues**: Check that your API key is correct in Readarr settings
302+
- **Connection Problems**: Ensure the Readarr URL is accessible from where you're running the script
303+
- **Command Failures**: If search commands fail, try using the Readarr UI to verify what commands are available in your version
304+
- **Logs**: Check the container logs with `docker logs huntarr-readarr` if running in Docker
305+
- **Debug Mode**: Enable `DEBUG_MODE=true` to see detailed API responses and process flow
306+
- **State Files**: The script stores state in `/tmp/huntarr-state/` - if something seems stuck, you can try deleting these files
307+
- **Timeout Errors**: If you see "Read timed out" errors, increase the `API_TIMEOUT` value to give Readarr more time to respond
308+
309+
---
310+
311+
**Change Log:**
312+
- **v1**: Initial release of Huntarr [Readarr Edition] based on the Radarr version
313+
314+
---
315+
316+
This script helps automate the tedious process of finding missing books and quality upgrades in your collection, running quietly in the background while respecting your indexers' rate limits.
317+
318+
---
319+
320+
Thanks to:
321+
322+
[IntensiveCareCub](https://www.reddit.com/user/IntensiveCareCub/) for the Hunter to Huntarr idea!

0 commit comments

Comments
 (0)