Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/rivenmedia/riven-ts/llms.txt

Use this file to discover all available pages before exploring further.

The ranking configuration is a JSON file at the path specified by the rankingConfigPath option in Riven’s main settings. Riven validates it at startup using a strict Zod schema, writing a minimal default file if none exists. Every field is optional — unspecified ranking model fields default to null (disabled), and unspecified settings fields use the schema defaults documented below.

​
Config File Structure

{
  "$schema": "https://raw.githubusercontent.com/rivenmedia/riven-ts/main/apps/riven/ranking-config.schema.json",
  "rankingModel": "default",
  "settings": {
    "resolutions": {
      "r2160p": true
    }
  }
}
The top-level shape is:
FieldTypeRequiredDescription
$schemastringNoJSON Schema URL for editor validation and autocompletion.
rankingModel"default" | objectNoUse the built-in preset string "default", or supply a full ranking model object. Defaults to "default" if omitted.
settingsSettings objectNoOverrides for resolution, language, and option settings. Merged on top of the active preset’s settings when a preset string is used.
When rankingModel is set to the string "default", Riven loads the built-in default preset values and then merges any settings overrides on top. When rankingModel is an object, the preset is bypassed entirely and the object is used as-is (with null for any unspecified keys).

​
Ranking Model Fields

All ranking model fields accept an integer or null. null means the attribute is disabled — any torrent detected with that attribute will be rejected. A value of 0 means the attribute is allowed but contributes nothing to the score.

​
Quality Group

These fields score the release source detected in the torrent name.
​
remux
integer | null
default:"null"
Blu-ray or UHD Blu-ray lossless remux. Mapped from quality strings remux and bluray remux. Default preset value: 10000.
​
webdl
integer | null
default:"null"
Web-DL release (downloaded directly from a streaming service). Mapped from quality string web-dl. Default preset value: 200.
​
web
integer | null
default:"null"
Web release (generic web source). Mapped from quality string web. Default preset value: 100.
​
bluray
integer | null
default:"null"
Standard Blu-ray encode (not remux). Mapped from quality string bluray. Default preset value: 100.
​
hdtv
integer | null
default:"null"
HDTV broadcast capture. Default preset value: −5000.
​
dvd
integer | null
default:"null"
DVD source. Default preset value: null.
​
vhs
integer | null
default:"null"
VHS source. Default preset value: null.
​
webmux
integer | null
default:"null"
Web mux release. Default preset value: null.

​
Codec Group

These fields score the video codec identified in the torrent name. Codec aliases are normalised automatically (e.g. h265 and x265 both map to hevc; h264 and x264 both map to avc).
​
hevc
integer | null
default:"null"
HEVC / H.265 / x265 codec. Default preset value: 500.
​
avc
integer | null
default:"null"
AVC / H.264 / x264 codec. Default preset value: 500.
​
av1
integer | null
default:"null"
AV1 codec. Default preset value: 500.
​
xvid
integer | null
default:"null"
XviD codec. Default preset value: null.
​
mpeg
integer | null
default:"null"
MPEG codec. Default preset value: null.

​
Rips Group

These fields score rip-type releases. Most rips are penalised heavily in the default preset.
​
webrip
integer | null
default:"null"
Web rip (screen-captured from a streaming service). Default preset value: −1000.
​
brrip
integer | null
default:"null"
Blu-ray rip (re-encoded from a Blu-ray). Default preset value: −10000.
​
hdrip
integer | null
default:"null"
HD rip (generic). Default preset value: −10000.
​
bdrip
integer | null
default:"null"
BD rip (re-encoded from a Blu-ray disc). Default preset value: null.
​
dvdrip
integer | null
default:"null"
DVD rip. Default preset value: null.
​
uhdrip
integer | null
default:"null"
UHD rip. Default preset value: null.
​
webdlrip
integer | null
default:"null"
Web-DL rip. Default preset value: null.
​
vhsrip
integer | null
default:"null"
VHS rip. Default preset value: null.
​
ppvrip
integer | null
default:"null"
PPV (pay-per-view) rip. Default preset value: null.
​
tvrip
integer | null
default:"null"
TV broadcast rip (SD). Default preset value: null.

​
HDR Group

HDR fields score the dynamic range metadata detected in the torrent name. Multiple HDR tags on a single torrent are additive.
​
dolbyVision
integer | null
default:"null"
Dolby Vision HDR (tag: DV). Default preset value: 3000.
​
hdr10plus
integer | null
default:"null"
HDR10+ (tag: HDR10+). Default preset value: 2100.
​
hdr
integer | null
default:"null"
Standard HDR10 (tag: HDR). Default preset value: 2000.
​
bit10
integer | null
default:"null"
10-bit depth flag (independent of HDR format). Default preset value: 100.
​
sdr
integer | null
default:"null"
Standard dynamic range (explicitly tagged SDR). Default preset value: 0.

