Plex
/
Plex-Meta-Manager
mirror of https://github.com/meisnate12/Plex-Meta-Manager.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
Branches Tags
${ item.name }
Create tag ${ searchTerm }
Create branch ${ searchTerm }
from '4aba37884b'
${ noResults }
Plex-Meta-Manager/docs/metadata/builders/smart.md

363 lines
32 KiB
Raw Normal View History Unescape

[100] add docs
2 years ago
# Smart Builders
Smart Builders allow Plex Meta Manager to create Smart Collections in two different ways.
## Smart Label
A Smart Label Collection is a smart collection that grabs every item with a specific label generated by the program. That label is added to all the items the Collection Builders find instead of being added to a normal collection.
To make a collection a Smart Label Collection,the `smart_label` attribute must added to the collection definition. It functions in two different ways:
1. Define the sort using the Movies/Shows column of the [Sorts Table](#sort-options) below along with any other builder to make that collection a Smart Label Collection.
```yaml
collections:
Marvel Cinematic Universe:
trakt_list: https://trakt.tv/users/jawann2002/lists/marvel-cinematic-universe-movies?sort=rank,asc
smart_label: release.desc
```
2. Provide a whole `smart_filter` to determine exactly how the smart collection should be built, ensuring to include `label: <<smart_label>>`, which will link it to the collection labels.
```yaml
collections:
Unplayed Marvel Cinematic Universe:
trakt_list: https://trakt.tv/users/jawann2002/lists/marvel-cinematic-universe-movies?sort=rank,asc
smart_label:
sort_by: release.desc
all:
label: <<smart_label>>
unplayed: True
```
This is extremely useful because smart collections don't follow normal show/hide rules and can eliminate the need to have [Plex Collectionless](plex.md#plex-collectionless) when used correctly. To fix the issue described in [Plex Collectionless](plex.md#plex-collectionless) you would make `Marvel Cinematic Universe` a Smart Label Collection and all other Marvel collection just normal collections, and they will show/hide all the movie properly.
To have the Smart Label Collections to eliminate Plex Collectionless you have to go all in on using them. A good rule of thumb to make sure this works correctly is that every item in your library should have a max of one non-smart collection.
Reach out on the [Plex Meta Manager Discord](https://discord.gg/TsdpsFYqqm) or in the [GitHub Discussions](https://github.com/meisnate12/Plex-Meta-Manager/discussions) for help if you're having any issues getting this to work properly.
## Smart Filter
Uses Plex's [Advanced Filters](https://support.plex.tv/articles/201273953-collections/) to create a smart collection based on the filter parameters provided.
Any Advanced Filter made using the Plex UI should be able to be recreated using `smart_filter`. If you're having trouble getting `smart_filter` 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](https://github.com/meisnate12/Plex-Meta-Manager/discussions) or on [Discord](https://discord.gg/TsdpsFYqqm), and I'll do my best to help you.
like Plex's [Advanced Filters](https://support.plex.tv/articles/201273953-collections/) you have to start each filter with either `any` or `all` as a base. You can only have one base attribute and all filter attributes must be under the base.
Inside the base attribute you can use any filter 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
| Attribute | Description & Values |
|:-----------|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `type` | **Description:** The Type of items inside this collection.<br>**Default:**<table class="clearTable"><tr><td>`movies` for Movies Libraries</td></tr><tr><td>`shows` for Show Libraries</td></tr><tr><td>`artists` for Music Libraries</td></tr></table>**Values:** `movies`, `shows`, `seasons`, `episodes`, `artists`, `albums`, or `tracks` |
| `limit` | **Description:** The max number of item for the filter.<br>**Default:** `all`<br>**Values:** `all` or a number greater then 0 |
| `sort_by` | **Description:** This will control how the filter is sorted in your library.<br>**Default:** `random`<br>**Values:** Any sort options for your filter type in the [Sorts Options Table](#sort-options) |
| `validate` | **Description:** Determines if a collection will fail on a validation error<br>**Default:** `true`<br>**Values**: `true` or `false` |
## Sort Options
| Sort Option | Description | Movies | Shows | Seasons | Episodes | Artists | Albums | Tracks |
|:------------------------------------------------|:--------------------------------------------|:--------:|:--------:|:--------:|:--------:|:--------:|:--------:|:--------:|
| `title.asc`<br>`title.desc` | Sort by Title | &#9989; | &#9989; | &#10060; | &#9989; | &#9989; | &#9989; | &#9989; |
| `season.asc`<br>`season.desc` | Sort by Season | &#10060; | &#10060; | &#9989; | &#10060; | &#10060; | &#10060; | &#10060; |
| `show.asc`<br>`show.desc` | Sort by Show | &#10060; | &#10060; | &#9989; | &#9989; | &#10060; | &#10060; | &#10060; |
| `album_artist.asc`<br>`album_artist.desc` | Sort by Album Artist | &#10060; | &#10060; | &#10060; | &#10060; | &#10060; | &#9989; | &#9989; |
| `artist.asc`<br>`artist.desc` | Sort by Artist | &#10060; | &#10060; | &#10060; | &#10060; | &#10060; | &#10060; | &#9989; |
| `album.asc`<br>`album.desc` | Sort by Album | &#10060; | &#10060; | &#10060; | &#10060; | &#10060; | &#10060; | &#9989; |
| `year.asc`<br>`year.desc` | Sort by Year | &#9989; | &#9989; | &#10060; | &#9989; | &#10060; | &#9989; | &#10060; |
| `release.asc`<br>`release.desc` | Sort by Release Date (Originally Available) | &#9989; | &#9989; | &#10060; | &#9989; | &#10060; | &#9989; | &#10060; |
| `critic_rating.asc`<br>`critic_rating.desc` | Sort by Critic Rating | &#9989; | &#9989; | &#10060; | &#9989; | &#10060; | &#9989; | &#10060; |
| `audience_rating.asc`<br>`audience_rating.desc` | Sort by Audience Rating | &#9989; | &#9989; | &#10060; | &#9989; | &#10060; | &#10060; | &#10060; |
| `user_rating.asc`<br>`user_rating.desc` | Sort by User Rating | &#9989; | &#9989; | &#9989; | &#9989; | &#9989; | &#9989; | &#9989; |
| `content_rating.asc`<br>`content_rating.desc` | Sort by Content Rating | &#9989; | &#9989; | &#10060; | &#10060; | &#10060; | &#10060; | &#10060; |
| `duration.asc`<br>`duration.desc` | Sort by Duration | &#9989; | &#10060; | &#10060; | &#9989; | &#10060; | &#10060; | &#9989; |
| `progress.asc`<br>`progress.desc` | Sort by Progress | &#10060; | &#10060; | &#10060; | &#9989; | &#10060; | &#10060; | &#10060; |
| `played.asc`<br>`played.desc` | Sort by Date Last Played | &#10060; | &#10060; | &#10060; | &#10060; | &#9989; | &#9989; | &#9989; |
| `plays.asc`<br>`plays.desc` | Sort by Number of Plays | &#9989; | &#10060; | &#10060; | &#9989; | &#9989; | &#9989; | &#9989; |
| `unplayed.asc`<br>`unplayed.desc` | Sort by Unplayed | &#10060; | &#9989; | &#10060; | &#10060; | &#10060; | &#10060; | &#10060; |
| `episode_added.asc`<br>`episode_added.desc` | Sort by Last Episode Date Added | &#10060; | &#9989; | &#10060; | &#10060; | &#10060; | &#10060; | &#10060; |
| `added.asc`<br>`added.desc` | Sort by Date Added | &#9989; | &#9989; | &#9989; | &#9989; | &#9989; | &#9989; | &#9989; |
| `viewed.asc`<br>`viewed.desc` | Sort by Date Last Viewed | &#9989; | &#9989; | &#10060; | &#9989; | &#10060; | &#10060; | &#10060; |
| `rated.asc`<br>`rated.desc` | Sort by Date Last Rated | &#10060; | &#10060; | &#10060; | &#10060; | &#10060; | &#10060; | &#9989; |
| `popularity.asc`<br>`popularity.desc` | Sort by Popularity | &#10060; | &#10060; | &#10060; | &#10060; | &#10060; | &#10060; | &#9989; |
| `resolution.asc`<br>`resolution.desc` | Sort by Resolution | &#9989; | &#10060; | &#10060; | &#9989; | &#10060; | &#10060; | &#10060; |
| `bitrate.asc`<br>`bitrate.desc` | Sort by Bitrate | &#9989; | &#10060; | &#10060; | &#9989; | &#10060; | &#10060; | &#9989; |
| `random` | Sort by Random | &#9989; | &#9989; | &#9989; | &#9989; | &#9989; | &#9989; | &#9989; |
## Filters
There are three fields per filter option when using Plex's Advanced Filters in the Web UI.
1. **Attribute:** What attribute you wish to filter.
2. **Modifier:** Which modifier to use.
3. **Value:** Actual value to filter.
**Example:** `Attribute.Modifier: Value`
## String Filters
String filters can be used with either no modifier or with `.not`, `.is`, `.isnot`, `.begins`, or `.ends`.
String filter 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<br>Libraries | Show<br>Libraries | Music<br>Libraries |
|:---------------------|:---------------------------------------------------------|:------------------:|:-----------------:|:------------------:|
| `title` | Uses the title attribute to match | &#9989; | &#9989; | &#10060; |
| `episode_title` | Uses the title attribute of the show's episodes to match | &#10060; | &#9989; | &#10060; |
| `studio` | Uses the studio attribute to match | &#9989; | &#9989; | &#10060; |
| `artist_title` | Uses the Artist's Title attribute to match | &#10060; | &#10060; | &#9989; |
| `album_title` | Uses the Album's Title attribute to match | &#10060; | &#10060; | &#9989; |
| `track_title` | Uses the Track's Title attribute to match | &#10060; | &#10060; | &#9989; |
| `album_record_label` | Uses the Album's Record Label attribute to match | &#10060; | &#10060; | &#9989; |
## Tag Filters
Tag filters can be used with either no modifier or with `.not` except for `decade` and `resolution` which can only be used with no modifier.
Tag filter 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<br>Libraries | Show<br>Libraries | Music<br>Libraries |
|:--------------------|:----------------------------------------------------------------------------|:------------------:|:-----------------:|:------------------:|
| `actor` | Uses the actor tags to match | &#9989; | &#9989; | &#10060; |
| `audio_language` | Uses the audio language tags to match | &#9989; | &#9989; | &#10060; |
| `collection` | Uses the collection tags to match | &#9989; | &#9989; | &#10060; |
| `content_rating` | Uses the content rating tags to match | &#9989; | &#9989; | &#10060; |
| `country` | Uses the country tags to match | &#9989; | &#10060; | &#10060; |
| `decade` | Uses the year tag to match the decade | &#9989; | &#10060; | &#10060; |
| `director` | Uses the director tags to match | &#9989; | &#10060; | &#10060; |
| `genre` | Uses the genre tags to match | &#9989; | &#9989; | &#10060; |
| `label` | Uses the label tags to match | &#9989; | &#9989; | &#10060; |
| `network` | Uses the network tags to match<br>**Only works with the New Plex TV Agent** | &#10060; | &#9989; | &#10060; |
| `producer` | Uses the actor tags to match | &#9989; | &#10060; | &#10060; |
| `resolution` | Uses the resolution tags to match | &#9989; | &#9989; | &#10060; |
| `subtitle_language` | Uses the subtitle language tags to match | &#9989; | &#9989; | &#10060; |
| `writer` | Uses the writer tags to match | &#9989; | &#10060; | &#10060; |
| `year` | Uses the year tag to match | &#9989; | &#9989; | &#10060; |
| `episode_year` | Uses the year tag to match | &#10060; | &#9989; | &#10060; |
| `artist_genre` | Uses the Artist's Genre attribute to match | &#10060; | &#10060; | &#9989; |
| `artist_collection` | Uses the Artist's Collection attribute to match | &#10060; | &#10060; | &#9989; |
| `artist_country` | Uses the Artist's Country attribute to match | &#10060; | &#10060; | &#9989; |
| `artist_mood` | Uses the Artist's Mood attribute to match | &#10060; | &#10060; | &#9989; |
| `artist_style` | Uses the Artist's Style attribute to match | &#10060; | &#10060; | &#9989; |
| `album_genre` | Uses the Album's Genre attribute to match | &#10060; | &#10060; | &#9989; |
| `album_mood` | Uses the Album's Mood attribute to match | &#10060; | &#10060; | &#9989; |
| `album_style` | Uses the Album's Style attribute to match | &#10060; | &#10060; | &#9989; |
| `album_format` | Uses the Album's Format attribute to match | &#10060; | &#10060; | &#9989; |
| `album_type` | Uses the Album's Type attribute to match | &#10060; | &#10060; | &#9989; |
| `album_collection` | Uses the Album's Collection attribute to match | &#10060; | &#10060; | &#9989; |
| `album_source` | Uses the Album's Source attribute to match | &#10060; | &#10060; | &#9989; |
| `album_label` | Uses the Album's Label attribute to match | &#10060; | &#10060; | &#9989; |
| `track_mood` | Uses the Track's Mood attribute to match | &#10060; | &#10060; | &#9989; |
| `track_source` | Uses the Track's Style attribute to match | &#10060; | &#10060; | &#9989; |
## Date Filters
Date filters can be used with either no modifier or with `.not`, `.before`, or `.after`.
No date filter 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<br>**Format:** number of days<br>**Example:** `30` | `is in the last` |
| `.not` | Matches every item where the date attribute is not in the last X days<br>**Format:** number of days<br>**Example:** `30` | `is not in the last` |
| `.before` | Matches every item where the date attribute is before the given date<br>**Format:** MM/DD/YYYY or `today` for the current day<br>**Example:** `01/01/2000` | `is before` |
| `.after` | Matches every item where the date attribute is after the given date<br>**Format:** MM/DD/YYYY or `today` for the current day<br>**Example:** `01/01/2000` | `is after` |
### Date Attributes
| Date Search | Description | Movie<br>Libraries | Show<br>Libraries | Music<br>Libraries |
|:----------------------|:-----------------------------------------------------------------------------------|:------------------:|:-----------------:|:------------------:|
| `added` | Uses the date added attribute to match | &#9989; | &#9989; | &#10060; |
| `episode_added` | Uses the date added attribute of the show's episodes to match | &#10060; | &#9989; | &#10060; |
| `release` | Uses the release date attribute (originally available) to match | &#9989; | &#9989; | &#10060; |
| `episode_air_date` | Uses the air date attribute (originally available) of the show's episodes to match | &#10060; | &#9989; | &#10060; |
| `last_played` | Uses the date last played attribute to match | &#9989; | &#9989; | &#10060; |
| `episode_last_played` | Uses the date last played attribute of the show's episodes to match | &#10060; | &#9989; | &#10060; |
| `artist_added` | Uses the Artist's date added attribute to match | &#10060; | &#10060; | &#9989; |
| `artist_last_played` | Uses the Artist's last played attribute to match | &#10060; | &#10060; | &#9989; |
| `album_last_played` | Uses the Album's last played attribute to match | &#10060; | &#10060; | &#9989; |
| `album_added` | Uses the Album's date added attribute to match | &#10060; | &#10060; | &#9989; |
| `album_released` | Uses the Album's release date attribute to match | &#10060; | &#10060; | &#9989; |
| `track_last_played` | Uses the Track's date last played attribute to match | &#10060; | &#10060; | &#9989; |
| `track_last_skipped` | Uses the Track's date last skipped attribute to match | &#10060; | &#10060; | &#9989; |
| `track_last_rated` | Uses the Track's date last rated attribute to match | &#10060; | &#10060; | &#9989; |
| `track_added` | Uses the Track's date added attribute to match | &#10060; | &#10060; | &#9989; |
## Number Filters
Number filters must use `.gt`, `.gte`, `.lt`, or `.lte` as a modifier.
No number filter can take multiple values.
### Number Modifiers
| Number Modifier | Description | Plex Web UI Display |
|:----------------|:--------------------------------------------------------------------------------------------------------------------------------------------------------|:-------------------:|
| `.gt` | Matches every item where the number attribute is greater then the given number<br>**Format:** number<br>**Example:** `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<br>**Format:** number<br>**Example:** `30`, `1995`, or `7.5` | N/A |
| `.lt` | Matches every item where the number attribute is less then the given number<br>**Format:** number<br>**Example:** `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<br>**Format:** number<br>**Example:** `30`, `1995`, or `7.5` | N/A |
### Number Attributes
| Number Search | Description | Movie<br>Libraries | Show<br>Libraries | Music<br>Libraries |
|:----------------------|:--------------------------------------------------------------------------------------------|:------------------:|:-----------------:|:------------------:|
| `duration` | Uses the duration attribute to match using minutes<br>**Minimum:** `1` | &#9989; | &#10060; | &#10060; |
| `plays` | Uses the plays attribute to match<br>**Minimum:** `1` | &#9989; | &#9989; | &#10060; |
| `episode_plays` | Uses the Episode's plays attribute to match<br>**Minimum:** `1` | &#10060; | &#9989; | &#10060; |
| `critic_rating` | Uses the critic rating attribute to match<br>**Range:** `0.0` - `10.0` | &#9989; | &#9989; | &#10060; |
| `audience_rating` | Uses the audience rating attribute to match<br>**Range:** `0.0` - `10.0` | &#9989; | &#9989; | &#10060; |
| `user_rating` | Uses the user rating attribute to match<br>**Range:** `0.0` - `10.0` | &#9989; | &#9989; | &#10060; |
| `episode_user_rating` | Uses the user rating attribute of the show's episodes to match<br>**Range:** `0.0` - `10.0` | &#10060; | &#9989; | &#10060; |
| `year` | Uses the year attribute to match<br>**Minimum:** `1` | &#9989; | &#9989; | &#10060; |
| `episode_year` | Uses the Episode's year attribute to match<br> **Minimum:** `1` | &#10060; | &#9989; | &#10060; |
| `album_year` | Uses the Album's year attribute to match<br>**Minimum:** `1` | &#10060; | &#10060; | &#9989; |
| `album_decade` | Uses the Album's decade attribute to match<br>**Minimum:** `1` | &#10060; | &#10060; | &#9989; |
| `album_plays` | Uses the Album's plays attribute to match<br>**Minimum:** `1` | &#10060; | &#10060; | &#9989; |
| `track_plays` | Uses the Track's plays attribute to match<br>**Minimum:** `1` | &#10060; | &#10060; | &#9989; |
| `track_skips` | Uses the Track's skips attribute to match<br>**Minimum:** `1` | &#10060; | &#10060; | &#9989; |
| `artist_user_rating` | Uses the Artist's user rating attribute to match<br>**Range:** `0.0` - `10.0` | &#10060; | &#10060; | &#9989; |
| `album_user_rating` | Uses the Album's user rating attribute to match<br>**Range:** `0.0` - `10.0` | &#10060; | &#10060; | &#9989; |
| `album_critic_rating` | Uses the Album's critic rating attribute to match<br>**Range:** `0.0` - `10.0` | &#10060; | &#10060; | &#9989; |
| `track_user_rating` | Uses the Track's user rating attribute to match<br>**Range:** `0.0` - `10.0` | &#10060; | &#10060; | &#9989; |
## Boolean Filters
Boolean Filters take no modifier and can only be either `true` or `false`.
### Boolean Attributes
| Boolean Search | Description | Movie<br>Libraries | Show<br>Libraries | Music<br>Libraries |
|:--------------------|:-----------------------|:------------------:|:-----------------:|:------------------:|
| `hdr` | Is HDR | &#9989; | &#9989; | &#10060; |
| `unmatched` | Is Unmatched | &#9989; | &#10060; | &#10060; |
| `duplicate` | Is Duplicate | &#9989; | &#10060; | &#10060; |
| `unplayed` | Is Unplayed | &#9989; | &#10060; | &#10060; |
| `progress` | Is In Progress | &#9989; | &#10060; | &#10060; |
| `trash` | Is Trashed | &#9989; | &#9989; | &#10060; |
| `unplayed_episodes` | Has Unplayed Episodes | &#10060; | &#9989; | &#10060; |
| `episode_unplayed` | Has Episodes Unplayed | &#10060; | &#9989; | &#10060; |
| `episode_duplicate` | Has Duplicate Episodes | &#10060; | &#9989; | &#10060; |
| `episode_progress` | Has Episode Progress | &#10060; | &#9989; | &#10060; |
| `episode_unmatched` | Has Episodes Unmatched | &#10060; | &#9989; | &#10060; |
| `artist_unmatched` | Is Artist's Unmatched | &#10060; | &#10060; | &#9989; |
| `album_unmatched` | Is Album's Unmatched | &#10060; | &#10060; | &#9989; |
| `track_trash` | Is Track Trashed | &#10060; | &#10060; | &#9989; |
## Smart Filter Examples
A few examples are listed below:
```yaml
collections:
Documentaries:
smart_filter:
all:
genre: Documentary
```
```yaml
collections:
Dave Chappelle Comedy:
smart_filter:
all:
actor: Dave Chappelle
genre: Comedy
```
```yaml
collections:
Top Action Movies:
smart_filter:
all:
genre: Action
sort_by: audience_rating.desc
limit: 20
```
```yaml
collections:
90s Movies:
smart_filter:
any:
year:
- 1990
- 1991
- 1992
- 1993
- 1994
- 1995
- 1996
- 1997
- 1998
- 1999
```
```yaml
collections:
90s Movies:
smart_filter:
any:
decade: 1990
```
```yaml
collections:
Best 2010+ Movies:
smart_filter:
all:
year.gte: 2010
sort_by: audience_rating.desc
limit: 20
```
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 filter on those names.
```yaml
collections:
Robin Williams:
smart_filter:
all:
actor: tmdb
tmdb_person: 2157
```
```yaml
collections:
Steven Spielberg:
smart_filter:
all:
director: tmdb
tmdb_person: https://www.themoviedb.org/person/488-steven-spielberg
```
```yaml
collections:
Quentin Tarantino:
smart_filter:
any:
actor: tmdb
director: tmdb
producer: tmdb
writer: tmdb
tmdb_person: 138
```