Custom formats

Custom formats

Custom formats let you boost or penalise releases based on patterns in the release title, release group, size, or indexer flags — so that Dune.2023.RETAIL.EPUB.Multi ranks higher than Dune.2023.EPUB-SomeGroup, even though both match the quality profile.

Status in v0.12

Heads up — the custom-format CRUD API (/api/v1/customformat) exists and the rows persist, but the release-parser does not yet apply the scoring to candidate rankings. Releases are currently ranked by quality profile only. Tracking issue: #94 on the roadmap.

Formats you create now will start taking effect as soon as the scoring layer is wired — no data migration needed on your side.

Schema

A custom format is a name plus a list of conditions. A release matches the format when all conditions with required: true match, optionally weighted by negated/non-required entries.

{
  "name": "Freeleech",
  "conditions": [
    { "type": "indexerFlag", "pattern": "freeleech", "negate": false, "required": true }
  ]
}

Condition types

type	pattern interpretation
releaseTitle	Go regex tested against the raw release title
releaseGroup	Exact or regex match against the parsed group (last -GROUP in the title)
size	Size bound in bytes, prefixed with <, <=, >, >= (e.g. >5000000)
indexerFlag	String flag from the Newznab/Torznab response (e.g. freeleech, internal)

Modifier fields

• negate: true — the condition matches when the pattern does NOT match. Useful for "not a PROPER re-release".
• required: true — the format as a whole fails if this condition fails. Non-required conditions contribute to the score but don't disqualify the format.

Common patterns

Once the scoring layer ships, these are the formats most users want:

Format name	Condition	Rationale
RETAIL	releaseTitle regex (?i)\bretail\b	Prefer retail rips over user-converted sources
EPUB3	releaseTitle regex (?i)\bEPUB3\b	Pull in newer format when available
Unabridged	releaseTitle regex (?i)\bunabridged\b	Audiobook preference
Freeleech	indexerFlag freeleech	Don't spend torrent ratio when you don't have to
Bad group	releaseGroup `(?i)^(sgen	scanrip)$withnegate: true`
Oversize	size <250000000	Reject absurdly large matches (likely corrupt)

Managing via API

# List
curl -H "X-Api-Key: $KEY" http://bindery:8787/api/v1/customformat

# Create
curl -H "X-Api-Key: $KEY" -H "Content-Type: application/json" \
  -X POST http://bindery:8787/api/v1/customformat \
  -d '{
    "name": "RETAIL",
    "conditions": [
      { "type": "releaseTitle", "pattern": "(?i)\\bretail\\b", "required": true }
    ]
  }'

See also

• Quality profiles — format-type cutoff (EPUB / MOBI / …). This is the piece that IS enforced today.
• Delay profiles — protocol hold-off timer. Same "CRUD-only in v0.12" status.