Stream Expression Language - Viren070/AIOStreams GitHub Wiki

The Stream Expression Language (SEL) is a powerful feature in AIOStreams that allows you to write custom logic to filter, select, and evaluate lists of streams. It is used by features like Groups and Stream Selectors.

This page serves as the complete technical reference for SEL syntax, operators, and functions.

Syntax & Logic

An expression in SEL is a combination of constants, functions, and operators that resolves to a specific value. The required result depends on the context where you use the expression:

  • Group Conditions require the expression to resolve to true or false.
  • Stream Selectors require the expression to resolve to an array (list) of streams.

Operators

These are used to compare values and combine logic.

  • Comparison: == (equals), != (not equals), > (greater than), < (less than), >= (greater than or equal), <= (less than or equal)
  • Addition/Subtraction: + (add), - (subtract)
  • Logical: and, or, not
  • Conditional: x ? y : z (Ternary conditional - if x is true, then y else z)
  • Grouping: () (used to control the order of operations, just like in math).

Working with Stream Lists

Most functions either take a list of streams as input or produce a list of streams as output. You can chain functions together to create powerful, multi-step filters. This is called nesting.

Example of Nesting: To get a count of only the 4K streams that are also cached, you would nest the functions like this:

count(resolution(cached(streams), '4k'))

  • How it reads:
    1. cached(streams): First, get a list of only the cached streams.
    2. resolution(..., '4k'): Then, from that list, get a new list of only the ones that are 4K.
    3. count(...): Finally, count how many streams are in that final list.

Context-Specific Constants

The constants available to you depend on which AIOStreams feature you are using SEL with.

For Group Conditions:

  • previousStreams: A list of streams found by the last group that ran.
  • totalStreams: A list of all streams found by all groups that have run so far.
  • queryType: What you're searching for (e.g., "movie", "series").
  • previousGroupTimeTaken: How long the last group took (in milliseconds).
  • totalTimeTaken: Total time spent so far (in milliseconds).

For Stream Selectors:

  • streams: A list of all available streams that can be filtered.

Complete Function Reference

Utility Functions

  • count(streams: ParsedStream[])

    • Purpose: Returns the total number of stream objects in the provided streams array. Primarily used in Group Conditions.
    • Parameters:
      • streams: An array of stream objects (e.g., previousStreams, totalStreams, or the result of another filter function).
    • Returns: A number.
    • Example (Group Condition): count(previousStreams) < 5

  • negate(streamsToExclude: ParsedStream[], originalStreamList: ParsedStream[])

    • Purpose: Returns a new list of streams from originalStreamList that are NOT present in streamsToExclude.
    • Parameters:
      • streamsToExclude: An array of streams to exclude.
      • originalStreamList: The complete array of streams to filter from.
    • Returns: An array of stream objects.
    • Example: negate(quality(streams, 'CAM', 'TS'), streams) returns all streams except for CAM and TS quality.

  • merge(streamArrays: ParsedStream[]...)

    • Purpose: Combines multiple arrays of streams into a single array, removing any duplicate streams.
    • Parameters:
      • streamArrays: Two or more arrays of stream objects.
    • Returns: A single, merged array of stream objects.
    • Example: merge(visualTag(streams, 'DV'), audioTag(streams, 'Atmos')) returns a single list of all streams that are either Dolby Vision or have Atmos audio.

