Configuration Files

Configarr uses two main configuration files:

config.yml - Contains your main configuration
secrets.yml - Stores sensitive information like API keys

Configuration Structure

We try to be mostly compatible with Recyclarr, but with some small differences. We started this fork since Recyclarr V7 and will not always support newer features. Additionally we implement new features which recyclarr does not support at all like custom formats definitions directly in config or support local folders.

Templates

Configarr supports two types of templates:

Recyclarr Templates: Used to define reusable configuration blocks
- Documentation: Recyclarr Templates Wiki
- Location: Place template files in the directory specified by localConfigTemplatesPath
TRaSH-Guides Templates: Standard templates from TRaSH-Guides
- These are automatically pulled from the TRaSH-Guides repository
- language field support added with 1.7.0
- Can be overridden using trashGuideUrl in config.yml
- See TRaSH-Guides Radarr and TRaSH-Guides Sonarr for more information

Custom Formats Definitions

Custom formats can be defined in two ways:

Direct in config.yml: Define custom formats directly in your configuration file
Separate files: Store custom formats in separate files in the localCustomFormatsPath directory
Local templates: Store custom formats in local templates folder which can be included per instance (at the moment only for local templates and not recyclarr git templates)

Example custom format definition:

config.yml
# Directly in the main config.yml
customFormatDefinitions:
  - trash_id: custom-de-only # Unique identifier
    trash_scores:
      default: -10000 # Default score for this format
    trash_description: "Language: German Only"
    name: "Language: Not German"
    includeCustomFormatWhenRenaming: false
    specifications:
      - name: Not German Language
        implementation: LanguageSpecification
        negate: true
        required: false
        fields:
          value: 4
# ...

local-templates/template1.yml
# or in templates which can be included per instance
customFormatDefinitions:
  - trash_id: custom-de-only2 # Unique identifier
    trash_scores:
      default: -10000 # Default score for this format
    trash_description: "Language: German Only 2"
    name: "Language: Not German"
    includeCustomFormatWhenRenaming: false
    specifications:
      - name: Not German Language
        implementation: LanguageSpecification
        negate: true
        required: false
        fields:
          value: 4
# ...

Configuration Files Reference

If you want to deep dive into available values and parameters you can always check the direct source code reference for available configurations: Source Code

config.yml

The main configuration file that defines your Sonarr and Radarr instances, custom formats, and template includes.

Config.yml

config.yml
# Optional: Override default repositories
#trashGuideUrl: https://github.com/BlackDark/fork-TRASH-Guides
#recyclarrConfigUrl: https://github.com/BlackDark/fork-recyclarr-configs

# since v1.12.0. Optional. Enable for legacy configuration to clone full repos (trash, recyclarr) instead of sparse.
# Default is false. Setting to true increases storage usage up to 10x.
#enableFullGitClone: true

# Optional: Paths for custom formats and templates
localCustomFormatsPath: /app/cfs
localConfigTemplatesPath: /app/templates

# Optional. Custom Format Definitions
customFormatDefinitions:
  - trash_id: example-in-config-cf
    trash_scores:
      default: -10000
    trash_description: "Language: German Only"
    name: "Language: Not German"
    includeCustomFormatWhenRenaming: false
    specifications:
      - name: Not German Language
        implementation: LanguageSpecification
        negate: true
        required: false
        fields:
          value: 4

# With this options you can disable or enable processing for *arrs. Default is enabled
#sonarrEnabled: false
#radarrEnabled: false
#whisparrEnabled: false
#readarrEnabled: false
#lidarrEnabled: false

