Filters & Scoring

Control exactly what content gets added to your library with filters and scoring.

Overview

Filters

Binary Decision

Block or allow - content either passes or fails.

Used for: Genres, certifications, runtime, release year

Scoring

Weighted Ranking

0-100 score - content is ranked by quality.

Used for: IMDb/Trakt/TMDB ratings, vote counts, popularity

Filter System

Filters are applied before scoring. Content that fails filters is immediately rejected.

Global vs Per-Job Filters

Global Filters

Apply to all jobs across the board:

filters:
  global:
    blocking:
      certifications:
        - "R"
        - "NC-17"
      genres:
        - "horror"
    required:
      min_runtime: 90

Use for: Consistent rules across all content (e.g., family-friendly server)

Per-Job Filters

Override global filters for specific jobs:

jobs:
  family_movies:
    filters:
      required:
        certifications: ["G", "PG", "PG-13"]
      blocking:
        genres: ["horror", "thriller"]

  adults_only_night:
    filters:
      required:
        certifications: ["R"]
      min_rating: 7.0

Use for: Job-specific requirements that differ from global rules

Combining Filters

Job filters override global filters for matching keys:

filters:
  global:
    required:
      min_runtime: 90  # Global: 90min minimum

jobs:
  short_films:
    filters:
      required:
        max_runtime: 60  # This job: override to 60min max

Note

Non-conflicting filters are combined. Conflicting ones are replaced by job-specific values.

Available Filters

Certifications

Control content ratings (movie ratings, TV ratings).

Required certifications (only allow these):

filters:
  movies:
    required:
      certifications: ["G", "PG", "PG-13"]

  shows:
    required:
      certifications: ["TV-Y", "TV-G", "TV-PG"]

Blocked certifications (reject these):

filters:
  global:
    blocking:
      certifications:
        - "NC-17"
        - "TV-MA"

Movie Certifications:

• G - General Audiences
• PG - Parental Guidance
• PG-13 - Parents Strongly Cautioned
• R - Restricted
• NC-17 - Adults Only

TV Certifications:

• TV-Y - All Children
• TV-Y7 - Children 7+
• TV-G - General Audience
• TV-PG - Parental Guidance
• TV-14 - Parents Strongly Cautioned
• TV-MA - Mature Audience

Genres

Control content by genre.

Required genres (must have at least one):

filters:
  movies:
    required:
      genres:
        - "science-fiction"
        - "fantasy"

Blocked genres (reject if has any):

filters:
  global:
    blocking:
      genres:
        - "horror"
        - "documentary"
        - "reality"

Common genres:

• Movies: action, adventure, comedy, drama, science-fiction, fantasy, thriller, horror, romance, documentary
• TV: drama, comedy, reality, animation, documentary, talk-show, game-show

Tip

Use lowercase with hyphens: science-fiction not Science Fiction

Runtime

Control content length (in minutes).

filters:
  movies:
    required:
      min_runtime: 90      # Feature films
      max_runtime: 180     # Under 3 hours

  shows:
    required:
      min_episode_runtime: 20   # No shorts
      max_episode_runtime: 60   # Standard episodes

Common use cases:

• Feature films only: min_runtime: 90
• No epics: max_runtime: 150
• Standard TV: min_episode_runtime: 20, max_episode_runtime: 60
• Anime episodes: min_episode_runtime: 22, max_episode_runtime: 25

Release Year

Control how old/new content can be.

filters:
  required:
    min_year: 2020       # Only 2020 onwards
    max_year: 2024       # Nothing from 2025+

Use cases:

• Modern only: min_year: 2015
• Classics: max_year: 1999
• Current year: min_year: 2026, max_year: 2026

Languages & Countries

Control content origin.

filters:
  required:
    languages: ["en"]                # English only
    countries: ["us", "gb", "ca"]    # US, UK, Canada

Blocking:

filters:
  blocking:
    languages: ["ja", "ko"]          # No Japanese or Korean
    countries: ["cn"]                # No Chinese productions

Common language codes:

• en - English
• es - Spanish
• fr - French
• de - German
• ja - Japanese
• ko - Korean
• zh - Chinese

Networks

Control TV networks (shows only).

filters:
  shows:
    required:
      networks:
        - "HBO"
        - "Netflix"
        - "Apple TV+"

Blocking networks:

filters:
  shows:
    blocking:
      networks:
        - "Adult Swim"
        - "MTV"

Scoring System

0-100 Scale

Content that passes filters is scored from 0-100 based on weighted ratings.

Score Components

Rating Sources

Four rating sources can be weighted:

scoring:
  imdb_rating_weight: 0.4      # IMDb rating (40%)
  trakt_rating_weight: 0.3     # Trakt rating (30%)
  tmdb_rating_weight: 0.2      # TMDB rating (20%)
  metacritic_weight: 0.1       # Metacritic (10%)

Weights must sum to 1.0

Note

If a source is unavailable (e.g., no Metacritic score), the other weights are proportionally increased.

Vote Requirements

Require minimum votes for reliable ratings:

scoring:
  min_imdb_votes: 5000      # At least 5,000 votes
  min_trakt_votes: 100      # At least 100 votes

Without minimum votes, content with few votes can have inflated ratings.

Example:

• Movie A: 9.5 rating (10 votes) ❌ Rejected
• Movie B: 8.2 rating (50,000 votes) ✅ Accepted

Release Recency

Set minimum release year:

