eddie/homelab
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 2
homelab/compose/media/automation/recyclarr/README.md

10 KiB
Raw Blame History

Recyclarr - TRaSH Guides Sync

Automatically sync TRaSH Guides recommendations to your Radarr and Sonarr instances.

Overview

Recyclarr keeps your Radarr and Sonarr configurations in sync with TRaSH Guides best practices:

  • ✅ Quality Profiles: Optimal quality settings
  • ✅ Custom Formats: Release group scoring
  • ✅ Quality Definitions: File size recommendations
  • ✅ Naming Formats: Consistent file naming
  • ✅ Automated Sync: Runs on schedule (every 6 hours by default)
  • ✅ Multi-Instance: Support multiple Radarr/Sonarr instances

Quick Start

1. Get API Keys

Radarr API Key:

# Visit https://radarr.fig.systems
# Settings → General → Security → API Key

Sonarr API Key:

# Visit https://sonarr.fig.systems
# Settings → General → Security → API Key

2. Create Configuration

cd ~/homelab/compose/media/automation/recyclarr

# Create config directory
mkdir -p config

# Copy example config
cp recyclarr.yml.example config/recyclarr.yml

# Edit with your API keys
nano config/recyclarr.yml

Update these values:

radarr:
  radarr-main:
    api_key: YOUR_RADARR_API_KEY_HERE  # <- Replace this

sonarr:
  sonarr-main:
    api_key: YOUR_SONARR_API_KEY_HERE  # <- Replace this

3. Deploy

docker compose up -d

4. Verify

Check the logs to see sync results:

docker logs recyclarr

You should see:

Processing configuration...
Syncing Radarr: radarr-main
Syncing Sonarr: sonarr-main
Sync completed successfully

Configuration

Basic Configuration

The config/recyclarr.yml file controls what gets synced.

Minimal example:

radarr:
  radarr-main:
    base_url: http://radarr:7878
    api_key: abc123...

sonarr:
  sonarr-main:
    base_url: http://sonarr:8989
    api_key: xyz789...

Quality Profiles

Radarr - HD Bluray + WEB:

radarr:
  radarr-main:
    quality_profiles:
      - name: HD Bluray + WEB
        upgrade:
          allowed: true
          until_quality: Bluray-1080p
        qualities:
          - name: Bluray-1080p
          - name: WEB 1080p
          - name: Bluray-720p
          - name: WEB 720p

Sonarr - WEB-1080p:

sonarr:
  sonarr-main:
    quality_profiles:
      - name: WEB-1080p
        upgrade:
          allowed: true
          until_quality: WEB 1080p
        qualities:
          - name: WEB 1080p
          - name: HDTV-1080p
          - name: WEB 720p

Custom Formats

Custom formats score releases based on quality, source, and release group.

High-quality release groups (+10000 points):

custom_formats:
  - trash_ids:
      - 3a3ff47579026e76d6504ebea39390de # Remux Tier 01
      - 9f98181fe5a3fbeb0cc29340da2a468a # Remux Tier 02
    quality_profiles:
      - name: HD Bluray + WEB
        score: 10000

Unwanted formats (-10000 points):

custom_formats:
  - trash_ids:
      - ed38b889b31be83ffc192888e2286d83 # BR-DISK
      - 90a6f9a284dff5103f6346090e6280c8 # LQ
      - b8cd450cbfa689c0259a01d9e29ba3d6 # 3D
    quality_profiles:
      - name: HD Bluray + WEB
        score: -10000

Find trash_ids:

Sync Schedule

Change sync frequency:

Edit .env:

# Every 6 hours (default)
CRON_SCHEDULE=0 */6 * * *

# Daily at 3 AM
CRON_SCHEDULE=0 3 * * *

# Every 12 hours
CRON_SCHEDULE=0 */12 * * *

# Every hour
CRON_SCHEDULE=0 * * * *

Manual sync:

docker exec recyclarr recyclarr sync

Common Configurations

1. HD Quality (1080p)

Good balance of quality and file size.

Radarr:

  • Bluray-1080p preferred
  • WEB-1080p as fallback
  • Scores high-quality release groups

Sonarr:

  • WEB-1080p preferred
  • HDTV-1080p as fallback

2. Maximum Quality (Remux)

Best possible quality, large file sizes.

radarr:
  radarr-main:
    quality_profiles:
      - name: Remux-1080p
        upgrade:
          allowed: true
          until_quality: Remux-1080p
        qualities:
          - name: Remux-1080p
          - name: Bluray-1080p

3. 4K / UHD

For 4K content:

radarr:
  radarr-4k:
    base_url: http://radarr:7878
    api_key: abc123...
    quality_profiles:
      - name: UHD Bluray + WEB
        upgrade:
          until_quality: Remux-2160p
        qualities:
          - name: Remux-2160p
          - name: Bluray-2160p
          - name: WEB 2160p

4. Anime

Special settings for anime:

sonarr:
  sonarr-anime:
    base_url: http://sonarr:8989
    api_key: xyz789...
    quality_profiles:
      - name: Anime
        qualities:
          - name: Bluray-1080p
          - name: WEB 1080p
    custom_formats:
      - trash_ids:
          - 064af5f084a0a24458cc8ecd3220f93f # Uncensored
        quality_profiles:
          - name: Anime
            score: 10000

