Plex-Builders.md

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

No configuration is required for these builders.

Name	Attribute	Description	Works with Movies	Works with Shows	Works with Playlists and Custom Sort
Plex All	plex_all	Gets every movie/show in your library. Useful with Filters	✔️	✔️	❌
Plex Pilots	plex_pilots	Gets the first episode of every show in your library	❌	✔️	✔️
Plex Collectionless	plex_collectionless	Gets every movie/show that is not in a collection	✔️	✔️	❌
Plex Search	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:
      rating.gte: 9

Plex Pilots

Gets the first episode of every show in your library. This Only works with collection_level: episode

collection:
  Pilots:
    collection_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 Plex Meta Manager 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 (To exclude specific collections) and exclude_prefix (To exclude every collection whose title or sort title starts with the prefix). At least one exclusion is required.

collections:
  Collectionless:
    plex_collectionless:
      exclude_prefix:
        - +
        - ~
      exclude: Marvel Cinematic Universe
    sort_title: ~_Collectionless
    collection_order: alpha

• 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.

Plex Search

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

Any Advance 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 Advance 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 Advance 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.

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

Special Attributes

Special Option	Attribute	Description	Default
Type	type	The Type of items inside this collection/playlist Options: movies, shows, seasons, episodes, artists, albums, or tracks	movies for Movies Libraries, shows for Show Libraries, and artists for Music Libraries
Limit	limit	The max number of item for the search	all
Sort By	sort_by	This will control how the search is sorted in your library. You can use any sort options for your search type in the Sorts Options Table	random
Validate	validate	Determines if a collection/playlist will fail on a validation error Options: true or false	true

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)	✔️	✔️	❌	✔️	❌	✔️	❌
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 Advance Filters in the Web UI. The first is the Attribute (what attribute you wish to search), the second is the Modifier (which modifier to use), and the third is the Term (actual term to search).

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	✔️	✔️	❌
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

Tag Attributes

Tag Search	Description	Movie Libraries	Show Libraries	Music Libraries
actor	Uses the actor tags to match	✔️	✔️	❌
audio_language	Uses the audio language tags to match	✔️	✔️	❌
collection	Uses the collection tags to match	✔️	✔️	❌
content_rating	Uses the content rating tags to match	✔️	✔️	❌
country	Uses the country tags to match	✔️	❌	❌
decade	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	✔️	✔️	❌
network	Uses the network tags to match Only works with the New Plex TV Agent	❌	✔️	❌
producer	Uses the actor 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	✔️	❌	❌
year	Uses the year tag to match	✔️	✔️	❌
episode_year	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	❌	❌	✔️
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 Style attribute to match	❌	❌	✔️

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	Format	Plex Web UI Display
No Modifier	Matches every item where the date attribute is in the last X days	Format: number of days e.g. 30	is in the last
.not	Matches every item where the date attribute is not in the last X days	Format: number of days e.g. 30	is not in the last
.before	Matches every item where the date attribute is before the given date	Format: MM/DD/YYYY e.g. 01/01/2000	is before
.after	Matches every item where the date attribute is after the given date	Format: MM/DD/YYYY e.g. 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.

No number search can take multiple values.

Number Modifiers

Number Modifier	Description	Format	Plex Web UI Display
.gt	Matches every item where the number attribute is greater then the given number	Format: number e.g. 30, 1995, or 7.5	is greater than
.gte	Matches every item where the number attribute is greater then or equal to the given number	Format: number e.g. 30, 1995, or 7.5	N/A
.lt	Matches every item where the number attribute is less then the given number	Format: number e.g. 30, 1995, or 7.5	is less than
.lte	Matches every item where the number attribute is less then or equal to the given number	Format: number e.g. 30, 1995, or 7.5	N/A

Number Attributes

Number Search	Description	Restrictions	Movie Libraries	Show Libraries	Music Libraries
duration	Uses the duration attribute to match using minutes	minimum: 1	✔️	❌	❌
plays	Uses the plays attribute to match	minimum: 1	✔️	✔️	❌
episode_plays	Uses the Episode's plays attribute to match	minimum: 1	❌	✔️	❌
critic_rating	Uses the critic rating attribute to match	0.0 - 10.0	✔️	✔️	❌
audience_rating	Uses the audience rating attribute to match	0.0 - 10.0	✔️	✔️	❌
user_rating	Uses the user rating attribute to match	0.0 - 10.0	✔️	✔️	❌
episode_user_rating	Uses the user rating attribute of the show's episodes to match	0.0 - 10.0	❌	✔️	❌
year	Uses the year attribute to match	minimum: 1	✔️	✔️	❌
episode_year	Uses the Episode's year attribute to match	minimum: 1	❌	✔️	❌
album_year	Uses the Album's year attribute to match	minimum: 1	❌	❌	✔️
album_decade	Uses the Album's decade attribute to match	minimum: 1	❌	❌	✔️
album_plays	Uses the Album's plays attribute to match	minimum: 1	❌	❌	✔️
track_plays	Uses the Track's plays attribute to match	minimum: 1	❌	❌	✔️
track_skips	Uses the Track's skips attribute to match	minimum: 1	❌	❌	✔️
artist_user_rating	Uses the Artist's user rating attribute to match	0.0 - 10.0	❌	❌	✔️
album_user_rating	Uses the Album's user rating attribute to match	0.0 - 10.0	❌	❌	✔️
album_critic_rating	Uses the Album's critic rating attribute to match	0.0 - 10.0	❌	❌	✔️
track_user_rating	Uses the Track's user rating attribute to match	0.0 - 10.0	❌	❌	✔️

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	❌	✔️	❌
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: audience_rating.desc
      limit: 20

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

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

If you specify TMDb Person ID's using the Detail 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