03. Usage

📘 Usage Guide

This guide explains how to use the Custom Format Sync tool effectively, including how to create and manage custom formats.

📁 Custom Format File Structure

Custom formats are defined in JSON files located in the custom_formats/ directory of your repository.

🔑 Key Fields

• name: The name of the custom format (required)
• cfSync_version: Version for change tracking (required, follows SemVer)
• cfSync_radarr: Boolean to sync to Radarr instances (optional, default: true)
• cfSync_sonarr: Boolean to sync to Sonarr instances (optional, default: true)
• cfSync_score: Score for all quality profiles (optional)
• cfSync_instances: List of specific instances to sync (optional, overrides cfSync_radarr and cfSync_sonarr)

📝 Example Custom Format JSON

{
  "name": "Example Custom Format",
  "cfSync_version": "0.0.1",
  "cfSync_radarr": true,
  "cfSync_sonarr": false,
  "cfSync_score": 100,
  "cfSync_instances": ["Radarr_001", "Radarr_002"],
  "includeCustomFormatWhenRenaming": false,
  "specifications": [
    {
      "name": "Example Specification",
      "implementation": "ReleaseTitleSpecification",
      "negate": false,
      "required": false,
      "fields": {
        "value": "example.*pattern"
      }
    }
  ]
}

🎯 Targeting Specific Instances

Use the cfSync_instances field to specify which instances should receive the custom format:

• Use "Radarr_001", "Radarr_002", etc. for Radarr instances
• Use "Sonarr_001", "Sonarr_002", etc. for Sonarr instances
• Use just the number (e.g., "001") to target both Radarr and Sonarr with that number

Example:

"cfSync_instances": ["Radarr_001", "Sonarr_002", "003"]

🔢 Setting Custom Format Scores

Use the cfSync_score field to set a score for the custom format in all quality profiles:

"cfSync_score": 100

🔄 Updating Custom Formats

When modifying custom formats in the custom_formats folder, you need to ensure the changes are detected properly by the system. This is handled by a version bump in the custom format's .json file, following semantic versioning (SemVer).

🚀 How to Update Custom Formats:

1. Open the appropriate custom format file in the custom_formats folder.

2. Make your desired changes. For example, let's say you want to add a new group to scenegroups-tvseries.json:

   Before:

   {
     "name": "Scene Groups (TV)",
     "cfSync_version": "0.0.1",
     "cfSync_radarr": false,
     "cfSync_sonarr": true,
     "cfSync_score": 5,
     "includeCustomFormatWhenRenaming": false,
     "specifications": [
       {
         "name": "[BLOCK1]",
         "implementation": "ReleaseTitleSpecification",
         "negate": false,
         "required": false,
         "fields": {
           "value": "-LOL|-DIMENSION|-KILLERS|-BATV"
         }
       }
     ]
   }

   After adding a new group:

   {
     "name": "Scene Groups (TV)",
     "cfSync_version": "0.0.1",
     "cfSync_radarr": false,
     "cfSync_sonarr": true,
     "cfSync_score": 5,
     "includeCustomFormatWhenRenaming": false,
     "specifications": [
       {
         "name": "[BLOCK1]",
         "implementation": "ReleaseTitleSpecification",
         "negate": false,
         "required": false,
         "fields": {
           "value": "-LOL|-DIMENSION|-KILLERS|-BATV|-NEWGROUP"
         }
       }
     ]
   }

3. After making the changes, bump the version in the same .json file. For example, change from 0.0.1 to 0.0.2:

   Before:

   "cfSync_version": "0.0.1"

   After:

   "cfSync_version": "0.0.2"

4. Save the changes to the .json file.

5. Commit and push your changes to the main branch.

There's no need to manually update the version.json file—the workflow sync-custom-formats.yml script will handle that automatically during the sync process.

🚀 Triggering Sync Manually

1. Go to the "Actions" tab in your GitHub repository.
2. Select the "Sync Custom Formats" workflow.
3. Click "Run workflow".
4. Choose the branch (usually main) and click "Run workflow".

📊 Monitoring Sync Results

1. After a sync (automatic or manual), go to the "Actions" tab.
2. Click on the most recent "Sync Custom Formats" workflow run.
3. Expand the "Run sync script" step to view the logs.
4. Check for any error messages or successful sync confirmations.

⚠️ Important Notes

• The sync process runs automatically on pushes to main that affect the custom_formats/ directory and daily at midnight UTC.
• Always increment the cfSync_version when making changes to ensure the update is synced.
• Be cautious when setting high scores for custom formats, as this can significantly impact your download decisions.

For more information on configuration and troubleshooting, please refer to the ⚙️ Configuration and 🔧 Troubleshooting pages.