Creating a Trash Guides Repository

This page explains how to create a repository compatible with the trash-guides provider type. This is an advanced topic for users who want to create their own complete guide structure with custom formats, quality sizes, quality profiles, and media naming schemes.

tip

If you just want to add a few custom formats, use the simpler custom-formats type instead. It requires no special structure, just a folder of JSON files. See the main resource providers page for details.

When You Need This

Use the trash-guides type when you need:

• Custom formats organized into groups
• Quality size definitions
• Quality profiles with pre-configured format scores
• Media naming schemes
• A complete alternative to or supplement for the official TRaSH Guides

Required Structure

A trash-guides compatible repository must have a metadata.json file at the root that tells Recyclarr where to find each type of resource.

Directory Layout Example

my-guides-repo/
├── metadata.json                    # Required: defines resource locations
├── docs/
│   ├── json/
│   │   └── radarr/
│   │       ├── cf/                  # Custom formats
│   │       │   ├── my-format-1.json
│   │       │   └── my-format-2.json
│   │       ├── cf-groups/           # Custom format groups
│   │       │   └── my-group.json
│   │       ├── quality-size/        # Quality sizes
│   │       │   └── movie.json
│   │       ├── quality-profiles/    # Quality profiles
│   │       │   └── my-profile.json
│   │       ├── quality-profile-groups/
│   │       │   └── my-qp-group.json
│   │       └── naming/              # Media naming
│   │           └── radarr-naming.json
│   └── Radarr/
│       └── Radarr-collection-of-custom-formats.md  # Optional: categories
└── ...

The metadata.json File

The metadata.json file tells Recyclarr where to find each type of resource. All paths are relative to the repository root. You can specify multiple paths per resource type if your files are organized across different directories.

{
  "json_paths": {
    "radarr": {
      "custom_formats": ["docs/json/radarr/cf"],
      "qualities": ["docs/json/radarr/quality-size"],
      "naming": ["docs/json/radarr/naming"],
      "quality_profiles": ["docs/json/radarr/quality-profiles"],
      "custom_format_groups": ["docs/json/radarr/cf-groups"],
      "quality_profile_groups": ["docs/json/radarr/quality-profile-groups"]
    },
    "sonarr": {
      "custom_formats": ["docs/json/sonarr/cf"],
      "qualities": ["docs/json/sonarr/quality-size"],
      "naming": ["docs/json/sonarr/naming"],
      "quality_profiles": ["docs/json/sonarr/quality-profiles"],
      "custom_format_groups": ["docs/json/sonarr/cf-groups"],
      "quality_profile_groups": ["docs/json/sonarr/quality-profile-groups"]
    }
  }
}

You only need to include the resource types you actually provide. If your repo only has custom formats and quality sizes, omit the other keys.

JSON File Structures

Custom Formats

Each custom format JSON file follows the Sonarr/Radarr custom format API structure with additional trash_ fields that Recyclarr uses:

{
  "trash_id": "b3b3a6ac74ecbd56bcdbefa4799fb9df",
  "trash_scores": {
    "default": 100
  },
  "name": "My Custom Format",
  "includeCustomFormatWhenRenaming": false,
  "specifications": [
    {
      "name": "Specification Name",
      "implementation": "ReleaseTitleSpecification",
      "negate": false,
      "required": true,
      "fields": {
        "value": "regex-pattern-here"
      }
    }
  ]
}

Field	Required	Description
trash_id	Yes	Unique identifier. Use a UUID or descriptive slug.
name	Yes	Display name shown in Radarr/Sonarr.
specifications	Yes	Array of conditions that define the format.
trash_scores	No	Default scores keyed by profile name.

Generating Trash IDs

Trash IDs must be unique across all your custom formats. You can generate UUIDs:

uuidgen | tr '[:upper:]' '[:lower:]'

Custom Format Groups

CF groups bundle related custom formats together so users can reference them as a single unit. Each group file lists the custom formats it contains by trash_id:

{
  "trash_id": "d9cc9a504e5ede6294c8b973aad4f028",
  "name": "[Streaming Services] General",
  "default": "true",
  "custom_formats": [
    {
      "trash_id": "b3b3a6ac74ecbd56bcdbefa4799fb9df",
      "name": "AMZN",
      "required": true
    },
    {
      "trash_id": "170b1d363bd8516fbf3a3eb05d4faff6",
      "name": "NF",
      "required": true
    }
  ],
  "quality_profiles": {
    "include": {
      "HD Bluray + WEB": "d1d67249d3890e49bc12e275d989a7e9",
      "Remux + WEB 1080p": "9ca12ea80aa55ef916e3751f4b874151"
    }
  }
}