Integration with Radarr/Sonarr

How It Works

  1. Recyclarr reads your recyclarr.yml configuration
  2. Connects to Radarr/Sonarr via API
  3. Syncs settings:
    • Creates/updates quality profiles
    • Adds custom formats with scores
    • Sets quality definitions
    • Configures naming formats
  4. Your instances now use TRaSH Guides best practices

What Gets Changed

Recyclarr modifies:

  • Quality profile settings
  • Custom format definitions
  • Quality definitions (file sizes)
  • Naming formats (if configured)

Recyclarr does NOT touch:

  • Your media files
  • Download client settings
  • Indexer configurations
  • Root folder locations
  • Existing downloads/monitoring

Multiple Instances

Run separate Radarr/Sonarr instances for different purposes:

radarr:
  radarr-1080p:
    base_url: http://radarr:7878
    api_key: abc123...

  radarr-4k:
    base_url: http://radarr-4k:7878
    api_key: def456...

sonarr:
  sonarr-shows:
    base_url: http://sonarr:8989
    api_key: ghi789...

  sonarr-anime:
    base_url: http://sonarr-anime:8989
    api_key: jkl012...

Troubleshooting

Recyclarr won't start

Check logs:

docker logs recyclarr

Common issues:

  • Missing API keys in config/recyclarr.yml
  • Radarr/Sonarr not accessible at base_url
  • Invalid YAML syntax

"Unable to connect to Radarr/Sonarr"

Verify connectivity:

# From recyclarr container
docker exec recyclarr curl http://radarr:7878
docker exec recyclarr curl http://sonarr:8989

Check:

  • Radarr/Sonarr containers are running
  • Both on homelab network
  • API keys are correct

"Profile not found"

The quality profile name in recyclarr.yml must match exactly.

Check existing profiles:

  1. Go to Radarr → Settings → Profiles
  2. Note the exact profile name
  3. Use that name in recyclarr.yml

Or let Recyclarr create the profile (it will if it doesn't exist).

Changes not appearing

Force a sync:

docker exec recyclarr recyclarr sync --preview
docker exec recyclarr recyclarr sync

Check:

  • Look for errors in logs
  • Verify API key has write permissions
  • Check Radarr/Sonarr system logs

Invalid trash_id

If you see "invalid trash_id" errors:

  1. Visit TRaSH Guides
  2. Find the custom format you want
  3. Copy the exact trash_id from the guide
  4. Update recyclarr.yml

Advanced Usage

Preview Mode

See what would change without applying:

docker exec recyclarr recyclarr sync --preview

Sync Specific Instance

# Sync only Radarr
docker exec recyclarr recyclarr sync radarr

# Sync only Sonarr
docker exec recyclarr recyclarr sync sonarr

# Sync specific instance
docker exec recyclarr recyclarr sync radarr-main

Validate Configuration

docker exec recyclarr recyclarr config list
docker exec recyclarr recyclarr config check

Debug Mode

Enable debug logging in .env:

LOG_LEVEL=Debug

Then restart:

docker compose restart

Best Practices

Start Simple

  1. First sync: Use default quality profiles
  2. Test: Download a movie/show
  3. Verify: Check quality and file size
  4. Adjust: Modify scores and profiles as needed

Quality Profile Strategy

For most users:

  • Radarr: HD Bluray + WEB (1080p)
  • Sonarr: WEB-1080p

For quality enthusiasts:

  • Radarr: Remux-1080p or UHD Bluray + WEB
  • Sonarr: Bluray-1080p

For storage-conscious:

  • Lower minimum quality
  • Add file size limits
  • Score smaller releases higher

Custom Format Scores

Scoring guide:

  • +10000: Highest priority (preferred release groups)
  • +5000: High priority (good quality)
  • +1000: Moderate preference
  • -10000: Never download (BR-DISK, CAM, etc.)
  • -5000: Avoid unless no alternative

Sync Frequency

Recommended schedules:

  • Every 6 hours: Default, good balance
  • Daily: If you rarely update settings
  • Every hour: If actively tuning configurations

TRaSH Guides Resources

Comparison: Recyclarr vs Profilarr

Feature Recyclarr Profilarr
Interface CLI / Automated Web UI
Configuration YAML file Web interface
Source TRaSH Guides Custom + Community
Automation Scheduled sync Manual/scheduled
Version Control Via Git (manual) Built-in
Learning Curve Moderate Easy
Best For Set-and-forget Active management

Use both together:

  • Recyclarr for automated TRaSH sync
  • Profilarr for custom tweaks and management

Next Steps

  1. ✅ Deploy Recyclarr
  2. ✅ Configure API keys
  3. ✅ Run first sync
  4. ✅ Check Radarr/Sonarr profiles
  5. ✅ Test download quality
  6. ⬜ Fine-tune custom format scores
  7. ⬜ Set up Profilarr for additional management
  8. ⬜ Monitor sync logs periodically

Automate quality, maintain consistency! 🎬