Skip to content

Dumb Builders

This builder finds its items by using the features of Plex.

No configuration is required for these builders.

The results of these builders are static and require Kometa to re-run in order to update.

Attribute Description Works with Movies Works with Shows Works with Playlists and Custom Sort
plex_all Gets every movie/show in your library. Useful with Filters
plex_watchlist Gets every movie/show in your Watchlist.
plex_pilots Gets the first episode of every show in your library
plex_collectionless Gets every movie/show that is not in a collection
plex_search Gets every movie/show based on the search parameters provided

Plex All

Finds every item in your library. Useful with Filters.

The expected input is either true or false.

collections:
  9.0 Movies:
    plex_all: true
    filters:
      user_rating.gte: 9

Plex Watchlist

Finds every item in your Watchlist.

The expected input is the sort you want returned. It defaults to added.asc.

Watchlist Sort Options

Sort Option Description
title.asc
title.desc
Sort by Title
release.asc
release.desc
Sort by Release Date (Originally Available)
critic_rating.asc
critic_rating.desc
Sort by Critic Rating
added.asc
added.desc
Sort by Date Added to your Watchlist

The sync_mode: sync and collection_order: custom Setting are recommended.

collections:
  My Watchlist:
    plex_watchlist: critic_rating.desc
    collection_order: custom
    sync_mode: sync

Plex Pilots

Gets the first episode of every show in your library. This only works with builder_level: episode

collections:
  Pilots:
    builder_level: episode
    plex_pilots: true

Plex Collectionless

This is not needed if you're using Smart Label Collections.

Finds every item that is not in a collection unless the collection is in the exclusion list. This is a special collection type to help keep your library looking correct. When items in your library are in multiple collections it can mess up how they're displayed in your library.

For Example, if you have a Marvel Cinematic Universe Collection set to Show this collection and its items and an Iron Man Collection set to Hide items in this collection what happens is the show overrides the hide, and you end up with both the collections and the 3 Iron Man movies all displaying.

Alternatively, if you set the Marvel Cinematic Universe Collection to Hide items in this collection then movies without a collection like The Incredible Hulk will be hidden from the library view.

To combat the problem above you set all collections to Hide items in this collection then create a collection set to Hide collection and put every movie that you still want to display in that collection.

With the variability of collections generated by the Kometa maintaining a collection like this becomes very difficult, so in order to automate it, you can use plex_collectionless. You just have to tell it what collections to exclude or what collection prefixes to exclude.

There are two attributes for plex_collectionless:

  • exclude: Exclude these Collections from being considered for collectionless.
  • exclude_prefix Exclude Collections whose title or sort title starts with a prefix from being considered for collectionless.

At least one exclusion is required.

collections:
  Collectionless:
    plex_collectionless:
      exclude_prefix:
        - "!"
        - "+"
        - "~"
      exclude: 
        - Marvel Cinematic Universe
    sort_title: ~_Collectionless
    collection_order: alpha
    collection_mode: hide
  • Both exclude and exclude_prefix can take multiple values as a List.
  • This is a known issue with Plex Collection and there is a Feature Suggestion detailing the issue more on their forms.

Uses Plex's Advanced Filters to find all items based on the search parameters provided.

Any Advanced Filter made using the Plex UI should be able to be recreated using plex_search. If you're having trouble getting plex_search to work correctly, build the collection you want inside of Plex's Advanced Filters and take a screenshot of the parameters in the Plex UI and post it in either the Discussions or on Discord, and I'll do my best to help you.

like Plex's Advanced Filters you have to start each search with either any or all as a base. You can only have one base attribute and all search attributes must be under the base.

Inside the base attribute you can use any search below or nest more any or all. You can have as many nested any or all next to each other as you want. If using multiple any or all you will have to do so in the form of a list.

Note: To search by season, episode, album, or track you must use the builder_level Setting to change the type of items the collection holds.

There are a couple other attributes you can have at the top level only along with the base attribute are:

Special Attributes