scoring:
  min_year: 1990     # No content before 1990

Different from filters: This is scoring-based, not a hard block.

Default Score

Fallback score when ratings unavailable:

scoring:
  default_score: 50     # Middle ground

Use cases:

• New releases without ratings yet
• Content from sources without rating data
• Unreleased anticipated content

Threshold Score

Job-Specific

Each job has a threshold_score - only content scoring above this is added.

jobs:
  quality_movies:
    threshold_score: 75    # Only scores 75+ added

  everything_movies:
    threshold_score: 50    # More permissive

Typical thresholds:

• Very Strict: 80-90
• Quality Focus: 70-79
• Balanced: 60-69
• Permissive: 50-59
• Very Permissive: <50

Configuration Examples

Family Server

Goal: Kid-safe content only.

scoring:
  imdb_rating_weight: 0.6
  trakt_rating_weight: 0.4
  min_imdb_votes: 1000
  default_score: 50

filters:
  global:
    blocking:
      certifications:
        - "R"
        - "NC-17"
        - "TV-MA"
        - "TV-14"
      genres:
        - "horror"
        - "thriller"
    required:
      certifications:
        - "G"
        - "PG"
        - "PG-13"
        - "TV-Y"
        - "TV-G"
        - "TV-PG"

jobs:
  family_movies:
    threshold_score: 65

Quality Curator

Goal: Only highly-rated, proven content.

scoring:
  imdb_rating_weight: 0.4
  trakt_rating_weight: 0.3
  tmdb_rating_weight: 0.2
  metacritic_weight: 0.1
  min_imdb_votes: 50000      # Require popularity
  min_year: 1990

filters:
  movies:
    required:
      min_runtime: 90
    blocking:
      genres:
        - "documentary"
        - "reality"

jobs:
  curated_movies:
    threshold_score: 80      # Very high bar

Genre Specialist

Goal: Sci-fi and fantasy only.

scoring:
  imdb_rating_weight: 0.5
  trakt_rating_weight: 0.5
  min_imdb_votes: 5000

filters:
  global:
    required:
      genres:
        - "science-fiction"
        - "fantasy"
    blocking:
      genres:
        - "romance"      # No romantic fantasy
        - "comedy"       # Serious only

jobs:
  scifi_movies:
    threshold_score: 70

Current Releases

Goal: Latest theatrical and streaming releases.

scoring:
  imdb_rating_weight: 0.3
  trakt_rating_weight: 0.4
  tmdb_rating_weight: 0.3
  min_imdb_votes: 500        # Lower for new releases
  min_year: 2024             # Current year only
  default_score: 60          # Give new content a chance

filters:
  movies:
    required:
      min_year: 2024
      min_runtime: 75

jobs:
  new_releases:
    threshold_score: 60      # Medium bar for new content

Testing Filters

Always Preview First

Use the preview feature to see what passes your filters before enabling jobs.

Web UI

1. Configure filters in the Config page
2. Go to Jobs page
3. Configure a test job
4. Click Preview
5. Review results:
   • ✅ Items that pass (will be added)
   • ❌ Items filtered out (with reasons)
   • 📊 Score distribution
6. Adjust filters based on results

API

curl -X POST http://localhost:9090/api/v1/jobs/preview/trending-movies

Response shows:

{
  "would_add": [...],
  "filtered_out": [
    {
      "title": "Horror Movie",
      "reason": "Blocked genre: horror"
    },
    {
      "title": "Low-Rated Film",
      "score": 45,
      "reason": "Score below threshold (65)"
    }
  ]
}

Common Patterns

Family-Friendly

filters:
  blocking:
    certifications: ["R", "NC-17", "TV-MA"]
    genres: ["horror"]

Quality Only

scoring:
  min_imdb_votes: 50000
jobs:
  quality:
    threshold_score: 80

Recent Content

filters:
  required:
    min_year: 2020
scoring:
  min_year: 2020

English Only

filters:
  required:
    languages: ["en"]
    countries: ["us", "gb", "ca"]

Feature Films

filters:
  movies:
    required:
      min_runtime: 90
      max_runtime: 180

Genre Specific

filters:
  required:
    genres: ["action", "adventure"]
  blocking:
    genres: ["romance", "documentary"]

Best Practices

1. Start strict, then loosen

   Begin with high thresholds and tight filters, then relax as needed.

2. Use previews extensively

   Always preview before enabling jobs to avoid surprises.

3. Combine filters and scoring

   Use filters for hard requirements, scoring for quality ranking.

4. Monitor the activity log

   Check weekly to see what’s being added and adjust.

5. Set realistic vote minimums

   For new content: 500-1000 votes. For established: 5000-10000 votes.

6. Don’t over-filter

   Too many filters = nothing gets added. Find the right balance.

Troubleshooting

Nothing Being Added?

Common issues:

1. Threshold too high - Try lowering to 60-65
2. Filters too strict - Remove some blocking filters
3. Vote requirement too high - Lower min_votes for new content
4. Already in library - Check activity log

Debug steps:

# Preview job to see what's being filtered
curl -X POST http://localhost:9090/api/v1/jobs/preview/trending-movies

# Check logs
docker logs blockbusterr | grep filtered

Next Steps

Jobs Overview

Learn about all 17 job types

Smart Jobs

Adaptive scoring for smart popular jobs

Use Cases

See real-world filter configurations

Integration Modes

Choose Direct or Jellyseerr mode