Skip to main content

Custom Formats

ServiceSupported
Sonarr (v4)
Radarr
# See "Basic Setup" for `service_type` and `instance_name`
service_type:
  instance_name:
    # Custom Format Configuration
    delete_old_custom_formats: false
    custom_formats:
      - trash_ids:
          - ed38b889b31be83fda192888e2286d83 # BR-DISK
          - 90cedc1fea7ea5d11298bebd3d1d3223 # EVO (no WEBDL)
          - 90a6f9a284dff5103f6346090e6280c8 # LQ
          - dc98083864ea246d05a42df0d05f81cc # x265 (720/1080p)
        assign_scores_to:
          - name: HD-1080p
          - trash_id: 64fb5f9858489bdac2af690e27c8f42f # UHD Bluray + WEB
            score: -1000
      - trash_ids:
          - 496f355514737f7d83bf7aa4d24f8169 # TrueHD ATMOS
          - 2f22d89048b01681dde8afe203bf2e95 # DTS X
        assign_scores_to:
          - name: SD

    # Custom Format Groups
    # Default groups auto-sync when using guide-backed quality profiles.
    # Use `skip` to opt-out, `add` to include non-default groups.
    custom_format_groups:
      skip:
        - 9d5acd8f1da78dfbae788182f7605200 # Opt-out of Audio Formats
      add:
        - trash_id: f737e18b5824d6ebb2d57b957ae2fd6c # Streaming Services (UK)
          assign_scores_to:
            - trash_id: 64fb5f9858489bdac2af690e27c8f42f # UHD Bluray + WEB
            - name: HD-1080p
        - trash_id: 9d5acd8f1da78dfbae788182f7605200 # Customize Audio Formats
          select:
            - 7357cf5161efbf8c4d5d0c30b4815ee2 # Add non-default CFs
          exclude:
            - dc98083864ea246d05a42df0d05f81cc # Remove unwanted defaults
        - trash_id: f4a0410a1df109a66d6e47dcadcce014 # [Optional] Miscellaneous
          select_all: true
          exclude:
            - c9eafd50846d299b862ca9bb6ea91950 # x265

Synchronization Behavior​

Custom format synchronization is broken up into three categories:

  • Creation: Custom formats that are in the guide but do not exist in the service are created.
  • Updates: Custom formats that already exist in both the guide and the service but are different are updated.
  • Deletions: If deletions are allowed by having the delete_old_custom_formats configuration setting set to true, then custom formats in the service are deleted if they are removed from the guide or removed from your configuration file.
info

Recyclarr only manages custom formats that are in your configuration. If a configured custom format matches an existing one in the service by name, Recyclarr automatically adopts and updates it. To keep a custom format under manual control, do not include its trash ID in your configuration.

For details on how Recyclarr tracks custom formats it creates, see the Sync State page.

delete_old_custom_formats​

Optional. Default: false

If enabled, custom formats that you remove from your YAML configuration OR that are removed from the guide will be deleted from your Radarr instance.

info

This only applies to custom formats that Recyclarr has synchronized to Radarr. Custom formats that you have added manually in Radarr will not be deleted if you enable this setting.

custom_formats​

Optional. Default: No custom formats are synced

A list of one or more sets of custom formats each with an optional set of quality profiles names that identify which quality profiles to assign the scores for those custom formats to. The child properties documented below apply to each element of this list.

trash_ids​

Required.

A list of one or more Trash IDs of custom formats to synchronize. There are a couple of ways to obtain Trash IDs (listed in order of preference below). The Trash ID itself is a hash of hexadecimal characters, like 496f355514737f7d83bf7aa4d24f8169.

  • Most custom format pages in the TRaSH Guides (like this one) have either tables (with a Trash ID column) or a expandable "JSON" section. You can use these to obtain the Trash ID value.
  • From Recyclarr itself using the list custom-formats command.
  • Taken from the value of the "trash_id" property directly in the TRaSH Guide JSON files itself.
tip

To ease the readability concerns of using IDs, leave a comment beside the Trash ID in your configuration so it can be easily identified later. If you use list custom-formats, comments are added for you. For example:

trash_ids:
- 5d96ce331b98e077abb8ceb60553aa16 # dovi
- a570d4a0e56a2874b64e5bfa55202a1b # flac
A Few Things to Remember
  • If delete_old_custom_formats is set to true, custom formats are deleted in Radarr if you remove them from this list.
  • It's OK for the same custom format to exist in multiple lists of trash_ids. Recyclarr will only ever synchronize it once. Allowing it to be specified multiple times allows you to assign it to different profiles with different scores.

assign_scores_to​

Optional. Default: No quality profiles are changed