Attribute Description & Values
limit Description: The max number of item for the search.
Default: all
Values: all or a number greater than 0
sort_by Description: This will control how the filter is sorted in your library. You can do a multi-level sort using a list.
Default: random
Values: Any sort options for your search type in the Sorts Options Table
type PLAYLIST SEARCHES ONLY Description: Allows different types of media to be searched for.
Default: movie, show, or artist depending on library type
Values: movie, show, season, episode, artist, album or track
validate Description: Determines if a collection/playlist will fail on a validation error
Default: true
Values: true or false

Sort Options

Sort Option Description Movies Shows Seasons Episodes Artists Albums Tracks
title.asc
title.desc
Sort by Title
season.asc
season.desc
Sort by Season
show.asc
show.desc
Sort by Show
album_artist.asc
album_artist.desc
Sort by Album Artist
artist.asc
artist.desc
Sort by Artist
album.asc
album.desc
Sort by Album
year.asc
year.desc
Sort by Year
release.asc
release.desc
Sort by Release Date (Originally Available)
episode_release.asc
episode_release.desc
Sort by Episode Release Date (Originally Available)
critic_rating.asc
critic_rating.desc
Sort by Critic Rating
audience_rating.asc
audience_rating.desc
Sort by Audience Rating
user_rating.asc
user_rating.desc
Sort by User Rating
content_rating.asc
content_rating.desc
Sort by Content Rating
duration.asc
duration.desc
Sort by Duration
progress.asc
progress.desc
Sort by Progress
played.asc
played.desc
Sort by Date Last Played
plays.asc
plays.desc
Sort by Number of Plays
unplayed.asc
unplayed.desc
Sort by Unplayed
episode_added.asc
episode_added.desc
Sort by Last Episode Date Added
added.asc
added.desc
Sort by Date Added
viewed.asc
viewed.desc
Sort by Date Last Viewed
rated.asc
rated.desc
Sort by Date Last Rated
popularity.asc
popularity.desc
Sort by Popularity
resolution.asc
resolution.desc
Sort by Resolution
bitrate.asc
bitrate.desc
Sort by Bitrate
random Sort by Random

Searches

There are three fields per search option when using Plex's Advanced Filters in the Web UI.

  1. Attribute: What attribute you wish to search.
  2. Modifier: Which modifier to use.
  3. Value: Actual value to search.

Example: Attribute.Modifier: Value

String Searches

String searches can be used with either no modifier or with .not, .is, .isnot, .begins, or .ends.

String search can take multiple values only as a list.

String Modifiers

String Modifier Description Plex Web UI Display
No Modifier Matches every item where the attribute contains the given string contains
.not Matches every item where the attribute does not contain the given string does not contain
.is Matches every item where the attribute exactly matches the given string is
.isnot Matches every item where the attribute does not exactly match the given string is not
.begins Matches every item where the attribute begins with the given string begins with
.ends Matches every item where the attribute ends with the given string ends with

String Attributes

String Search Description Movie
Libraries
Show
Libraries
Music
Libraries
title Uses the title attribute to match
episode_title Uses the title attribute of the show's episodes to match
studio Uses the studio attribute to match
edition Uses the edition attribute to match
artist_title Uses the Artist's Title attribute to match
album_title Uses the Album's Title attribute to match
track_title Uses the Track's Title attribute to match
album_record_label Uses the Album's Record Label attribute to match

Tag Searches

Tag searches can be used with either no modifier or with .not except for decade and resolution which can only be used with no modifier.

Tag search can take multiple values as a list or a comma-separated string.

Tag Modifiers

Tag Modifier Description Plex Web UI Display
No Modifier Matches every item where the attribute matches the given string is
.not Matches every item where the attribute does not match the given string is not
.regex Matches every item where one value of this attribute matches the regex. N/A

Tag Attributes