Field	Required	Description
trash_id	Yes	Unique identifier for the group.
name	Yes	Display name for the group.
custom_formats	Yes	Array of CFs in the group, each with a trash_id.
default	No	Whether the group is included by default.
quality_profiles	No	Maps quality profile names to their trash_id values.

Quality Sizes

Quality size files define file size ranges for different quality levels:

{
  "trash_id": "aed34b9f60ee115dfa7918b742336277",
  "type": "movie",
  "qualities": [
    {
      "quality": "Bluray-1080p",
      "min": 50.8,
      "preferred": 1999,
      "max": 2000
    },
    {
      "quality": "WEBDL-1080p",
      "min": 12.5,
      "preferred": 1999,
      "max": 2000
    }
  ]
}

Quality Profiles

Quality profile files define complete quality profile configurations including quality ordering, cutoff, and format scores:

{
  "trash_id": "d1d67249d3890e49bc12e275d989a7e9",
  "name": "HD Bluray + WEB",
  "upgradeAllowed": true,
  "cutoff": "Bluray-1080p",
  "minFormatScore": 0,
  "cutoffFormatScore": 10000,
  "minUpgradeFormatScore": 1,
  "language": "Original",
  "items": [
    { "name": "Bluray-1080p", "allowed": true },
    {
      "name": "WEB 1080p",
      "allowed": true,
      "items": ["WEBRip-1080p", "WEBDL-1080p"]
    },
    { "name": "Bluray-720p", "allowed": true }
  ],
  "formatItems": {
    "HD Bluray Tier 01": "ed27ebfef2f323e964fb1f61391bcb35",
    "WEB Tier 01": "c20f169ef63c5f40c2def54abaf4438e"
  }
}

The formatItems map references custom format names to their trash_id values. The items array defines the quality ordering, where nested items represent quality groups.

Quality Profile Groups

Quality profile groups organize related quality profiles together. The file contains a JSON array of group objects:

[
  {
    "name": "Standard",
    "profiles": {
      "hd-bluray-web": "d1d67249d3890e49bc12e275d989a7e9",
      "remux-web-1080p": "9ca12ea80aa55ef916e3751f4b874151"
    }
  }
]

The keys in profiles are slugs that identify each quality profile, and the values are the corresponding trash_id values.

Media Naming

Media naming files define file and folder naming patterns. Each pattern type (folder and file) contains named variants for different media servers:

{
  "folder": {
    "default": "{Movie CleanTitle} ({Release Year})",
    "plex-imdb": "{Movie CleanTitle} ({Release Year}) {imdb-{ImdbId}}",
    "jellyfin-tmdb": "{Movie CleanTitle} ({Release Year}) [tmdbid-{TmdbId}]"
  },
  "file": {
    "standard": "{Movie CleanTitle} {(Release Year)} - {{Edition Tags}} {[Custom Formats]}{[Quality Full]}{-Release Group}",
    "plex-imdb": "{Movie CleanTitle} {(Release Year)} {imdb-{ImdbId}} - {edition-{Edition Tags}} {[Custom Formats]}{[Quality Full]}{-Release Group}"
  }
}

The variant names (like default, standard, plex-imdb) are what you reference in your Recyclarr configuration. The naming tokens differ between Radarr and Sonarr.

Category Organization

Categories organize custom formats for the recyclarr list command output. Unlike other resource types, categories are not configured through metadata.json. Recyclarr looks for markdown files at hardcoded paths:

• docs/Radarr/Radarr-collection-of-custom-formats.md
• docs/Sonarr/sonarr-collection-of-custom-formats.md

These files must contain markdown tables where each column header is a category name and each cell is a markdown link in the format [CF Name](#anchor). The anchor must match the JSON filename (without the .json extension). For example:

| Streaming Services | Audio                         |
|--------------------|-------------------------------|
| [AMZN](#amzn)      | [TrueHD ATMOS](#truehd-atmos) |
| [NF](#nf)          | [DTS-HD MA](#dts-hd-ma)       |

Categories are optional. If these files don't exist, recyclarr list still works but won't group custom formats into categories.

Using Your Repository

Once your repository is set up, add it to your settings.yml:

resource_providers:
  # As a supplemental source (adds to official)
  - name: my-guides
    type: trash-guides
    clone_url: https://github.com/yourname/my-guides.git
    reference: main

  # Or as a replacement (replaces official)
  - name: my-guides
    type: trash-guides
    clone_url: https://github.com/yourname/my-guides.git
    reference: main
    replace_default: true

For local directories:

resource_providers:
  - name: my-local-guides
    type: trash-guides
    path: /home/user/my-guides

Reference Implementation

The official TRaSH Guides repository is the reference implementation. Examine its metadata.json and directory organization for a working example.

warning

The TRaSH Guides structure is complex because it serves documentation purposes beyond Recyclarr. For simple use cases, the custom-formats type with a flat folder of JSON files is much easier to maintain.