​
Audio Group

Audio fields score the audio track format(s) and channel layout. Multiple audio tracks on a single torrent are additive.
​
atmos
integer | null
default:"null"
Dolby Atmos object-based audio. Default preset value: 1000.
​
truehd
integer | null
default:"null"
Dolby TrueHD lossless audio. Default preset value: 2000.
​
dtsLossless
integer | null
default:"null"
DTS-HD Master Audio / DTS:X lossless. Default preset value: 2000.
​
dtsLossy
integer | null
default:"null"
Standard DTS lossy audio. Default preset value: 100.
​
dolbyDigitalPlus
integer | null
default:"null"
Dolby Digital Plus / E-AC-3 / DD+ / EAC3. Default preset value: 150.
​
dolbyDigital
integer | null
default:"null"
Dolby Digital / AC-3 / DD. Default preset value: 50.
​
aac
integer | null
default:"null"
AAC audio. Default preset value: 100.
​
flac
integer | null
default:"null"
FLAC lossless audio. Default preset value: 0.
​
stereo
integer | null
default:"null"
Stereo / 2.0 channel layout. Default preset value: 0.
​
surround
integer | null
default:"null"
Surround sound channel layout (5.1 or 7.1). Default preset value: 0.
​
mono
integer | null
default:"null"
Mono audio. Default preset value: null.
​
mp3
integer | null
default:"null"
MP3 audio. Default preset value: null.

​
Extras Group

Extra fields score boolean flags that are parsed from the torrent name. These accumulate into the flags score part.
​
proper
integer | null
default:"null"
Proper re-release (corrects a previous release defect). Default preset value: 20.
​
repack
integer | null
default:"null"
Repack re-release (replaces a prior release from the same group). Default preset value: 20.
​
edition
integer | null
default:"null"
Special edition (Director’s Cut, Extended, etc.). Default preset value: 100.
​
dubbed
integer | null
default:"null"
Dubbed audio track detected. Default preset value: −1000.
​
uncensored
integer | null
default:"null"
Uncensored release flag. Default preset value: 0.
​
scene
integer | null
default:"null"
Scene release flag. Default preset value: 0.
​
hardcoded
integer | null
default:"null"
Hardcoded subtitles detected. Default preset value: 0.
​
subbed
integer | null
default:"null"
External subtitles included. Default preset value: 0.
​
network
integer | null
default:"null"
Network tag present (e.g. streaming service name). Default preset value: 0.
​
retail
integer | null
default:"null"
Retail release flag. Default preset value: 0.
​
upscaled
integer | null
default:"null"
AI-upscaled release. Default preset value: null.
​
threeD
integer | null
default:"null"
3D release. Default preset value: null.
​
converted
integer | null
default:"null"
Format-converted release. Default preset value: null.
​
documentary
integer | null
default:"null"
Documentary flag. Default preset value: null.
​
commentary
integer | null
default:"null"
Commentary track release. Default preset value: null.

​
Trash Group

Trash fields cover low-quality or scene-piracy release types. The six quality tags cam, pdtv, r5, screener, telecine, and telesync are hard-rejected by the trash handler when removeAllTrash is enabled, regardless of the ranking model value. All other fields in this group are rejected only when set to null in the ranking model (the default). Setting any field to a non-null integer allows fetching torrents with that tag and scores them by that value.
​
cam
integer | null
default:"null"
Cam rip (recorded in a cinema). Default preset value: null (rejected).
​
screener
integer | null
default:"null"
Screener copy. Default preset value: null (rejected).
​
telecine
integer | null
default:"null"
Telecine copy. Default preset value: null (rejected).
​
telesync
integer | null
default:"null"
Telesync copy. Default preset value: null (rejected).
​
r5
integer | null
default:"null"
R5 DVD copy. Default preset value: null (rejected).
​
pdtv
integer | null
default:"null"
PDTV broadcast capture. Default preset value: null (rejected).
​
cleanAudio
integer | null
default:"null"
HQ clean audio tag (used on cam rips). Default preset value: null (rejected).
​
site
integer | null
default:"null"
Site watermark tag. Default preset value: null (rejected).
​
size
integer | null
default:"null"
Size-encoded tag. Default preset value: null (rejected).
​
satrip
integer | null
default:"null"
Satellite broadcast rip. Default preset value: null (rejected).

​
Settings Fields

Settings control filtering behaviour independent of the ranking model scores.

​
Resolution Settings