Tag Search Description Movie
Libraries
Show
Libraries
Music
Libraries
actor Uses the actor tags to match
episode_actor Uses the episode actor tags to match
audio_language Uses the audio language tags to match
collection Uses the collection tags to match for top level collections
season_collection Uses the collection tags to match for season collections
episode_collection Uses the collection tags to match for episode collections
content_rating Uses the content rating tags to match
country Uses the country tags to match
decade1 Uses the year tag to match the decade
director Uses the director tags to match
genre Uses the genre tags to match
label Uses the label tags to match for top level collections
season_label Uses the label tags to match for season collections
episode_label Uses the label tags to match for episode collections
network Uses the network tags to match
Only works with the New Plex TV Agent
producer Uses the producer tags to match
resolution Uses the resolution tags to match
subtitle_language Uses the subtitle language tags to match
writer Uses the writer tags to match
year1 Uses the year tag to match
episode_year1 Uses the year tag to match
artist_genre Uses the Artist's Genre attribute to match
artist_collection Uses the Artist's Collection attribute to match
artist_country Uses the Artist's Country attribute to match
artist_mood Uses the Artist's Mood attribute to match
artist_style Uses the Artist's Style attribute to match
artist_label Uses the Artist's Label attribute to match
album_genre Uses the Album's Genre attribute to match
album_mood Uses the Album's Mood attribute to match
album_style Uses the Album's Style attribute to match
album_format Uses the Album's Format attribute to match
album_type Uses the Album's Type attribute to match
album_collection Uses the Album's Collection attribute to match
album_source Uses the Album's Source attribute to match
album_label Uses the Album's Label attribute to match
track_mood Uses the Track's Mood attribute to match
track_source Uses the Track's Source attribute to match
track_label Uses the Track's Label attribute to match

1 You can use current_year to have Kometa use the current years value. This can be combined with a -# at the end to subtract that number of years. i.e. current_year-2

Date Searches

Date searches can be used with either no modifier or with .not, .before, or .after.

No date search can take multiple values.

Date Modifiers

Date Modifier Description Plex Web UI Display
No Modifier Matches every item where the date attribute is in the last X days
Format: number of days
Example: 30
is in the last
.not Matches every item where the date attribute is not in the last X days
Format: number of days
Example: 30
is not in the last
.before Matches every item where the date attribute is before the given date
Format: MM/DD/YYYY or today for the current day
Example: 01/01/2000
is before
.after Matches every item where the date attribute is after the given date
Format: MM/DD/YYYY or today for the current day
Example: 01/01/2000
is after

Date Attributes

Date Search Description Movie
Libraries
Show
Libraries
Music
Libraries
added Uses the date added attribute to match
episode_added Uses the date added attribute of the show's episodes to match
release Uses the release date attribute (originally available) to match
episode_air_date Uses the air date attribute (originally available) of the show's episodes to match
last_played Uses the date last played attribute to match
episode_last_played Uses the date last played attribute of the show's episodes to match
artist_added Uses the Artist's date added attribute to match
artist_last_played Uses the Artist's last played attribute to match
album_last_played Uses the Album's last played attribute to match
album_added Uses the Album's date added attribute to match
album_released Uses the Album's release date attribute to match
track_last_played Uses the Track's date last played attribute to match
track_last_skipped Uses the Track's date last skipped attribute to match
track_last_rated Uses the Track's date last rated attribute to match
track_added Uses the Track's date added attribute to match

Number Searches

Number searches must use .gt, .gte, .lt, or .lte as a modifier only the rating searches can use .rated.

No number search can take multiple values.

Number Modifiers

Number Modifier Description Plex Web UI Display
.gt Matches every item where the number attribute is greater than the given number
Format: number
Example: 30, 1995, or 7.5
is greater than
.gte Matches every item where the number attribute is greater than or equal to the given number
Format: number
Example: 30, 1995, or 7.5
N/A
.lt Matches every item where the number attribute is less than the given number
Format: number
Example: 30, 1995, or 7.5
is less than
.lte Matches every item where the number attribute is less than or equal to the given number
Format: number
Example: 30, 1995, or 7.5
N/A
.rated Matches every item either rated or not rated
Format: true or false
N/A
  • .rated only works for rating searches

Number Attributes