# Sonarr Configuration
sonarr:
  instance1: # Instance name (can be any unique identifier)
    base_url: http://sonarr:8989 # Sonarr instance URL
    api_key: !secret SONARR_API_KEY # Reference to API key in secrets.yml
    # api_key: !env SONARR_API_KEY # load from environment variable

    # since v1.11.0. You can disable instances. Optional
    # enabled: false

    # since v1.12.0. Optional
    # delete_unmanaged_custom_formats:
    #   enabled: true
    #   ignore: # optional
    #     - some-cf

    quality_definition:
      type: series # Quality definition type for Sonarr

    include: # Template includes
      - template: sonarr-cf
      - template: sonarr-quality
      - template: d1498e7d189fbe6c7110ceaabb7473e6
        source: TRASH # RECYCLARR (default) or TRASH

      # WEB-1080p (recyclarr template)
      - template: sonarr-quality-definition-series
      - template: sonarr-v4-quality-profile-web-1080p
      - template: sonarr-v4-custom-formats-web-1080p

    # experimental available in all *arr
    #media_management: {}

    # experimental available in all *arr
    #media_naming_api: {}

    # naming from recyclarr: https://recyclarr.dev/wiki/yaml/config-reference/media-naming/
    #media_naming: {}

    # (experimental) since v1.12.0
    # allows using the cf-groups from TRaSH-Guide.
    custom_format_groups:
      - trash_guide:
          - id: c4735e1d02e8738044ad4ad1bf58670c # Multiple CFs, default only required=true are loaded
            #include_unrequired: true # if you want to load all set this to true
        assign_scores_to:
          - name: WEB-1080p

    custom_formats: # Custom format assignments
      - trash_ids:
          - 47435ece6b99a0b477caf360e79ba0bb # x265 (HD)
        assign_scores_to:
          - name: WEB-1080p
            score: 0
      - trash_ids:
          - a3d82cbef5039f8d295478d28a887159 # block HDR10+
          - 2b239ed870daba8126a53bd5dc8dc1c8 # block DV HDR10+
        assign_scores_to:
          - name: WEB-1080p
            score: -10000
      - trash_ids:
          - example-in-config-cf # custom format defined in config.yml
        assign_scores_to:
          - name: WEB-1080p
            score: -5000

    quality_profiles:
      - name: WEB-1080p
        upgrade:
          min_format_score: 10000

    # Ability to rename quality profiles
    # renameQualityProfiles:
    # - from: WEB-1080p
    #   to: RenamedProfile

    # Ability to clone profiles
    # cloneQualityProfiles:
    #   - from: RenamedExampleProfile
    #     to: ClonedProfile

# Radarr Configuration
radarr:
  instance1: # Instance name (can be any unique identifier)
    base_url: http://radarr:7878 # Radarr instance URL
    api_key: !secret RADARR_API_KEY # Reference to API key in secrets.yml

    quality_definition:
      type: movies # Quality definition type for Radarr

    include:
      # Comment out any of the following includes to disable them
      - template: radarr-quality-definition-movie
      - template: radarr-quality-profile-hd-bluray-web
      - template: radarr-custom-formats-hd-bluray-web

    custom_formats: # Custom format assignments
      - trash_ids:
          - 9f6cbff8cfe4ebbc1bde14c7b7bec0de # IMAX Enhanced
        assign_scores_to:
          - name: HD Bluray + WEB
            score: 0

    quality_profiles:
      - name: HD Bluray + WEB
        # Support added with 1.7.0. Not support in all *arr applications. Check the application if it is supported.
        language: Any # The name must match available names in *arr
        # Reset existing CustomFormats scores on profile
        reset_unmatched_scores:
          enabled: true
        upgrade:
          allowed: true
          until_quality: Remux-1080p
          until_score: 10000
        min_format_score: 100
        # Score set from TRaSH-Guide to use
        #score_set: anime-radarr
        # Sorting order of qualities in profile. Either top or bottom
        #quality_sort: top
        # How to group and sort profiles
        qualities:
          - name: Remux-1080p
            qualities:
              - Bluray-1080p
              - Remux-1080p
          - name: WEB 1080p
            qualities:
              - WEBDL-1080p
              - WEBRip-1080p
              - HDTV-1080p
          - name: Bluray-720p
          - name: WEB 720p
            qualities:
              - WEBDL-720p
              - WEBRip-720p
              - HDTV-720p
          - name: Bluray-576p
          - name: Bluray-480p
          - name: WEB 480p
            qualities:
              - WEBDL-480p
              - WEBRip-480p
          - name: DVD
          - name: SDTV

