Repository files navigation

NOTE: This utilizes Lidarr API Version -1. Legacy Name of this Program: Lidarr Hunter.

• Overview
• Related Projects
• Features
• How It Works
• Configuration Options
• Installation Methods
  • Docker Run
  • Docker Compose
  • Unraid Users
  • SystemD Service
• Use Cases
• Tips
• Troubleshooting

This script continually searches your Lidarr library for missing music (artists/albums) and music that needs quality upgrades. It automatically triggers searches for both missing content and albums below your quality cutoff. It's designed to run continuously while being gentle on your indexers, helping you gradually complete your music collection with the best available quality.

• Huntarr - Sonarr Edition - Sister version for TV Shows
• Huntarr - Radarr Edition - Sister version for Movies
• Huntarr - Readarr Edition - Sister version for Books
• Unraid Intel ARC Deployment - Convert videos to AV1 Format (I've saved 325TB encoding to AV1)
• VisitPlexGuide for more great scripts

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!

• 🔄Continuous Operation: Runs indefinitely until manually stopped
• 🎯Dual Targeting System: Targets both missing music and quality upgrades
• 🎲Random Selection: By default, selects music randomly to distribute searches across your library
• ⏱️Throttled Searches: Includes configurable delays to prevent overloading indexers
• 📊Status Reporting: Provides clear feedback about what it's doing and which music it's searching for
• 🛡️Error Handling: Gracefully handles connection issues and API failures
• 🔁State Tracking: Remembers which artists/albums have been processed to avoid duplicate searches
• ⚙️Configurable Reset Timer: Automatically resets search history after a configurable period

• https://ninjacentral.co.za

1. Initialization: Connects to your Lidarr instance and analyzes your library
2. Missing Music:
   • Identifies artists or albums without files (based on configured mode)
   • Randomly selects content to process (up to configurable limit)
   • Refreshes metadata and triggers searches
3. Quality Upgrades:
   • Finds albums that don't meet your quality cutoff settings
   • Processes them in configurable batches
   • Uses smart selection to distribute searches
4. State Management:
   • Tracks which artists/albums have been processed
   • Automatically resets this tracking after a configurable time period
5. Repeat Cycle: Waits for a configurable period before starting the next cycle

Missing Episodes Demo	Quality Upgrade Demo
State Management System

The following environment variables can be configured:

• HUNT_MISSING_MODE

  • Determines the level at which missing content is processed
  • Options:
    • "artist": Process at the artist level (search for all missing albums by artist)
    • "album": Process at the album level (search for individual missing albums)
    • "both": Process both artists and albums with missing content

• HUNT_MISSING_ITEMS

  • Sets the maximum number of missing items (artists or albums) to process in each cycle
  • Setting to0 disables missing content searches completely

• HUNT_UPGRADE_ALBUMS

  • Sets the maximum number of albums to process for quality upgrades in each cycle
  • Setting to0 disables quality upgrade searches completely

• STATE_RESET_INTERVAL_HOURS

  • Controls how often the script "forgets" which items it has already processed
  • Default is 168 hours (one week)
  • Set to0 to disable reset (always remember processed items)

The simplest way to run Huntarr is via Docker:

docker run -d --name huntarr-lidarr \  --restart always \  -e API_KEY="your-api-key" \  -e API_URL="http://your-lidarr-address:8686" \  -e HUNT_MISSING_MODE="album" \  -e HUNT_MISSING_ITEMS="1" \  -e HUNT_UPGRADE_ALBUMS="0" \  -e SLEEP_DURATION="900" \  -e RANDOM_SELECTION="true" \  -e MONITORED_ONLY="true" \  -e STATE_RESET_INTERVAL_HOURS="168" \  -e DEBUG_MODE="false" \  huntarr/4lidarr:2.0

To check on the status of the program, you should see new files downloading or you can type:

docker logs huntarr-lidarr

For those who prefer Docker Compose, add this to yourdocker-compose.yml file:

version:"3.8"services:huntarr-lidarr:image:huntarr/4lidarr:2.0container_name:huntarr-lidarrrestart:alwaysenvironment:API_KEY:"your-api-key"API_URL:"http://your-lidarr-address:8686"HUNT_MISSING_MODE:"album"HUNT_MISSING_ITEMS:"1"HUNT_UPGRADE_ALBUMS:"0"SLEEP_DURATION:"900"RANDOM_SELECTION:"true"MONITORED_ONLY:"true"STATE_RESET_INTERVAL_HOURS:"168"DEBUG_MODE:"false"

Then run:

docker-compose up -d huntarr-lidarr

Run from the Unraid Command Line:

docker run -d --name huntarr-lidarr \  --restart always \  -e API_KEY="your-api-key" \  -e API_URL="http://your-lidarr-address:8686" \  -e HUNT_MISSING_MODE="album" \  -e HUNT_MISSING_ITEMS="1" \  -e HUNT_UPGRADE_ALBUMS="0" \  -e SLEEP_DURATION="900" \  -e RANDOM_SELECTION="true" \  -e MONITORED_ONLY="true" \  -e STATE_RESET_INTERVAL_HOURS="168" \  -e DEBUG_MODE="false" \  huntarr/4lidarr:2.0

For a more permanent installation on Linux systems using SystemD:

1. Save the script to/usr/local/bin/huntarr-lidarr.sh
2. Make it executable:chmod +x /usr/local/bin/huntarr-lidarr.sh
3. Create a systemd service file at/etc/systemd/system/huntarr-lidarr.service:

[Unit]Description=Huntarr Lidarr ServiceAfter=network.target lidarr.service[Service]Type=simpleUser=your-usernameEnvironment="API_KEY=your-api-key"Environment="API_URL=http://localhost:8686"Environment="HUNT_MISSING_MODE=album"Environment="HUNT_MISSING_ITEMS=1"Environment="HUNT_UPGRADE_ALBUMS=0"Environment="SLEEP_DURATION=900"Environment="RANDOM_SELECTION=true"Environment="MONITORED_ONLY=true"Environment="STATE_RESET_INTERVAL_HOURS=168"Environment="DEBUG_MODE=false"ExecStart=/usr/local/bin/huntarr-lidarr.shRestart=on-failureRestartSec=10[Install]WantedBy=multi-user.target

4. Enable and start the service:

sudo systemctlenable huntarr-lidarrsudo systemctl start huntarr-lidarr

• Library Completion: Gradually fill in missing albums and tracks in your collection
• Quality Improvement: Automatically upgrade album quality as better versions become available
• New Artist Setup: Automatically find music for newly added artists
• Background Service: Run it in the background to continuously maintain your library
• Smart Rotation: With state tracking, ensures all content gets attention over time

• First-Time Use: Start with default settings to ensure it works with your setup
• Adjusting Speed: Lower theSLEEP_DURATION to search more frequently (be careful with indexer limits)
• Focus on Missing or Upgrades: AdjustHUNT_MISSING_ITEMS andHUNT_UPGRADE_ALBUMS to focus on what matters to you
• Choose the Right Mode:
  • Useartist mode for broad searches (fastest but less targeted)
  • Usealbum mode for more targeted searches
• System Resources: The script uses minimal resources and can run continuously on even low-powered systems
• Debugging Issues: EnableDEBUG_MODE=true temporarily to see detailed logs when troubleshooting

• API Key Issues: Check that your API key is correct in Lidarr settings
• Connection Problems: Ensure the Lidarr URL is accessible from where you're running the script
• Command Failures: If search commands fail, try using the Lidarr UI to verify what commands are available in your version
• Logs: Check the container logs withdocker logs huntarr-lidarr if running in Docker
• Debug Mode: EnableDEBUG_MODE=true to see detailed API responses and process flow
• State Files: The script stores state in the container - if something seems stuck, try restarting the container

Change Log:

• v1: Original code written
• v2: Added dual targeting for both missing and quality upgrade albums
• v3: Added state tracking to prevent duplicate searches
• v4: Implemented configurable state reset timer
• v5: Added debug mode and improved error handling
• v6: Enhanced random selection mode for better distribution
• v7: Renamed from "Lidarr Hunter" to "Huntarr [Lidarr Edition]"

This script helps automate the tedious process of finding missing music and quality upgrades in your collection, running quietly in the background while respecting your indexers' rate limits.