Riven’s ranking engine is the decision-making core that sits between your torrent indexers and your media library. Every candidate torrent goes through a three-stage pipeline — parse → rank → sort — that transforms a raw torrent name likeDocumentation 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.Matrix.1999.2160p.UHD.BluRay.REMUX.DV.TrueHD.Atmos.7.1-GROUP into a numeric score, then selects the highest-scoring torrent that passes all your configured filters.
The Ranking Pipeline
The engine processes each torrent through three sequential stages:parse() — The parser extracts structured metadata from the raw torrent name: resolution, quality source, video codec, HDR format, audio tracks, language tags, season/episode numbers, boolean flags (proper, repack, dubbed, etc.), and custom tags like trash, adult, and scene.
2. rank() — Each parsed attribute is looked up in the ranking model and its configured score is accumulated into a totalScore. Score contributions are tracked individually per dimension (quality, codec, HDR, audio, flags) so you can see exactly why a torrent ranked where it did.
3. sortTorrents() — Ranked results are filtered to only the enabled resolutions, then sorted descending by totalScore. An optional bucketLimit caps how many results are kept per resolution bucket.
Scoring Dimensions
Every torrent’s total score is the sum of contributions from these six dimensions. All values are integers — higher is better. A field set tonull in the ranking model means that attribute is disabling: if a torrent is detected to have that attribute, the torrent will not be fetched at all.
Quality / Source
Scores the release source:
remux, web-dl, web, bluray, hdtv, and rip variants. Remux starts at +10,000 in the default preset; HDTV drops to −5,000.Codec
Scores the video codec detected in the torrent name:
hevc (H.265), avc (H.264/x264), and av1. Codec aliases like h265, x264, and h264 are normalised automatically.HDR Format
Scores HDR metadata:
dolbyVision, hdr10plus, hdr, sdr, and bit10 (10-bit depth flag). Multiple HDR tags are additive — a Dolby Vision + HDR10+ release scores both.Audio Format
Scores the audio track(s):
atmos, truehd, dtsLossless, dolbyDigitalPlus, aac, flac, stereo, surround, and more. Multiple audio tracks are additive.Channel Layout
Scores audio channel configurations independently from the format:
surround (5.1/7.1), stereo (2.0), and mono. Channels and audio format scores are summed together.Extras & Flags
Scores boolean flags parsed from the torrent name:
proper, repack, edition, dubbed, uncensored, scene, hardcoded, subbed, retail, and more.Resolution Filtering
Resolutions are not scored — they are gating filters. Theresolutions settings object controls which resolutions are allowed through at all:
| Resolution Key | Maps To | Default |
|---|---|---|
r2160p | 4K / 2160p | false |
r1080p | 1080p / 1440p | true |
r720p | 720p | true |
r480p | 480p / 576p | false |
r360p | 360p / 240p | false |
unknown | No resolution tag | true |
default preset’s settings block only sets r2160p: true; it does not override the schema defaults for other keys, so the effective resolution set when using the default preset is r2160p, r1080p, r720p, and unknown all enabled.
Resolution values in torrent names are normalised before lookup.
4K maps to 2160p, 1440p maps to 1080p, 576p maps to 480p, and 240p maps to 360p.Title Matching
Before scoring, Riven compares the torrent’s parsed title against the correct media title using a Levenshtein ratio (fuzzy string similarity). The threshold is controlled byoptions.titleSimilarity (default 0.85).
- A ratio of
1.0means an exact match. - A ratio below the threshold causes the torrent to be rejected with a
TitleSimilarityError. - You can pass
aliases(alternate titles) to broaden matching — if the parsed title matches any alias above the threshold it passes.
Trash & Adult Content Detection
Riven has two automatic rejection paths that run before scoring: Trash detection (options.removeAllTrash: true) rejects torrents in three ways: (1) the quality source matches a known scene/piracy tag (cam, pdtv, r5, screener, telecine, or telesync); (2) the audio track contains an hq clean audio tag (a marker found on cam rips); or (3) the parser sets the boolean trash flag on the torrent name.
Adult content filtering (options.removeAdultContent: true) rejects torrents where the parser detects the adult flag in the torrent name.
Both checks run unconditionally as part of checkFetch() and add entries to the failedChecks set on the result. When removeAllTrash is enabled, any torrent with a non-empty failedChecks set is dropped.
Score Threshold
After scoring, Riven enforces a minimum score viaoptions.removeRanksUnder (default −10,000). Torrents whose totalScore falls at or below this value are rejected with a RankUnderThresholdError. This is useful when rip penalties (e.g. brrip: -10000) would push scores into unacceptable territory.
Where the Config Lives
The ranking configuration is a JSON file on disk. Its path is set by therankingConfigPath setting in Riven’s main configuration. If the file does not exist at startup, Riven creates a default config automatically:
Configuration Reference
Full reference for every field in the ranking config file, including all ranking model fields and settings options.
Presets
Details on the built-in
default preset and how to build a fully custom ranking model.