# experimental support: check https://configarr.rayak.de/docs/configuration/experimental-support
whisparr: {}

# experimental support: check https://configarr.rayak.de/docs/configuration/experimental-support
readarr: {}

# experimental support: check https://configarr.rayak.de/docs/configuration/experimental-support
lidarr: {}

secrets.yml

Store sensitive information like API keys in this file. Never commit this file to version control.

secrets.yml
SONARR_API_KEY: your_sonarr_api_key_here
RADARR_API_KEY: your_radarr_api_key_here

Enable/Disable

You can configure enabled *Arr instance with options in the config.yml file. Default everything is true.

# true or false
sonarrEnabled: false
radarrEnabled: false
whisparrEnabled: false
readarrEnabled: false
lidarrEnabled: false

# You can also disable on per instance basis
sonarr:
  instance1:
    # ...
    enabled: false

Quality Definition / Size

Support has been added to allow configuring quality definitions manually if required. (Hint: Currently evaluation if the current function with type: string which represents the filename in the TRaSH-Guide should be deprecated in favor of the more consistent trash_id. See Github Issue).

# ...

sonarr:
  instance1:
    # ...
    quality_definition:
      qualities:
        - quality: "HDTV-720p" # this must always match with the available name / identifier in the *arr
          title: AdjustedName # optional
          min: 17.1
          preferred: 500
          max: 1000

# other file template.yml
---
quality_definition:
  qualities:
    - quality: "HDTV-1080p"
      min: 20
      preferred: 500
      max: 1000

Notes:

preferredRatio only applies to TRaSH/Recyclarr imported templates
works also with template and include
merged order is like: TRaSH/Recyclarr templates -> local templates -> config file
experimental, available since v1.9.0

Media Naming

You can use the predefined naming configurations from TRaSH-Guide like in recyclarr with the media_naming key.

The configuration values differs between Radarr and Sonarr.

Radarr

radarr:
  instance1:
    # Media Naming Configuration
    media_naming:
      folder: default
      movie:
        rename: true
        standard: default

Property	Description	Default
`folder`	Key for "Movie Folder Format". Check debug logs or TRaSH-Guide for values.	Not synced
`movie.rename`	If set to `true`, this enables the "Rename Movies" checkbox in the Radarr UI.	Not synced
`movie.standard`	Key for "Standard Movie Format". Check debug logs or TRaSH-Guide for values.	Not synced

All configurations above directly affect the "Movie Naming" settings under Settings > Media Management in the Radarr UI. If a property is not specified, Configarr will not sync that setting, allowing manual configuration.

Sonarr

sonarr:
  instance1:
    # Media Naming Configuration
    media_naming:
      series: default
      season: default
      episodes:
        rename: true
        standard: default
        daily: default
        anime: default

Property	Description	Default
`series`	Key for "Series Folder Format". Check debug logs or TRaSH-Guide for values.	Not synced
`season`	Key for "Season Folder Format". Check debug logs or TRaSH-Guide for values.	Not synced
`episodes.rename`	If set to `true`, this enables the "Rename Episodes" checkbox in the Sonarr UI.	Not synced
`episodes.standard`	Key for "Standard Episode Format". Check debug logs or TRaSH-Guide for values.	Not synced
`episodes.daily`	Key for "Daily Episode Format". Check debug logs or TRaSH-Guide for values.	Not synced
`episodes.anime`	Key for "Anime Episode Format". Check debug logs or TRaSH-Guide for values.	Not synced

All configurations above directly affect the "Episode Naming" settings under Settings > Media Management in the Sonarr UI. If a property is not specified, Configarr will not sync that setting, allowing manual configuration.

Quality Profile Rename

Support has been added to allow renaming quality profiles. This is useful if you use existing templates for example from TRaSH-Guides but want to adjust the naming to your liking.

We achieve the renaming by modifying all names in the quality_profiles fields and custom formats score mappings.

