Scored Sorting

Guide: Scored Sorting in AIOStreams

Scored Sorting is an advanced feature in AIOStreams that provides a powerful alternative to the traditional index-based "Preferred" sorting. Instead of relying on the order of your filter rules, Scored Sorting allows you to assign a quantitative score to streams, giving you precise, granular control over your results.

This system is highly flexible. You can use Ranked Regexes, Ranked Stream Expressions, or even both in combination with your existing "Preferred" filters. This guide will walk you through how to leverage this system effectively.

How Scored Sorting Works

The core concept is simple: streams are evaluated against a list of "Ranked" rules, and a score is accumulated. Unlike "Preferred" filters, where a stream matches only the first applicable rule, a stream can match multiple "Ranked" rules, and their scores are summed up.

This allows you to create a sophisticated scoring model where different stream characteristics contribute points towards a final score, which you can then use as a sorting criterion.

There are two types of ranked filters you can use:

1. Ranked Regex Filters: Assign scores based on regex patterns matching stream attributes like the filename.
2. Ranked Stream Expressions: Use the Stream Expression Language (SEL) to create complex conditional logic that assigns scores based on a stream's properties.

Choosing Your Approach

The system is designed to be modular. You are not forced to use one method over the other.

• Using Only Ranked Regexes: This is a great starting point if your scoring logic is based purely on text patterns in a stream's metadata (e.g., giving points for specific release groups or keywords). You can then add the Regex Score criterion to your sort configuration.
• Using Only Ranked Stream Expressions: If your logic is more complex and involves conditions based on stream properties (e.g., isAnime, bitrate, resolution) rather than just text matching, this is the way to go. You would then use the Stream Expression Score in your sort configuration.
• Using Both Together: You can use both systems simultaneously. However, it's important to remember that regexScore and seScore are two separate scores. You would need to add both Regex Score and Stream Expression Score to your sort configuration to sort by both values.
• Combining with Preferred Filters: Ranked filters do not replace Preferred filters. You can use both. For example, you might use Preferred filters to handle absolute must-have streams and then use Ranked filters to score and sort the rest.

A powerful advanced strategy is to use Ranked Regexes to "tag" streams with a score of 0, and then use Ranked Stream Expressions with the regexMatched() function to apply conditional scores based on which regexes were matched. This consolidates your final score into the {stream.seScore} variable, requiring only one sorting criterion (Stream Expression Score).

Setting Up Scored Sorting

1. Create Ranked Rules:

   • Navigate to Filters -> Regex or Stream Expression.
   • Scroll down to the Ranked section.
   • Add your rules. For each rule, provide:
     • Name: (Optional) A name for the rule. This is highly recommended for use in the custom formatter. For SEL, names are extracted from comments (/* My Rule Name */) in the expression itself. (see here for more details on naming expressions)
     • Expression/Regex: The logic to evaluate.
     • Score: The number of points to add to a stream's score if it matches the rule. This can be positive or negative.

2. Update Sort Configuration:

   • Go to Sorting.
   • Add the Stream Expression Score and/or Regex Score criteria to your list where appropriate.
   • Set the sort order (usually descending to put higher-scored streams first).
   • Position the criteria in your list according to your desired priority.

Displaying Scores in Your Formatter

To visualise the results of your scoring, you can use several special variables in your custom formatter templates.

Key Formatter Variables

• Scores:
  • {stream.regexScore} / {stream.seScore}: The final raw score for the stream.
  • {stream.nRegexScore} / {stream.nSeScore}: The score normalized to a 0-100 scale. The stream with the highest score in the results becomes 100. This is perfect for the star and pstar modifiers.
• Matched Rule Names:
  • {stream.regexMatched} / {stream.seMatched}: The name of the highest-ranking Preferred rule that was matched. For backward compatibility, {stream.regexMatched} will show the first matched Ranked rule name if no Preferred rule was matched.
  • {stream.rankedRegexMatched} / {stream.rseMatched}: An array of names for all Ranked rules that the stream matched. This is very useful for debugging or showing all factors that contributed to a stream's score.

Example: Using Star Ratings

A popular use case is to display a star rating based on a stream's score. The {::star} and {::pstar} modifiers are designed for this. Since they expect an input from 0-100, they work perfectly with the normalized score variables.

{stream.nSeScore::pstar}

If a stream has a normalized score of 75, this will display: ★★★★☆

This provides an intuitive, at-a-glance indicator of how well a stream matches your personal quality criteria.

Examples

Here is an example of advanced usage of the scoring system. It uses regexes and recommendations from TRaSH Guides for its scoring:

• Vidhin05/Releases-Regex