​
settings.resolutions
object
Controls which resolutions are allowed through. Torrents whose parsed resolution maps to a disabled bucket are rejected before scoring.
KeyResolution(s)Schema DefaultDefault Preset
r2160p2160p, 4Kfalsetrue
r1080p1080p, 1440ptrue(not set)
r720p720ptrue(not set)
r480p480p, 576pfalse(not set)
r360p360p, 240pfalse(not set)
unknownNo resolution tagtrue(not set)

​
Language Settings

​
settings.languages
object
Controls language-based filtering.
​
settings.languages.required
string[]
default:"[]"
Languages that must be present. Torrents without a required language are rejected. Use BCP-47 language codes (e.g. "en", "fr") or group names "anime", "nonAnime", "common", "all".
​
settings.languages.allowed
string[]
default:"[]"
Languages that are explicitly allowed (non-English). When allowEnglishInLanguages is true, English torrents always pass regardless of this list.
​
settings.languages.exclude
string[]
default:"[]"
Languages that cause a torrent to be rejected if detected.
​
settings.languages.preferred
string[]
default:"[]"
Languages that add a +10,000 bonus to the total score if matched.

​
Options Settings

​
settings.options
object
Fine-grained filtering options.
​
settings.options.removeAllTrash
boolean
default:"true"
Master switch for trash/adult filtering, title similarity checking, and the rank threshold. Disable only for debugging.
​
settings.options.removeRanksUnder
number
default:"-10000"
Torrents scoring below this value are rejected. Acts as a safety net against heavily penalised releases.
​
settings.options.titleSimilarity
number
default:"0.85"
Minimum Levenshtein ratio (0–1) between the torrent’s parsed title and the correct media title. Torrents below this threshold are rejected.
​
settings.options.removeAdultContent
boolean
default:"true"
Reject torrents where the parser detects the adult flag.
​
settings.options.removeUnknownLanguages
boolean
default:"false"
Reject torrents that have no detectable language tag.
​
settings.options.allowEnglishInLanguages
boolean
default:"true"
When true, English-language torrents always pass language checks regardless of the allowed or exclude lists.

​
Pattern Settings

​
settings.require
string[]
default:"[]"
Regular expression patterns (as strings). A torrent must match at least one pattern to be fetched. Case-insensitive by default; wrap in /…/ for a case-sensitive regex.
​
settings.exclude
string[]
default:"[]"
Regular expression patterns. A torrent matching any exclude pattern is rejected regardless of its score.
​
settings.preferred
string[]
default:"[]"
Regular expression patterns. A torrent matching any preferred pattern receives a +10,000 bonus to its total score.

​
Complete Custom Config Example

This example enables 4K-only, requires English, excludes dubbed releases, and builds a full custom ranking model from scratch rather than using the default preset: 
{
  "$schema": "https://raw.githubusercontent.com/rivenmedia/riven-ts/main/apps/riven/ranking-config.schema.json",
  "settings": {
    "resolutions": {
      "r2160p": true,
      "r1080p": false,
      "r720p": false,
      "r480p": false,
      "r360p": false,
      "unknown": false
    },
    "languages": {
      "required": [],
      "allowed": [],
      "exclude": [],
      "preferred": []
    },
    "options": {
      "removeAllTrash": true,
      "removeRanksUnder": -10000,
      "titleSimilarity": 0.85,
      "removeAdultContent": true,
      "removeUnknownLanguages": false,
      "allowEnglishInLanguages": true
    },
    "require": [],
    "exclude": ["dubbed"],
    "preferred": []
  },
  "rankingModel": {
    "remux": 10000,
    "webdl": 200,
    "web": 100,
    "bluray": 100,
    "hdtv": -5000,
    "webrip": -1000,
    "brrip": -10000,
    "hdrip": -10000,
    "hevc": 500,
    "avc": 500,
    "av1": 500,
    "dolbyVision": 3000,
    "hdr10plus": 2100,
    "hdr": 2000,
    "bit10": 100,
    "sdr": 0,
    "atmos": 1000,
    "truehd": 2000,
    "dtsLossless": 2000,
    "dolbyDigitalPlus": 150,
    "dtsLossy": 100,
    "aac": 100,
    "dolbyDigital": 50,
    "flac": 0,
    "stereo": 0,
    "surround": 0,
    "proper": 20,
    "repack": 20,
    "edition": 100,
    "dubbed": -1000
  }
}
When rankingModel is an object, the default preset is not applied. Every field you omit defaults to null, which means torrents with that detected attribute will be rejected. Make sure to explicitly set all attributes you want to allow.

Build docs developers (and LLMs) love

Get started for freeTalk to us