# ...

sonarr:
  instance1:
    # ...

    # Ability to rename profiles
    renameQualityProfiles:
      - from: ExampleProfile # must be the exact name of the existing profile
        to: RenamedExampleProfile # will be the new profile

Notes:

not supported in templates and will therefore not be merged!
rename order will be displayed in DEBUG log like: DEBUG [16:37:09.377]: Will rename quality profiles in this order: 'ExampleProfile' -> 'RenamedExampleProfile','[German] HD Bluray + WEB' -> 'RenamedProfile'
experimental, available since v1.10.0

Quality Profile Cloning

Support has been added to allow cloning quality profiles. This is useful if you use existing templates for example from TRaSH-Guides but want to duplicate and slightly adjust some Custom Format scores or mappings.

We achieve the clone by duplicating all quality profiles and duplicating all profile references in the custom formats.

tip

The ordering of rename and clone is important. At the moment we rename first and then clone!

# ...

sonarr:
  instance1:
    # ...

    # Ability to clone profiles
    cloneQualityProfiles:
      - from: ExampleProfile # must be the exact name of the existing profile
        to: ClonedProfile1 # will be the new profile

Notes:

not supported in templates and will therefore not be merged!
clone order will be displayed in DEBUG log
experimental, available since v1.10.0

Cleanup / Deleting CustomFormats

You can now enable the option to delete all custom formats which are not managed and used in the quality profiles. Additionally you can provide exceptions which should be ignored from deletions.

# ...

sonarr:
  instance1:
    # ...

    # (experimental) since v1.12.0. Optional
    delete_unmanaged_custom_formats:
      enabled: true
      ignore: # optional
        - some-cf

Notes:

experimental, available since v1.12.0

CustomFormatGroups

Support has been added to allow using the TRaSH-Guide custom format groups: see here. Those are logically bundled together CustomFormats which will be applied together. TRaSH-Guide is using them in an interactive manner with Notifiarr therefore there are also non required CustomFormats. Configarr will only load required ones (required: true).

If you need some optional ones just add them with the existing custom_formats mapping. Also the quality_profiles mapping in the JSON file is ignored because it does not make sense in Configarr.

# ...

sonarr:
  instance1:
    # ...

    # (experimental) since v1.12.0
    # allows using the cf-groups from TRaSH-Guide.
    custom_format_groups:
      - id: c4735e1d02e8738044ad4ad1bf58670c # Multiple CFs, default only required=true are loaded
        #include_unrequired: true # if you want to load all set this to true
      - trash_ids:
          - c4735e1d02e8738044ad4ad1bf58670c # Multiple CFs, only where required=true are loaded
        assign_scores_to:
          - name: MyProfile

Notes:

experimental, available since v1.12.0

Usage

Create both config.yml and secrets.yml files
Place them in your Configarr configuration directory
For Docker installations, mount these files as volumes
For Kubernetes deployments, create ConfigMaps/Secrets from these files

Configarr will automatically load these configurations on startup and apply them to your Sonarr/Radarr instances.

Experimental supported fields

Experimental support for media_management and media_naming_api (since v1.5.0) With those you can configure different settings in the different tabs available per *arr. Both fields are under experimental support. The supports elements in those are dependent on the *arr used. Check following API documentation of available fields:

Naming APIs:
MediaManagement APIs:

Configuration Structure​

Templates​

Custom Formats Definitions​

Configuration Files Reference​

config.yml​

secrets.yml​

Enable/Disable​

Quality Definition / Size​

Media Naming​

Quality Profile Rename​

Quality Profile Cloning​

Cleanup / Deleting CustomFormats​

CustomFormatGroups​

Usage​

Experimental supported fields​

Configuration Structure

Templates

Custom Formats Definitions

Configuration Files Reference

config.yml

secrets.yml

Enable/Disable

Quality Definition / Size

Media Naming

Quality Profile Rename

Quality Profile Cloning

Cleanup / Deleting CustomFormats

CustomFormatGroups

Usage

Experimental supported fields