Skip to main content

Documentation Index

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

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

Riven does not blindly pick the first torrent it finds. Every result returned by a scraper backend is parsed and scored by RTN (Rank Torrent Name), an open-source library that extracts structured metadata from torrent titles and applies a configurable scoring model. Only the highest-ranked torrents — up to a configurable bucket limit — are kept for the downloader to act on.

​
What RTN Does

Given a raw title like Inception.2010.2160p.UHD.BluRay.x265.HDR.DTS-HD.MA.5.1-GROUP, RTN:
  1. Parses the title into a ParsedData object: resolution=2160p, codec=x265, hdr=True, audio=DTS-HD MA 5.1, quality=BluRay, etc.
  2. Validates the torrent against the item being scraped (correct title, year, season/episode numbers, country, language).
  3. Scores the torrent using the active BaseRankingModel (default: DefaultRanking) and the user’s RTNSettingsModel.
  4. Filters trash results (cam rips, watermarked, mismatched metadata) when remove_all_trash is enabled.
The result is a Torrent object with a numeric rank attribute. Higher rank = better match.

​
Configuration

RTN settings live under the ranking key in Riven’s settings. RTNSettingsModel extends the upstream SettingsModel from the rank-torrent-name library: 
{
  "ranking": {
    "resolutions": {
      "2160p": { "fetch": true },
      "1080p": { "fetch": true },
      "720p":  { "fetch": false },
      "480p":  { "fetch": false }
    },
    "options": {
      "remove_all_trash": true
    },
    "custom_ranks": {
      "hdr": { "fetch": true, "rank": 80 },
      "dolby_video": { "fetch": true, "rank": 100 },
      "aac": { "fetch": true, "rank": 20 }
    }
  }
}
Scraper-level settings that affect which torrents reach ranking at all are found under scraping: 
{
  "scraping": {
    "enable_aliases":    true,
    "bucket_limit":      5,
    "dubbed_anime_only": false,
    "max_failed_attempts": 0
  }
}
SettingDefaultEffect
scraping.enable_aliasestrueUse alternative title spellings (e.g. localised names) when matching torrent titles
scraping.bucket_limit5Maximum results kept per quality bucket after sorting
scraping.dubbed_anime_onlyfalseDiscard subtitled anime torrents; only keep dubbed ones
scraping.max_failed_attempts0 (unlimited)Move item to Failed after this many scrape cycles with no usable result

​
The Bucket System

After scoring, torrents are sorted by rank with sort_torrents(). The bucket limit (scraping.bucket_limit) caps how many torrents are retained per quality bucket (e.g. no more than 5 2160p results, 5 1080p results, etc.): 
sorted_torrents = sort_torrents(
    torrents,
    bucket_limit=scraping_settings.bucket_limit,
)
This prevents a single popular torrent from flooding the candidate list with dozens of nearly-identical re-packs, leaving room for genuinely different quality tiers.
Setting bucket_limit to 0 disables the cap entirely. All valid torrents are passed to the downloader. This is also the behaviour when triggering a manual scrape (where manual=True).

​
Per-Scrape Ranking Overrides

You can override ranking preferences for a single scrape without changing the global configuration. Pass a JSON-encoded ranking_overrides query parameter to the scrape endpoint: 
# Force only 1080p results for this scrape
GET /api/v1/scrape?item_id=42&ranking_overrides={"resolutions":["1080p"]}

# Prefer HDR and Dolby Vision for this item
GET /api/v1/scrape?item_id=42&ranking_overrides={"custom_ranks":["hdr","dolby_video"]}
The get_ranking_overrides() function in program/services/scrapers/shared.py takes the current global RTNSettingsModel, deep-copies it, and toggles fetch flags so only the listed items are enabled within each category: 
def get_ranking_overrides(
    ranking_overrides: dict[str, list[str]] | None,
) -> SettingsModel | None:
    ...
    for category, obj in groups:
        if category not in ranking_overrides:
            continue
        for key in obj.__class__.model_fields:
            should_enable = key in targets
            # toggle fetch flag
Ranking overrides are not persisted — they only affect the single API call they are attached to. To change the default behaviour for all future scrapes, update the global ranking configuration via POST /api/v1/settings.

​
Scrape Endpoint Reference

​
Get Streams for an Item

Returns all ranked streams for an item, optionally streaming results via SSE as each scraper backend completes: 
GET /api/v1/scrape
  ?item_id=42
  &ranking_overrides={"resolutions":["1080p","2160p"]}
  &min_filesize_override=2000        # MB
  &max_filesize_override=50000       # MB
  &stream=true                       # SSE mode
You can also identify the item by external ID instead of the Riven database ID: 
GET /api/v1/scrape?imdb_id=tt1375666&media_type=movie
GET /api/v1/scrape?tmdb_id=27205&media_type=movie
For custom title searches (useful for edge cases where metadata is wrong): 
GET /api/v1/scrape?item_id=42&custom_title=Inception+2010&custom_imdb_id=tt1375666
Using custom_title or custom_imdb_id clears the item’s stored TMDB/TVDB IDs and year for the duration of the request, relaxing the strict metadata filters. This is intentional — it allows the scraper to find results that would otherwise be filtered out due to a metadata mismatch.

​
Download a Specific Stream

Once you have identified the infohash you want to use, you can instruct Riven to download it directly without waiting for the automatic ranking to pick one: 
POST /api/v1/scrape/{item_id}/download
Content-Type: application/json

{
  "infohash": "abc123def456..."
}
This bypasses the ranking step entirely and sends the chosen torrent straight to the downloader.

​
Validation Filters Applied Before Ranking

RTN ranking only runs on torrents that pass a set of pre-filters in parse_results() (program/services/scrapers/shared.py). These filters ensure that:
  • Movies do not match torrents that contain season or episode markers.
  • Shows match torrents with at least 3 episodes and all expected seasons.
  • Seasons match torrents with the correct season number and all expected episodes.
  • Episodes match torrents containing the correct episode (or absolute) number.
  • Year is within ±1 year of the item’s release date (or the show’s premiere year for seasons/episodes).
  • Country variant (US, UK, AU, NZ) matches the item’s country code.
  • Anime results respect the dubbed_anime_only flag.
Torrents that fail any of these checks are discarded before rtn.rank() is ever called, keeping the candidate set clean and the ranking scores meaningful.

Build docs developers (and LLMs) love

Get started for freeTalk to us