{"id":28537325,"url":"https://github.com/plexguide/huntarr-lidarr","last_synced_at":"2025-10-08T21:41:31.704Z","repository":{"id":285603070,"uuid":"958684691","full_name":"plexguide/Huntarr-Lidarr","owner":"plexguide","description":" A specialized utility that automates discovering missing and upgrading your music collection. ","archived":false,"fork":false,"pushed_at":"2025-04-07T16:29:36.000Z","size":150,"stargazers_count":53,"open_issues_count":2,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-09-09T16:37:08.316Z","etag":null,"topics":["music","readarr","usenet"],"latest_commit_sha":null,"homepage":"https://plexguide.com","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/plexguide.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2025-04-01T15:40:37.000Z","updated_at":"2025-08-26T06:13:48.000Z","dependencies_parsed_at":"2025-04-03T15:41:54.642Z","dependency_job_id":null,"html_url":"https://github.com/plexguide/Huntarr-Lidarr","commit_stats":null,"previous_names":["plexguide/lidarr-hunter","plexguide/huntarr-lidarr"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/plexguide/Huntarr-Lidarr","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/plexguide%2FHuntarr-Lidarr","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/plexguide%2FHuntarr-Lidarr/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/plexguide%2FHuntarr-Lidarr/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/plexguide%2FHuntarr-Lidarr/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/plexguide","download_url":"https://codeload.github.com/plexguide/Huntarr-Lidarr/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/plexguide%2FHuntarr-Lidarr/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279000706,"owners_count":26082837,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-08T02:00:06.501Z","response_time":56,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["music","readarr","usenet"],"created_at":"2025-06-09T18:09:40.188Z","updated_at":"2025-10-08T21:41:31.699Z","avatar_url":"https://github.com/plexguide.png","language":"Python","readme":"# Huntarr [Lidarr Edition] - Force Lidarr to Hunt Missing Music \u0026 Upgrade Music Qualities\n\n\u003ch2 align=\"center\"\u003eWant to Help? Click the Star in the Upper-Right Corner! ⭐\u003c/h2\u003e\n\n\u003ctable\u003e\n  \u003ctr\u003e\n    \u003ctd colspan=\"2\"\u003e\u003cimg src=\"https://github.com/user-attachments/assets/b25f2c00-112f-4178-ab55-947ad1c9802c\" width=\"100%\"/\u003e\u003c/td\u003e\n  \u003c/tr\u003e\n\u003c/table\u003e\n\n\n**NOTE**: This utilizes Lidarr API Version - `1`. Legacy Name of this Program: Lidarr Hunter.\n \n## Table of Contents\n- [Overview](#overview)\n- [Related Projects](#related-projects)\n- [Features](#features)\n- [How It Works](#how-it-works)\n- [Configuration Options](#configuration-options)\n- [Installation Methods](#installation-methods)\n  - [Docker Run](#docker-run)\n  - [Docker Compose](#docker-compose)\n  - [Unraid Users](#unraid-users)\n  - [SystemD Service](#systemd-service)\n- [Use Cases](#use-cases)\n- [Tips](#tips)\n- [Troubleshooting](#troubleshooting)\n\n## Overview \n\nThis 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.\n\n## Related Projects\n\n* [Huntarr - Sonarr Edition](https://github.com/plexguide/Sonarr-Hunter) - Sister version for TV Shows\n* [Huntarr - Radarr Edition](https://github.com/plexguide/Radarr-Hunter) - Sister version for Movies\n* [Huntarr - Readarr Edition](https://github.com/plexguide/Huntarr-Readarr) - Sister version for Books\n* [Unraid Intel ARC Deployment](https://github.com/plexguide/Unraid_Intel-ARC_Deployment) - Convert videos to AV1 Format (I've saved 325TB encoding to AV1)\n* Visit [PlexGuide](https://plexguide.com) for more great scripts\n\n## PayPal Donations – Building My Daughter's Future\n\nMy 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!\n\n[![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)\n\n## Features\n\n- 🔄 **Continuous Operation**: Runs indefinitely until manually stopped\n- 🎯 **Dual Targeting System**: Targets both missing music and quality upgrades\n- 🎲 **Random Selection**: By default, selects music randomly to distribute searches across your library\n- ⏱️ **Throttled Searches**: Includes configurable delays to prevent overloading indexers\n- 📊 **Status Reporting**: Provides clear feedback about what it's doing and which music it's searching for\n- 🛡️ **Error Handling**: Gracefully handles connection issues and API failures\n- 🔁 **State Tracking**: Remembers which artists/albums have been processed to avoid duplicate searches\n- ⚙️ **Configurable Reset Timer**: Automatically resets search history after a configurable period\n\n## Indexers Approving of Huntarr:\n* https://ninjacentral.co.za\n\n## How It Works\n\n1. **Initialization**: Connects to your Lidarr instance and analyzes your library\n2. **Missing Music**: \n   - Identifies artists or albums without files (based on configured mode)\n   - Randomly selects content to process (up to configurable limit)\n   - Refreshes metadata and triggers searches\n3. **Quality Upgrades**:\n   - Finds albums that don't meet your quality cutoff settings\n   - Processes them in configurable batches\n   - Uses smart selection to distribute searches\n4. **State Management**:\n   - Tracks which artists/albums have been processed\n   - Automatically resets this tracking after a configurable time period\n5. **Repeat Cycle**: Waits for a configurable period before starting the next cycle\n\n\u003ctable\u003e\n  \u003ctr\u003e\n    \u003ctd width=\"50%\"\u003e\n      \u003cimg src=\"https://github.com/user-attachments/assets/558b5c39-3fe5-4dc4-b397-146064b4dc8d\" width=\"100%\"/\u003e\n      \u003cp align=\"center\"\u003e\u003cem\u003eMissing Episodes Demo\u003c/em\u003e\u003c/p\u003e\n    \u003c/td\u003e\n    \u003ctd width=\"50%\"\u003e\n      \u003cimg src=\"https://github.com/user-attachments/assets/bf897600-54f8-4511-aa67-112f1dfe55bb\" width=\"100%\"/\u003e\n      \u003cp align=\"center\"\u003e\u003cem\u003eQuality Upgrade Demo\u003c/em\u003e\u003c/p\u003e\n    \u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd colspan=\"2\"\u003e\n      \u003cimg src=\"https://github.com/user-attachments/assets/3e95f6d5-4a96-4bb8-a5b9-1d7b871ff94a\" width=\"100%\"/\u003e\n      \u003cp align=\"center\"\u003e\u003cem\u003eState Management System\u003c/em\u003e\u003c/p\u003e\n    \u003c/td\u003e\n  \u003c/tr\u003e\n\u003c/table\u003e\n\n## Configuration Options\n\nThe following environment variables can be configured:\n\n| Variable                     | Description                                                                | Default    |\n|------------------------------|----------------------------------------------------------------------------|------------|\n| `API_KEY`                    | Your Lidarr API key                                                        | Required   |\n| `API_URL`                    | URL to your Lidarr instance                                                | Required   |\n| `HUNT_MISSING_MODE`          | Mode for missing searches: `\"artist\"`, `\"album\"`, or `\"both\"`              | artist     |\n| `HUNT_MISSING_ITEMS`         | Maximum missing items to process per cycle (0 to disable)                  | 1          |\n| `HUNT_UPGRADE_ALBUMS`        | Maximum albums to upgrade per cycle (0 to disable)                         | 0          |\n| `SLEEP_DURATION`             | Seconds to wait after completing a cycle (900 = 15 minutes)                | 900        |\n| `RANDOM_SELECTION`           | Use random selection (`true`) or sequential (`false`)                      | true       |\n| `MONITORED_ONLY`             | Only process monitored content                                             | true       |\n| `STATE_RESET_INTERVAL_HOURS` | Hours after which the processed state files reset (168=1 week, 0=never)    | 168        |\n| `DEBUG_MODE`                 | Enable detailed debug logging (`true` or `false`)                          | false      |\n\n### Detailed Configuration Explanation\n\n- **HUNT_MISSING_MODE**\n  - Determines the level at which missing content is processed\n  - Options:\n    - `\"artist\"`: Process at the artist level (search for all missing albums by artist)\n    - `\"album\"`: Process at the album level (search for individual missing albums)\n    - `\"both\"`: Process both artists and albums with missing content\n\n- **HUNT_MISSING_ITEMS**\n  - Sets the maximum number of missing items (artists or albums) to process in each cycle\n  - Setting to `0` disables missing content searches completely\n\n- **HUNT_UPGRADE_ALBUMS**\n  - Sets the maximum number of albums to process for quality upgrades in each cycle\n  - Setting to `0` disables quality upgrade searches completely\n\n- **STATE_RESET_INTERVAL_HOURS**\n  - Controls how often the script \"forgets\" which items it has already processed\n  - Default is 168 hours (one week)\n  - Set to `0` to disable reset (always remember processed items)\n\n## Installation Methods\n\n### Docker Run\n\nThe simplest way to run Huntarr is via Docker:\n\n```bash\ndocker run -d --name huntarr-lidarr \\\n  --restart always \\\n  -e API_KEY=\"your-api-key\" \\\n  -e API_URL=\"http://your-lidarr-address:8686\" \\\n  -e HUNT_MISSING_MODE=\"album\" \\\n  -e HUNT_MISSING_ITEMS=\"1\" \\\n  -e HUNT_UPGRADE_ALBUMS=\"0\" \\\n  -e SLEEP_DURATION=\"900\" \\\n  -e RANDOM_SELECTION=\"true\" \\\n  -e MONITORED_ONLY=\"true\" \\\n  -e STATE_RESET_INTERVAL_HOURS=\"168\" \\\n  -e DEBUG_MODE=\"false\" \\\n  huntarr/4lidarr:2.0\n```\n\nTo check on the status of the program, you should see new files downloading or you can type:\n```bash\ndocker logs huntarr-lidarr\n```\n\n### Docker Compose\n\nFor those who prefer Docker Compose, add this to your `docker-compose.yml` file:\n\n```yaml\nversion: \"3.8\"\nservices:\n  huntarr-lidarr:\n    image: huntarr/4lidarr:2.0\n    container_name: huntarr-lidarr\n    restart: always\n    environment:\n      API_KEY: \"your-api-key\"\n      API_URL: \"http://your-lidarr-address:8686\"\n      HUNT_MISSING_MODE: \"album\"\n      HUNT_MISSING_ITEMS: \"1\"\n      HUNT_UPGRADE_ALBUMS: \"0\"\n      SLEEP_DURATION: \"900\"\n      RANDOM_SELECTION: \"true\"\n      MONITORED_ONLY: \"true\"\n      STATE_RESET_INTERVAL_HOURS: \"168\"\n      DEBUG_MODE: \"false\"\n```\n\nThen run:\n\n```bash\ndocker-compose up -d huntarr-lidarr\n```\n\n### Unraid Users\n\nRun from the Unraid Command Line:\n\n```bash\ndocker run -d --name huntarr-lidarr \\\n  --restart always \\\n  -e API_KEY=\"your-api-key\" \\\n  -e API_URL=\"http://your-lidarr-address:8686\" \\\n  -e HUNT_MISSING_MODE=\"album\" \\\n  -e HUNT_MISSING_ITEMS=\"1\" \\\n  -e HUNT_UPGRADE_ALBUMS=\"0\" \\\n  -e SLEEP_DURATION=\"900\" \\\n  -e RANDOM_SELECTION=\"true\" \\\n  -e MONITORED_ONLY=\"true\" \\\n  -e STATE_RESET_INTERVAL_HOURS=\"168\" \\\n  -e DEBUG_MODE=\"false\" \\\n  huntarr/4lidarr:2.0\n```\n\n### SystemD Service\n\nFor a more permanent installation on Linux systems using SystemD:\n\n1. Save the script to `/usr/local/bin/huntarr-lidarr.sh`\n2. Make it executable: `chmod +x /usr/local/bin/huntarr-lidarr.sh`\n3. Create a systemd service file at `/etc/systemd/system/huntarr-lidarr.service`:\n\n```ini\n[Unit]\nDescription=Huntarr Lidarr Service\nAfter=network.target lidarr.service\n\n[Service]\nType=simple\nUser=your-username\nEnvironment=\"API_KEY=your-api-key\"\nEnvironment=\"API_URL=http://localhost:8686\"\nEnvironment=\"HUNT_MISSING_MODE=album\"\nEnvironment=\"HUNT_MISSING_ITEMS=1\"\nEnvironment=\"HUNT_UPGRADE_ALBUMS=0\"\nEnvironment=\"SLEEP_DURATION=900\"\nEnvironment=\"RANDOM_SELECTION=true\"\nEnvironment=\"MONITORED_ONLY=true\"\nEnvironment=\"STATE_RESET_INTERVAL_HOURS=168\"\nEnvironment=\"DEBUG_MODE=false\"\nExecStart=/usr/local/bin/huntarr-lidarr.sh\nRestart=on-failure\nRestartSec=10\n\n[Install]\nWantedBy=multi-user.target\n```\n\n4. Enable and start the service:\n\n```bash\nsudo systemctl enable huntarr-lidarr\nsudo systemctl start huntarr-lidarr\n```\n\n## Use Cases\n\n- **Library Completion**: Gradually fill in missing albums and tracks in your collection\n- **Quality Improvement**: Automatically upgrade album quality as better versions become available\n- **New Artist Setup**: Automatically find music for newly added artists\n- **Background Service**: Run it in the background to continuously maintain your library\n- **Smart Rotation**: With state tracking, ensures all content gets attention over time\n\n## Tips\n\n- **First-Time Use**: Start with default settings to ensure it works with your setup\n- **Adjusting Speed**: Lower the `SLEEP_DURATION` to search more frequently (be careful with indexer limits)\n- **Focus on Missing or Upgrades**: Adjust `HUNT_MISSING_ITEMS` and `HUNT_UPGRADE_ALBUMS` to focus on what matters to you\n- **Choose the Right Mode**:\n  - Use `artist` mode for broad searches (fastest but less targeted)\n  - Use `album` mode for more targeted searches\n- **System Resources**: The script uses minimal resources and can run continuously on even low-powered systems\n- **Debugging Issues**: Enable `DEBUG_MODE=true` temporarily to see detailed logs when troubleshooting\n\n## Troubleshooting\n\n- **API Key Issues**: Check that your API key is correct in Lidarr settings\n- **Connection Problems**: Ensure the Lidarr URL is accessible from where you're running the script\n- **Command Failures**: If search commands fail, try using the Lidarr UI to verify what commands are available in your version\n- **Logs**: Check the container logs with `docker logs huntarr-lidarr` if running in Docker\n- **Debug Mode**: Enable `DEBUG_MODE=true` to see detailed API responses and process flow\n- **State Files**: The script stores state in the container - if something seems stuck, try restarting the container\n\n---\n\n**Change Log:**\n- **v1**: Original code written\n- **v2**: Added dual targeting for both missing and quality upgrade albums\n- **v3**: Added state tracking to prevent duplicate searches\n- **v4**: Implemented configurable state reset timer\n- **v5**: Added debug mode and improved error handling\n- **v6**: Enhanced random selection mode for better distribution\n- **v7**: Renamed from \"Lidarr Hunter\" to \"Huntarr [Lidarr Edition]\"\n\n---\n\nThis 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.\n","funding_links":["https://www.paypal.com/donate?hosted_button_id=58AYJ68VVMGSC"],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fplexguide%2Fhuntarr-lidarr","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fplexguide%2Fhuntarr-lidarr","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fplexguide%2Fhuntarr-lidarr/lists"}