Skip to content

Custom Rulesets ​

Create custom rulesets in FunkArr's web UI to handle shows or movies not covered by the community catalog, or to override community rules with your own matching logic.

Your First Ruleset ​

This walkthrough creates a ruleset for a TV show called "Abenteuer Wald" that airs on SWR.

1. Open the Builder ​

Navigate to Rulesets → + New in the FunkArr web UI. The builder opens with an empty form on the left and the live preview panel on the right.

2. Fill in Identity ​

FieldValueWhy
RuleSet IDabenteuer-waldUnique kebab-case identifier. Cannot be changed after creation.
TopicAbenteuer WaldExactly as it appears in the Mediathek topic field.
Media TypeShowTells Sonarr/Radarr how to handle it.
Media NameAbenteuer WaldAuto-filled from Topic. Change it only if the show has a different name in TVDB/TMDB.
TVDB ID12345Look this up on thetvdb.com. Optional but recommended - Sonarr uses it to match.

Add aliases if the show appears under different topic names (e.g., "Abenteuer Wald - Spezial").

3. Set Default Confidence ​

Set confidence to 1.0 for a show where you expect reliable matches. Lower it (e.g., 0.8) if the Mediathek data is inconsistent and you want Sonarr to double-check.

4. Add a Matching Rule ​

Click + Add Rule. A new rule card opens with a generated ID.

FieldValue
Rule IDairdate
Priority0 (first rule to try)
StrategyTitle Equals Airdate

For this example, the Mediathek titles look like "Abenteuer Wald vom 13. September 2026", so the airdate strategy extracts the broadcast date directly.

5. Add a Filter ​

Exclude short clips by adding a filter in the all section:

  • Field: duration
  • Operator: greaterThan
  • Value: 20

This ensures only full episodes (longer than 20 minutes) are matched.

6. Test with the Debugger ​

The live preview panel on the right auto-fetches Mediathek entries matching your topic. As you build rules, matches appear in real time with green indicators.

For more thorough testing, click Full Test to send your rules to the server. The full test shows a detailed pipeline trace for each candidate - which rules were tried, which filters passed or failed, and what was extracted.

7. Save ​

Click Save. FunkArr validates your ruleset against the JSON schema and registers it immediately. The new ruleset appears in the list and starts matching the next time Sonarr or Radarr trigger a search.

Overrides ​

Local rulesets (data/rulesets/local/<id>.json) take priority over community rulesets (data/rulesets/community/<id>.json) with the same ID. When both exist, FunkArr merges them:

  • Rules with the same ID → local replaces community
  • Rules with a new ID → appended to the list
  • Topic → the community ruleset's topic is kept
  • Aliases → unioned (both sets combined)
  • Media fields → local wins per field (name, type, tvdbId, imdbId, tmdbId)
  • Confidence → local value used if set
  • Enrichment → local settings win per field

The merged result is sorted by priority.

To edit a community ruleset, navigate to its detail page and click Edit. The builder saves the result as a full local copy with standalone: true (see below). The community file stays untouched but no longer influences that ruleset. For an override that keeps receiving community updates, create a local JSON file with the same ID in data/rulesets/local/ containing only your differing rules.

Standalone Mode ​

If you want to ignore the community base entirely, set standalone: true in your local ruleset JSON file. This tells FunkArr to use your local ruleset as-is, with no merging. Editing a community ruleset in the builder sets this flag automatically.

Use this when a community ruleset's structure is too different from what you need, or when you want full control over every rule.

Disabling Community Rules ​

To skip specific community rules without replacing them, add their IDs to the disable array:

json
{
  "disable": ["title-includes", "title-includes-p1"]
}

Disabled rules are removed during merge. Your own rules still apply. The field only takes effect in merge mode, not with standalone: true.

Exporting for Community ​

If you've created a ruleset that others would find useful, click Export for Community on the detail page. This validates the ruleset and downloads the merged JSON file without the standalone and disable fields you can submit as a pull request to the community rulesets repository.

Next Steps ​