One or more quality profiles to update with the scores from the custom formats listed above. Scores are taken from the guide by default, with an option to override the score for all of them. Profiles can be referenced by name or trash_id. Each entry must use exactly one of these properties. Specifying both produces a validation error.

name​

Conditionally Required. Required if trash_id is not specified.

The name of a quality profile. Works for both guide-backed and user-defined profiles. This is the only way to target a specific profile variant when multiple profiles share the same trash_id. If the profile name does not exist, an error is shown. The profile is not required to appear in the top-level quality_profiles list; however, if you want Recyclarr to create it, you must also add an entry there.

trash_id​

Conditionally Required. Required if name is not specified.

The trash ID of a guide-backed quality profile. Use this instead of name when referencing profiles managed by Recyclarr through guide synchronization. This is useful because guide-backed profile names may change with guide updates, while the trash ID remains stable. Only works when exactly one profile in the configuration has this trash_id. If multiple profiles share it (profile variants), Recyclarr reports an error and instructs you to use name instead.

score​

Optional. Default: Use scores from the guide

A positive or negative number representing the score to apply to all custom formats listed in the trash_ids list. A score of 0 is also acceptable, which effectively disables the custom formats without having to delete them.

custom_format_groups​

Optional. Default: Auto-sync default groups for guide-backed quality profiles

Controls which CF groups sync from the TRaSH Guides. Groups bundle related custom formats with guide-recommended scores.

Auto-sync: When you use a guide-backed quality profile, Recyclarr automatically syncs groups that have default: true in the guide and include your profile in their compatibility list. Use skip to opt-out of auto-synced groups; use add to include non-default groups or customize which CFs sync.

See the CF Groups guide for usage patterns and examples.

skip​

Optional. Default: No groups are skipped

A list of group trash IDs to exclude from auto-sync. Groups in this list are ignored even if they match your quality profiles.

If the same group appears in both skip and add, the explicit add entry takes precedence.

add​

Optional. Default: No additional groups

A list of groups to explicitly sync. Use this to opt-in to non-default groups or customize a default group's behavior (e.g., use select and exclude to control which CFs sync).

trash_id​

Required.

The trash ID of a custom format group from the TRaSH Guides. Group trash IDs can be discovered using the list custom-format-groups command or found in the TRaSH Guide CF group JSON files.

assign_scores_to​

Optional. Default: All applicable guide-backed quality profiles

One or more quality profiles to assign the group's CF scores to. Profiles can be referenced by trash_id or name. Each entry must use exactly one of these properties. Specifying both produces a validation error.

When omitted, scores are assigned to all guide-backed profiles in your configuration that the group includes, including all profile variants sharing the same trash_id. Each group specifies compatible profiles; for example, HDR groups include only UHD profiles. To assign group scores to user-defined profiles, specify them explicitly with name.

trash_id​

Conditionally Required. Required if name is not specified.

The trash ID of a guide-backed quality profile. The profile must exist in the guide's quality profile resources, otherwise a validation error is reported. Only works when exactly one profile in the configuration has this trash_id. If multiple profiles share it (profile variants), Recyclarr reports an error and instructs you to use name instead.

name​

Conditionally Required. Required if trash_id is not specified.

The name of a quality profile to assign group scores to. Works for both guide-backed and user-defined profiles. This is the only way to target a specific profile variant when multiple profiles share the same trash_id. If the named profile does not exist in your configuration or in the remote service, a warning is produced during sync.

select​

Optional. Default: No additional CFs are selected

A list of CF trash IDs to include alongside the defaults. Use this to opt-in to non-default CFs from the group. Required and default CFs are always included regardless of this list.

Selecting a CF that is already a default produces a warning since it has no effect. Mutually exclusive with select_all; specifying both produces a validation error.

select_all​

Optional. Default: false

When true, all non-required CFs in the group are included as if they were individually listed in select. This is especially useful for groups that contain only optional CFs (no defaults), where nothing would sync without explicitly selecting each CF.

When the guide adds new CFs to a group, configurations with select_all: true automatically include them without changes. Use exclude to subtract specific CFs you do not want.

Mutually exclusive with select; specifying both produces a validation error.

exclude​

Optional. Default: No CFs are excluded

A list of CF trash IDs to remove from the synced set. Use this to opt-out of specific CFs you don't want synced. Required CFs cannot be excluded.

Without select_all, only default CFs can be meaningfully excluded. Excluding a non-default or required CF produces a warning since neither has any effect. With select_all: true, any non-required CF (both defaults and optionals) can be excluded.

A CF cannot appear in both select and exclude. The resulting set of CFs is: required CFs, plus default CFs minus exclude, plus select (or all non-required CFs when select_all is true).