Number Search Description Movie
Libraries
Show
Libraries
Music
Libraries
duration Uses the duration attribute to match using minutes
Minimum: 0
plays Uses the plays attribute to match
Minimum: 0
episode_plays Uses the Episode's plays attribute to match
Minimum: 0
critic_rating Uses the critic rating attribute to match
Range: 0.0 - 10.0
audience_rating Uses the audience rating attribute to match
Range: 0.0 - 10.0
user_rating Uses the user rating attribute to match
Range: 0.0 - 10.0
episode_user_rating Uses the user rating attribute of the show's episodes to match
Range: 0.0 - 10.0
episode_critic_rating Uses the critic rating attribute of the show's episodes to match
Range: 0.0 - 10.0
episode_audience_rating Uses the audience rating attribute of the show's episodes to match
Range: 0.0 - 10.0
year1 Uses the year attribute to match
Minimum: 0
episode_year1 Uses the Episode's year attribute to match
Minimum: 0
album_year1 Uses the Album's year attribute to match
Minimum: 0
album_decade1 Uses the Album's decade attribute to match
Minimum: 0
album_plays Uses the Album's plays attribute to match
Minimum: 0
track_plays Uses the Track's plays attribute to match
Minimum: 0
track_skips Uses the Track's skips attribute to match
Minimum: 0
artist_user_rating Uses the Artist's user rating attribute to match
Range: 0.0 - 10.0
album_user_rating Uses the Album's user rating attribute to match
Range: 0.0 - 10.0
album_critic_rating Uses the Album's critic rating attribute to match
Range: 0.0 - 10.0
track_user_rating Uses the Track's user rating attribute to match
Range: 0.0 - 10.0

1 You can use current_year to have Kometa use the current years value. This can be combined with a -# at the end to subtract that number of years. i.e. current_year-2

Boolean Searches

Boolean Searches take no modifier and can only be either true or false.

Boolean Attributes

Boolean Search Description Movie
Libraries
Show
Libraries
Music
Libraries
hdr Is HDR
unmatched Is Unmatched
duplicate Is Duplicate
unplayed Is Unplayed
progress Is In Progress
trash Is Trashed
unplayed_episodes Has Unplayed Episodes
episode_unplayed Has Episodes Unplayed
episode_duplicate Has Duplicate Episodes
episode_progress Has Episode Progress
episode_unmatched Has Episodes Unmatched
show_unmatched Has Shows Unmatched
artist_unmatched Is Artist's Unmatched
album_unmatched Is Album's Unmatched
track_trash Is Track Trashed

Plex Search Examples

A few examples are listed below:

collections:
  Documentaries:
    plex_search:
      all:
        genre: Documentary
collections:
  Dave Chappelle Comedy:
    plex_search:
      all:
        actor: Dave Chappelle
        genre: Comedy
collections:
  Top Action Movies:
    collection_order: custom
    plex_search:
      all:
        genre: Action
      sort_by: audience_rating.desc
      limit: 20
collections:
  90s Movies:
    plex_search:
      any:
        year:
          - 1990
          - 1991
          - 1992
          - 1993
          - 1994
          - 1995
          - 1996
          - 1997
          - 1998
          - 1999
collections:
  90s Movies:
    plex_search:
      any:
        decade: 1990
collections:
  Best 2010+ Movies:
    collection_order: custom
    plex_search:
      all:
        year.gte: 2010
      sort_by:
        - year.desc
        - audience_rating.desc
      limit: 20

Here's an example of an episode collection using plex_search.

 collections:
   Top 100 Simpsons Episodes:
     collection_order: custom
     builder_level: episode
     plex_search:
       type: episode
       sort_by: audience_rating.desc
       limit: 100
       all:
         title.ends: "Simpsons"
     summary: A collection of the highest rated simpsons episodes.

If you specify TMDb Person ID's using the Setting tmdb_person and then tell either actor, director, producer, or writer to add tmdb, the script will translate the TMDb Person IDs into their names and run the search on those names.

collections:
  Robin Williams:
    plex_search:
      all:
        actor: tmdb
    tmdb_person: 2157
collections:
  Steven Spielberg:
    plex_search:
      all:
        director: tmdb
    tmdb_person: https://www.themoviedb.org/person/488-steven-spielberg
collections:
  Quentin Tarantino:
    plex_search:
      any:
        actor: tmdb
        director: tmdb
        producer: tmdb
        writer: tmdb
    tmdb_person: 138