Filter Functions

  • regexMatched(streams: ParsedStream[], ...regexFilterNames: string[])

    • Purpose: Filters for streams that have matched one of your configured Regex Filters.
    • Parameters:
      • streams: An array of stream objects.
      • regexFilterNames (optional strings): If provided, returns streams that matched any of the specific Regex Filters by name. If omitted, returns streams that matched any Regex Filter.
    • Returns: An array of stream objects.
    • Example (any match): regexMatched(streams)
    • Example (specific match): regexMatched(streams, 'MyHighQualityFilter', 'MyOtherFilter')

  • regexMatchedInRange(streams: ParsedStream[], min: number, max: number)

    • Purpose: Filters for streams where the matched Regex Filter's index is within a specified range.
    • Parameters:
      • streams: An array of stream objects.
      • min (number): The minimum index (inclusive).
      • max (number): The maximum index (inclusive).
    • Returns: An array of stream objects.
    • Example: regexMatchedInRange(streams, 0, 5)

  • indexer(streams: ParsedStream[], ...indexerNames: string[])

    • Purpose: Filters streams by the name of the originating indexer.
    • Parameters:
      • streams: An array of stream objects.
      • indexerNames (strings): One or more indexer names (case-sensitive).
    • Returns: An array of stream objects.
    • Example: indexer(streams, '1337x', 'RARBG')

  • resolution(streams: ParsedStream[], ...resolutionNames: string[])

    • Purpose: Filters streams by video resolution.
    • Parameters:
      • streams: An array of stream objects.
      • resolutionNames (strings): One or more resolution strings.
        • Accepted Values: '2160p', '1440p', '1080p', '720p', '576p', '480p', '360p', '240p', '144p', 'Unknown'
    • Returns: An array of stream objects.
    • Example: resolution(streams, '2160p', '1080p')

  • quality(streams: ParsedStream[], ...qualityNames: string[])

    • Purpose: Filters streams by a general quality tag.
    • Parameters:
      • streams: An array of stream objects.
      • qualityNames (strings): One or more quality strings.
        • Accepted Values: 'Bluray REMUX', 'Bluray', 'WEB-DL', 'WEBRip', 'HDRip', 'HC HD-Rip', 'DVDRip', 'HDTV', 'CAM', 'TS', 'TC', 'SCR', 'Unknown'
    • Returns: An array of stream objects.
    • Example: quality(streams, 'Bluray', 'WEB-DL')

  • encode(streams: ParsedStream[], ...encodeNames: string[])

    • Purpose: Filters streams by video encoding format.
    • Parameters:
      • streams: An array of stream objects.
      • encodeNames (strings): One or more encoding formats (e.g., 'H.264', 'H.265', 'HEVC', 'x264', 'x265').
    • Returns: An array of stream objects.
    • Example: encode(streams, 'H.265', 'HEVC')

  • type(streams: ParsedStream[], ...streamTypes: string[])

    • Purpose: Filters streams by their type.
    • Parameters:
      • streams: An array of stream objects.
      • streamTypes (strings): One or more stream types.
        • Accepted Values: 'debrid', 'usenet', 'http', 'live', 'p2p', 'external', 'youtube'
    • Returns: An array of stream objects.
    • Example: type(streams, 'debrid', 'p2p')

  • visualTag(streams: ParsedStream[], ...visualTagNames: string[])

    • Purpose: Filters streams by visual tags (e.g., HDR, DV).
    • Parameters:
      • streams: An array of stream objects.
      • visualTagNames (strings): One or more visual tags (e.g., 'HDR', 'DV', 'HDR10').
    • Returns: An array of stream objects.
    • Example: visualTag(streams, 'HDR', 'DV')

  • audioTag(streams: ParsedStream[], ...audioTagNames: string[])

    • Purpose: Filters streams by audio format tags.
    • Parameters:
      • streams: An array of stream objects.
      • audioTagNames (strings): One or more audio tags (e.g., 'Atmos', 'DTS', 'AC3').
    • Returns: An array of stream objects.
    • Example: audioTag(streams, 'Atmos', 'DTS-HD MA')

  • audioChannels(streams: ParsedStream[], ...audioChannelsNames: string[])

    • Purpose: Filters streams by audio channel configuration.
    • Parameters:
      • streams: An array of stream objects.
      • audioChannelsNames (strings): One or more audio channel configurations (e.g., '5.1', '7.1', '2.0').
    • Returns: An array of stream objects.
    • Example: audioChannels(streams, '7.1', '5.1')

  • language(streams: ParsedStream[], ...languageNames: string[])

    • Purpose: Filters streams by language.
    • Parameters:
      • streams: An array of stream objects.
      • languageNames (strings): One or more languages (e.g., 'English', 'Spanish', 'French').
    • Returns: An array of stream objects.
    • Example: language(streams, 'English')

  • seeders(streams: ParsedStream[], minSeeders?: number, maxSeeders?: number)

    • Purpose: Filters streams by torrent seeder count.
    • Parameters:
      • streams: An array of stream objects.
      • minSeeders (optional number): Minimum seeders required.
      • maxSeeders (optional number): Maximum seeders allowed.
    • Returns: An array of stream objects.
    • Example (minimum): seeders(streams, 10)
    • Example (range): seeders(streams, 5, 100)

  • size(streams: ParsedStream[], minSize?: string | number, maxSize?: string | number)

    • Purpose: Filters streams by file size.
    • Parameters:
      • streams: An array of stream objects.
      • minSize (optional): Minimum size (e.g., '1GB', '500MB', or bytes as a number).
      • maxSize (optional): Maximum size (e.g., '5GB', '2TB', or bytes as a number).
    • Returns: An array of stream objects.
    • Example: size(streams, '1GB', '10GB')

  • service(streams: ParsedStream[], ...serviceNames: string[])

    • Purpose: Filters streams by a specific Debrid service.
    • Parameters:
      • streams: An array of stream objects.
      • serviceNames (strings): One or more Debrid service identifiers.
        • Accepted Values: 'realdebrid', 'debridlink', 'alldebrid', 'torbox', 'pikpak', 'seedr', 'offcloud', 'premiumize', 'easynews', 'easydebrid'
    • Returns: An array of stream objects.
    • Example: service(streams, 'realdebrid', 'premiumize')

  • cached(streams: ParsedStream[])

    • Purpose: Filters for streams that are marked as cached by a Debrid service.
    • Parameters:
      • streams: An array of stream objects.
    • Returns: An array of stream objects.
    • Example: cached(streams)

  • uncached(streams: ParsedStream[])

    • Purpose: Filters for streams that are not marked as cached.
    • Parameters:
      • streams: An array of stream objects.
    • Returns: An array of stream objects.
    • Example: uncached(streams)

  • releaseGroup(streams: ParsedStream[], ...releaseGroupNames: string[])

    • Purpose: Filters streams by the release group.
    • Parameters:
      • streams: An array of stream objects.
      • releaseGroupNames (strings): One or more release group names (case-sensitive).
    • Returns: An array of stream objects.
    • Example: releaseGroup(streams, 'FLUX', 'RARBG')

  • addon(streams: ParsedStream[], ...addonNames: string[])

    • Purpose: Filters streams by the addon name that provided it.
    • Parameters:
      • streams: An array of stream objects.
      • addonNames (strings): One or more addon names (case-sensitive).
    • Returns: An array of stream objects.
    • Example: addon(streams, 'Torrentio', 'Knightcrawler')

  • library(streams: ParsedStream[])

    • Purpose: Filters for streams marked as being from a personal library.
    • Parameters:
      • streams: An array of stream objects.
    • Returns: An array of stream objects.
    • Example: library(streams)