meisnate12
12 months ago
parent
6cfd46fd67
commit
5a5efd2112
@ -0,0 +1,105 @@
|
|||||||
|
# Dynamic Collections
|
||||||
|
|
||||||
|
Plex Meta Manager can dynamically create collections based on different criteria, such as
|
||||||
|
* Collections based on the Collections from TMDb for every item in the library. ([Star Wars](https://www.themoviedb.org/collection/10-star-wars-collection), [Harry Potter](https://www.themoviedb.org/collection/1241), etc...)
|
||||||
|
* Collections based on each of a Users Trakt Lists
|
||||||
|
* Collections for the top `X` popular people on TMDb (Bruce Willis, Tom Hanks, etc...)
|
||||||
|
* Collections for each decade represented in the library (Best of 1990s, Best of 2000s, etc...)
|
||||||
|
* Collections for each of the moods/styles within a Music library (A Cappella, Pop Rock, etc...)
|
||||||
|
|
||||||
|
The main purpose of dynamic collections is to automate the creation of collections which would otherwise require considerable user input and repetition (such as creating a collection for every genre).
|
||||||
|
|
||||||
|
Each dynamic collection must have a mapping name (just like standard collections), which is also attached to the collection as a label to mark it as having been created by this dynamic collection.
|
||||||
|
|
||||||
|
This example will create a collection for every TMDb Collection associated with items in the library.
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
dynamic_collections:
|
||||||
|
TMDb Collections: # This name is the mapping name
|
||||||
|
type: tmdb_collection
|
||||||
|
remove_suffix: "Collection"
|
||||||
|
```
|
||||||
|
|
||||||
|
## Collection Naming
|
||||||
|
|
||||||
|
By default, the collections generated will be named for the thing being used to create them; things like genres, countries, actors or even Trakt List Names.
|
||||||
|
|
||||||
|
There are many attributes that can change the titles, including `title_format`, `remove_suffix`, `remove_prefix`, `key_name_override`, and `title_override` all detailed below.
|
||||||
|
|
||||||
|
## Dynamic Keys & Key Names
|
||||||
|
|
||||||
|
A `dynamic key` or `key` for short is used to refer to a specific value/result from the dynamic collection criteria that will be used to create the collection.
|
||||||
|
|
||||||
|
A `key_name` is the name that replaces `<<key_name>>` in `title_format` to create the collection titles for each key.
|
||||||
|
|
||||||
|
An example of some keys and their names that would be generated from a `tmdb_collection` dynamic collection are
|
||||||
|
* `key`: "10"
|
||||||
|
* `key_name`: Star Wars Collection
|
||||||
|
* `key`: "1241"
|
||||||
|
* `key_name`: Harry Potter Collection
|
||||||
|
|
||||||
|
### Example Key Usage
|
||||||
|
|
||||||
|
Keys can be used for a number of purposes, examples can be found throughout this page. A few examples are shown below:
|
||||||
|
|
||||||
|
* Excluding the "Horror" key from the `Genre` dynamic collection definition
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
dynamic_collections:
|
||||||
|
Genres: # mapping name does not matter, just needs to be unique
|
||||||
|
type: genre
|
||||||
|
exclude:
|
||||||
|
- Horror
|
||||||
|
```
|
||||||
|
|
||||||
|
* Using the `key_name_override` attribute to change the formatting of "France" to "French" so that a collection can be named "French Cinema" instead of simply "France"
|
||||||
|
* This particular example also uses the `title_format` attribute to manipulate the naming convention of the collections.
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
dynamic_collections:
|
||||||
|
Countries: # mapping name does not matter, just needs to be unique
|
||||||
|
type: country
|
||||||
|
title_format: <<key_name>> Cinema
|
||||||
|
key_name_override:
|
||||||
|
France: French
|
||||||
|
```
|
||||||
|
|
||||||
|
* Using the `addons` attribute to combine multiple `keys`, i.e. merging "MTV2", "MTV3" and "MTV (UK)" into one "MTV" collection.
|
||||||
|
* When doing this, individual collections will not be created for the individual MTV collections, instead they will be merged within the "MTV" collection.
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
dynamic_collections:
|
||||||
|
networks:
|
||||||
|
type: network
|
||||||
|
addons:
|
||||||
|
MTV:
|
||||||
|
- MTV2
|
||||||
|
- MTV3
|
||||||
|
- MTV (UK)
|
||||||
|
```
|
||||||
|
|
||||||
|
## Attributes
|
||||||
|
|
||||||
|
| Attribute | Description | Required |
|
||||||
|
|:--------------------------------------------|:-------------------------------------------------------------------------------------------------------------------------------|:-----------------:|
|
||||||
|
| [`type`](#type--data) | Type of Dynamic Collection to be created. | ✅ |
|
||||||
|
| [`data`](#type--data) | Data to determine how dynamic collections with a certain `type` are created. | Depends on `type` |
|
||||||
|
| [`exclude`](#exclude) | Exclude this list of keys from being created into collections. | ❌ |
|
||||||
|
| [`addons`](#addons) | Defines how multiple keys can be combined under a parent key. | ❌ |
|
||||||
|
| [`template`](#template) | Name of the template to use for these dynamic collections. | ❌ |
|
||||||
|
| [`template_variables`](#template-variables) | Defines how template variables can be defined by key. | ❌ |
|
||||||
|
| [`other_template`](#other-template) | Name of the template to use for the other collection. | ❌ |
|
||||||
|
| [`remove_suffix`](#remove-prefixsuffix) | Removes the defined suffixes from the key before it's used in the collection title. | ❌ |
|
||||||
|
| [`remove_prefix`](#remove-prefixsuffix) | Removes the defined prefixes from the key before it's used in the collection title. | ❌ |
|
||||||
|
| [`title_format`](#title-format) | This is the format for the collection titles. | ❌ |
|
||||||
|
| [`key_name_override`](#key-name-override) | Defines how key names can be overridden before they are formatted into collection titles. | ❌ |
|
||||||
|
| [`title_override`](#title-override) | Defines how collection titles can be overridden ignoring title formatting. | ❌ |
|
||||||
|
| [`custom_keys`](#custom-keys) | Defines if custom keys are allowed. | ❌ |
|
||||||
|
| [`test`](#test) | Will add `test: true` to all collections for test runs. | ❌ |
|
||||||
|
| [`sync`](#sync) | Will remove dynamic collections that are no longer in the creation list. | ❌ |
|
||||||
|
| [`include`](#include) | Define a list of keys to be made into collections. | ❌ |
|
||||||
|
| [`other_name`](#other-name) | Used in combination with `include`. When defined, all keys not in `include` or `addons` will be combined into this collection. | ❌ |
|
||||||
|
|
||||||
|
{%
|
||||||
|
include-markdown "./dynamic_types.md"
|
||||||
|
%}
|
||||||
File diff suppressed because it is too large
Load Diff
@ -0,0 +1,24 @@
|
|||||||
|
# Builders
|
||||||
|
|
||||||
|
Builders use third-party services to source items to be added to the collection. Multiple builders can be used in the same collection from a variety of sources listed below.
|
||||||
|
|
||||||
|
| Name | Description | Requires Config |
|
||||||
|
|:--------------------------------|:----------------------------------------------------------------------------------------------|:---------------:|
|
||||||
|
| [Plex](plex.md) | Grabs items based on the metadata inside your Plex Server. | ✅ |
|
||||||
|
| [Smart](smart.md) | Creates Smart Collections based on the metadata inside your Plex Server. (Collections Only) | ✅ |
|
||||||
|
| [TMDb](tmdb.md) | Grabs items based on metadata and lists on [TheMovieDb.org](https://www.themoviedb.org/). | ✅ |
|
||||||
|
| [TVDb](tvdb.md) | Grabs items based on metadata and lists on [TheTVDb.com](https://www.thetvdb.com/). | ❌ |
|
||||||
|
| [IMDb](imdb.md) | Grabs items based on metadata and lists on [IMDb.com](https://www.imdb.com/). | ❌ |
|
||||||
|
| [Trakt](trakt.md) | Grabs items based on metadata and lists on [Trakt.tv](https://trakt.tv/). | ✅ |
|
||||||
|
| [Tautulli](tautulli.md) | Grabs items based on metadata and lists in your [Tautulli](https://tautulli.com/). | ✅ |
|
||||||
|
| [Radarr](radarr.md) | Grabs items based on metadata and lists in your [Radarr](https://radarr.video/) . | ✅ |
|
||||||
|
| [Sonarr](sonarr.md) | Grabs items based on metadata and lists in your [Sonarr](https://sonarr.tv/). | ✅ |
|
||||||
|
| [MdbList](mdblist.md) | Grabs items based on metadata and lists on [MdbList.com](https://mdblist.com/). | ❌ |
|
||||||
|
| [Letterboxd](letterboxd.md) | Grabs items based on metadata and lists on [Letterboxd.com](https://letterboxd.com/). | ❌ |
|
||||||
|
| [ICheckMovies](icheckmovies.md) | Grabs items based on metadata and lists on [ICheckMovies.com](https://www.icheckmovies.com/). | ❌ |
|
||||||
|
| [FlixPatrol](flixpatrol.md) | Grabs items based on metadata and lists on [FlixPatrol.com](https://flixpatrol.com/). | ❌ |
|
||||||
|
| [Reciperr](reciperr.md) | Grabs items based on metadata and lists on [reciperr.com](https://reciperr.com/). | ❌ |
|
||||||
|
| [StevenLu](stevenlu.md) | Grabs items based on metadata and lists on [StevenLu.com](https://movies.stevenlu.com/). | ❌ |
|
||||||
|
| [AniDB](anidb.md) | Grabs items based on metadata and lists on [AniDB.net](https://anidb.net/). | ❌ |
|
||||||
|
| [AniList](anilist.md) | Grabs items based on metadata and lists on [AniList.co](https://anilist.co/). | ❌ |
|
||||||
|
| [MyAnimeList](myanimelist.md) | Grabs items based on metadata and lists on [MyAnimeList.net](https://myanimelist.net/). | ✅ |
|
||||||
@ -0,0 +1,183 @@
|
|||||||
|
# Collection Files
|
||||||
|
|
||||||
|
Collection Files holds information on how Plex Meta Manager should create collections. There are a large number of builders available to build collections,
|
||||||
|
|
||||||
|
## Overview
|
||||||
|
|
||||||
|
This is a basic Collections File which contains the structure to build a collection called "Top 50 Grossing Films of All Time (Worldwide)"
|
||||||
|
|
||||||
|
The collection order is set to be the same as is received from the source list, and items added/removed from the source list will be added/removed from the collection in the Plex library.
|
||||||
|
|
||||||
|
???+ example "Example "MyCollections.yml""
|
||||||
|
|
||||||
|
Click the :fontawesome-solid-circle-plus: icon to learn more
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
collections: #(1)!
|
||||||
|
Top 50 Grossing Films of All Time (Worldwide):
|
||||||
|
tmdb_list: 10 #(2)!
|
||||||
|
collection_order: custom #(3)!
|
||||||
|
sync_mode: sync #(4)!
|
||||||
|
```
|
||||||
|
|
||||||
|
1. This must appear once and **only once** in any Metadata file
|
||||||
|
2. This creates a collection based on tmdb list ID 10, https://www.themoviedb.org/list/10 would also be accepted
|
||||||
|
3. This will sort the items in the Plex collection to be the same as the order in the list
|
||||||
|
4. Syncs the collection to the list, so that if an item is added/removed from the list, the same is done to the collection. Set this to `append` if you only want it to add things and not remove them.
|
||||||
|
|
||||||
|
For the purpose of this example, we are going to save the File as `MyCollections.yml` within the location mapped as `config` in our setup.
|
||||||
|
|
||||||
|
I then call "MyCollections.yml" in my [Configuration File](../configuration.md) within the `collection_files` section
|
||||||
|
|
||||||
|
???+ example "config.yml Example Collection File Addition"
|
||||||
|
|
||||||
|
Click the :fontawesome-solid-circle-plus: icon to learn more
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
libraries:
|
||||||
|
Movies: #(1)!
|
||||||
|
collection_files:
|
||||||
|
- file: config/MyCollections.yml #(2)!
|
||||||
|
```
|
||||||
|
|
||||||
|
1. This must match the name of a library in your Plex server
|
||||||
|
2. `config` refers to the location that you mapped to `config` when following the PMM Installation Guides.
|
||||||
|
|
||||||
|
Whenever I execute Plex Meta Manager and the Movies library is run, MyCollections.yml will run and my "Top 50 Grossing Films of All Time (Worldwide)" will be created/updated.
|
||||||
|
|
||||||
|
## File Attributes
|
||||||
|
|
||||||
|
Collection Files can utilize the following top-level attributes
|
||||||
|
|
||||||
|
| Attribute | Description |
|
||||||
|
|:--------------------------------------------------------------------------|:------------------------------------------------------------------------------------------------------------------|
|
||||||
|
| [`templates`](../../builders/templates.md) | contains definitions of templates that can be leveraged by multiple collections |
|
||||||
|
| [`external_templates`](../../builders/templates.md#external-templates) | contains [path types](../paths.md) that point to external templates that can be leveraged by multiple collections |
|
||||||
|
| [`collections`](#collection-attributes) | contains definitions of collections you wish to add to one or more libraries |
|
||||||
|
| [`dynamic_collections`](#dynamic-collection-attributes) | contains definitions of [dynamic collections](../../builders/dynamic.md) you wish to create |
|
||||||
|
|
||||||
|
* One of `metadata`, `collections` or `dynamic_collections` must be present for the File to run, else you will receive an error when trying to run the file against your library.
|
||||||
|
|
||||||
|
* Example Files can be found in the [Plex Meta Manager Configs Repository](https://github.com/meisnate12/Plex-Meta-Manager-Configs/tree/master/PMM)
|
||||||
|
|
||||||
|
## Collection Operations & Attributes
|
||||||
|
|
||||||
|
Whilst [Library Operations](../operations.md) are used to control library-wide operations, Collection Files can be used as a method to perform more limited operations, such as:
|
||||||
|
|
||||||
|
* Syncing collections with the source list if one is used (such as Trakt Lists, TMDB Lists, etc.)
|
||||||
|
|
||||||
|
* Sending missing media to Sonarr/Radarr
|
||||||
|
|
||||||
|
* Adding labels to items in collections
|
||||||
|
|
||||||
|
* Showing and Hiding collections at set intervals (i.e. show Christmas collections in December only)
|
||||||
|
|
||||||
|
These operations can be performed without the need to physically build a collection (using the `build_collection: false` attribute)
|
||||||
|
|
||||||
|
Examples of these can be seen here
|
||||||
|
|
||||||
|
???+ example "Examples of Collection Operations"
|
||||||
|
|
||||||
|
Click the :fontawesome-solid-circle-plus: icon to learn more
|
||||||
|
|
||||||
|
=== "Example 1 - Sync Collection to List"
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
collections:
|
||||||
|
Christmas Extravaganza:
|
||||||
|
trakt_list: https://trakt.tv/users/plexmetamanager/lists/christmas-extravaganza-non-tv-movie #(1)!
|
||||||
|
sync_mode: append #(2!)
|
||||||
|
collection_order: custom #(3)!
|
||||||
|
```
|
||||||
|
|
||||||
|
1. This is a Trakt List builder, telling PMM to build a collection based on the items in this list
|
||||||
|
1. If items are removed from the source list, having sync mode set to `append` means they will not be removed from the collection in Plex. Set this to `sync` if you want the items removed in the collection too
|
||||||
|
3. Sort the collection in the order that it is received from the Trakt list
|
||||||
|
|
||||||
|
=== "Example 2 - Send to Arr"
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
collections:
|
||||||
|
IMDb Top 250:
|
||||||
|
imdb_chart: top_movies
|
||||||
|
collection_order: custom #(1)!
|
||||||
|
radarr_add_missing: true #(2)!
|
||||||
|
```
|
||||||
|
|
||||||
|
1. Sorts the collection in the same order as is received by the source list
|
||||||
|
2. Sends items that are in the source list but are not in your Plex library to Radarr. Replace with `sonarr_add_missing` for any show-based builder.
|
||||||
|
|
||||||
|
=== "Example 3 - Add labels"
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
collections:
|
||||||
|
Radarr Tags:
|
||||||
|
build_collection: false #(1)!
|
||||||
|
radarr_taglist: mytag #(2)!
|
||||||
|
item_label: myplextag #(3)!
|
||||||
|
```
|
||||||
|
|
||||||
|
1. Tells PMM to not physically build a collection, but it will still perform the actions of the collection
|
||||||
|
2. Find all items in Radarr that have the tag `mytag`
|
||||||
|
3. For each of the items with `mytag` in Radarr, apply the `myplextag` to the items in the Plex library
|
||||||
|
|
||||||
|
=== "Example 4 - Schedule Collection"
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
collections:
|
||||||
|
Christmas Extravaganza:
|
||||||
|
trakt_list: https://trakt.tv/users/plexmetamanager/lists/christmas-extravaganza-non-tv-movie #(1)!
|
||||||
|
schedule: range(12/01-12/31) #(2)!
|
||||||
|
delete_not_scheduled: true #(3)!
|
||||||
|
```
|
||||||
|
|
||||||
|
1. Tells PMM to not physically build a collection, but it will still perform the actions of the collection
|
||||||
|
2. Only run this collection from December 1st through December 31st
|
||||||
|
3. If today is not part of the above scheduled range, delete the Christmas Extravaganza collection if it exists in the Plex library
|
||||||
|
|
||||||
|
There are multiple types of attributes that can be utilized within a collection:
|
||||||
|
|
||||||
|
* [Builders](../../builders/overview.md)
|
||||||
|
* [Settings/Updates](../../metadata/update.md)
|
||||||
|
* [Filters](../../builders/filters.md)
|
||||||
|
|
||||||
|
## Example File
|
||||||
|
|
||||||
|
Below is a common Collection File which will create two collections in a Plex library.
|
||||||
|
|
||||||
|
It will sync the collections to the source lists, order them randomly, and apply a summary to the collection.
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
collections:
|
||||||
|
Trending:
|
||||||
|
trakt_trending: 10
|
||||||
|
tmdb_trending_daily: 10
|
||||||
|
tmdb_trending_weekly: 10
|
||||||
|
sort_title: +1_Trending
|
||||||
|
sync_mode: sync
|
||||||
|
smart_label: random
|
||||||
|
summary: Movies Trending across the internet
|
||||||
|
Popular:
|
||||||
|
tmdb_popular: 40
|
||||||
|
imdb_list:
|
||||||
|
url: https://www.imdb.com/search/title/?title_type=feature,tv_movie,documentary,short
|
||||||
|
limit: 40
|
||||||
|
sort_title: +2_Popular
|
||||||
|
sync_mode: sync
|
||||||
|
smart_label: random
|
||||||
|
summary: Popular Movies across the internet
|
||||||
|
```
|
||||||
|
|
||||||
|
## Dynamic Collections
|
||||||
|
|
||||||
|
In addition to manually defining each Collection that you want in your library, Plex Meta Manager can also dynamically create collections based on a variety of different criteria, such as
|
||||||
|
|
||||||
|
* Collections for the top `X` popular people on TMDb (Bruce Willis, Tom Hanks etc.)
|
||||||
|
|
||||||
|
* Collections for each decade represented in the library (Best of 1990s, Best of 2000s etc.)
|
||||||
|
|
||||||
|
* Collections for each of the moods/styles within a Music library (A Cappella, Pop Rock etc.)
|
||||||
|
|
||||||
|
* Collections for each of a Trakt Users Lists.
|
||||||
|
|
||||||
|
A full list of the available options is available on the [Dynamic Collections](../../builders/dynamic.md) page
|
||||||
|
After Width: | Height: | Size: 446 KiB |
|
After Width: | Height: | Size: 446 KiB |
|
After Width: | Height: | Size: 458 KiB |
|
After Width: | Height: | Size: 371 KiB |
|
After Width: | Height: | Size: 118 KiB |
|
After Width: | Height: | Size: 1012 KiB |
|
After Width: | Height: | Size: 377 KiB |
|
After Width: | Height: | Size: 456 KiB |
|
After Width: | Height: | Size: 456 KiB |
|
After Width: | Height: | Size: 458 KiB |
@ -0,0 +1,259 @@
|
|||||||
|
# Movie Library Metadata
|
||||||
|
|
||||||
|
You can have the script edit the metadata of Movies by adding them to the `metadata` mapping of a Metadata File.
|
||||||
|
|
||||||
|
An example of multiple metadata edits in a movie library is below:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
metadata:
|
||||||
|
Godzilla (1954):
|
||||||
|
match:
|
||||||
|
title: Godzilla
|
||||||
|
year: 1954
|
||||||
|
content_rating: R
|
||||||
|
Godzilla (1998):
|
||||||
|
match:
|
||||||
|
title: Godzilla
|
||||||
|
year: 1998
|
||||||
|
sort_title: Godzilla 03
|
||||||
|
content_rating: PG-13
|
||||||
|
Shin Godzilla:
|
||||||
|
sort_title: Godzilla 06
|
||||||
|
content_rating: R
|
||||||
|
Godzilla 1985:
|
||||||
|
content_rating: PG
|
||||||
|
"Godzilla 2000: Millennium":
|
||||||
|
originally_available: 1999-08-18
|
||||||
|
Godzilla Against MechaGodzilla:
|
||||||
|
originally_available: 2002-03-23
|
||||||
|
Godzilla Raids Again:
|
||||||
|
content_rating: G
|
||||||
|
originally_available: 1955-05-21
|
||||||
|
Godzilla vs. Biollante:
|
||||||
|
content_rating: PG
|
||||||
|
Godzilla vs. Destoroyah:
|
||||||
|
content_rating: PG
|
||||||
|
originally_available: 1995-01-19
|
||||||
|
Godzilla vs. Gigan:
|
||||||
|
content_rating: G
|
||||||
|
originally_available: 1972-09-14
|
||||||
|
Godzilla vs. Hedorah:
|
||||||
|
content_rating: G
|
||||||
|
originally_available: 1971-04-01
|
||||||
|
Godzilla vs. King Ghidorah:
|
||||||
|
content_rating: PG
|
||||||
|
originally_available: 1991-04-28
|
||||||
|
Godzilla vs. Mechagodzilla:
|
||||||
|
content_rating: G
|
||||||
|
originally_available: 1974-03-24
|
||||||
|
Godzilla vs. Mechagodzilla II:
|
||||||
|
content_rating: PG
|
||||||
|
Godzilla vs. Megaguirus:
|
||||||
|
content_rating: PG
|
||||||
|
originally_available: 2000-08-31
|
||||||
|
Godzilla vs. Megalon:
|
||||||
|
content_rating: G
|
||||||
|
originally_available: 1973-03-17
|
||||||
|
Godzilla vs. Mothra:
|
||||||
|
content_rating: PG
|
||||||
|
originally_available: 1992-04-28
|
||||||
|
Godzilla vs. SpaceGodzilla:
|
||||||
|
content_rating: PG
|
||||||
|
originally_available: 1994-01-19
|
||||||
|
Godzilla, King of the Monsters!:
|
||||||
|
content_rating: G
|
||||||
|
"Godzilla, Mothra and King Ghidorah: Giant Monsters All-Out Attack":
|
||||||
|
content_rating: PG
|
||||||
|
originally_available: 2001-08-31
|
||||||
|
"Godzilla: Final Wars":
|
||||||
|
content_rating: PG
|
||||||
|
originally_available: 2004-12-13
|
||||||
|
"Godzilla: Tokyo S.O.S.":
|
||||||
|
originally_available: 2003-12-14
|
||||||
|
Halloween (Rob Zombie):
|
||||||
|
match:
|
||||||
|
title:
|
||||||
|
- Halloween (Rob Zombie)
|
||||||
|
- Halloween
|
||||||
|
year: 2007
|
||||||
|
"Halo 4: Forward Unto Dawn":
|
||||||
|
match:
|
||||||
|
title:
|
||||||
|
- Halo 4: Forward Unto Dawn
|
||||||
|
- Halo 4 Forward Unto Dawn
|
||||||
|
tmdb_show: 56295
|
||||||
|
content_rating: R
|
||||||
|
```
|
||||||
|
|
||||||
|
## Matching Movies
|
||||||
|
|
||||||
|
The `match` attribute is used to match movies within Plex to that definition within the Metadata file. One definition can match and edit multiple movies. The available matching options are outlined below.
|
||||||
|
|
||||||
|
| Attribute | Description |
|
||||||
|
|:-------------------------------|:------------------------------------------------------------------------------------------------------------------|
|
||||||
|
| `title`<sup>1</sup> | Only matches movies that exactly match the movie's Title. Can be a list (only one needs to match). |
|
||||||
|
| `year` | Only matches movies that were released in the given year. |
|
||||||
|
| `mapping_id`<sup>2</sup> | Only matches movies that have the given TMDb or IMDb ID. |
|
||||||
|
| `edition`<sup>3</sup> | Only matches movies that exactly match the movie's Edition. Can be a list (only one needs to match). |
|
||||||
|
| `edition_contains`<sup>3</sup> | Only matches movies where the movie's Edition contains the given string. Can be a list (only one needs to match). |
|
||||||
|
| `blank_edition`<sup>3</sup> | Only matches movies that have no Edition.<br>**Default:** `false`<br>**Values:** `true` or `false` |
|
||||||
|
|
||||||
|
1. When `title` is not provided and the mapping name was not specified as an ID, the default behaviour is to use the mapping name as `title` for matching.
|
||||||
|
2. When `mapping_id` is not provided and the mapping name was specified as an ID, the default behaviour is to use the mapping name as `mapping_id` for matching.
|
||||||
|
3. When the server does not have a Plex Pass then the Edition Field is not accessible. In this scenario, PMM will check the movie's filepath for `{edition-...}` to determine what the edition is.
|
||||||
|
|
||||||
|
### Examples
|
||||||
|
|
||||||
|
Below are some examples on how movies can be matched.
|
||||||
|
|
||||||
|
#### Example 1 - `title` and `mapping_id`
|
||||||
|
|
||||||
|
The below example shows how `title` and `mapping_id` can be used to match movies.
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
metadata:
|
||||||
|
movie1: # Matches via the title "Star Wars"
|
||||||
|
match:
|
||||||
|
title: Star Wars
|
||||||
|
edits...
|
||||||
|
movie2: # Matches via TMDb ID: 299534
|
||||||
|
match:
|
||||||
|
mapping_id: 299534
|
||||||
|
edits...
|
||||||
|
movie3: # Matches via IMDb ID: tt4154756
|
||||||
|
match:
|
||||||
|
mapping_id: tt4154756
|
||||||
|
edits...
|
||||||
|
movie4: # Matches via the title "9"
|
||||||
|
match:
|
||||||
|
title: 9
|
||||||
|
edits...
|
||||||
|
```
|
||||||
|
|
||||||
|
The Mapping Name can also be used to reduce line-count, as shown here:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
metadata:
|
||||||
|
Star Wars: # Matches via the title "Star Wars"
|
||||||
|
edits...
|
||||||
|
299534: # Matches via TMDb ID: 299534
|
||||||
|
edits...
|
||||||
|
tt4154756: # Matches via IMDb ID: tt4154756
|
||||||
|
edits...
|
||||||
|
"9": # Matches via the title "9"
|
||||||
|
edits...
|
||||||
|
```
|
||||||
|
|
||||||
|
**Note:** to search for a movie titled with a number from the mapping name you must surround the number in quotes like in the example below. Otherwise, it will look for the movie associated with that TMDb ID.
|
||||||
|
|
||||||
|
#### Example 2 - `title` and `year`
|
||||||
|
|
||||||
|
The below example shows how `title` and `year` can be used to match movies.
|
||||||
|
|
||||||
|
In this example, there are two movies in the library called "Godzilla", so the `year` attribute is used to identify which movie is being matched.
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
metadata:
|
||||||
|
Godzilla (1954): # Matches via the title "Godzilla" released in 1954
|
||||||
|
match:
|
||||||
|
title: Godzilla
|
||||||
|
year: 1954
|
||||||
|
edits...
|
||||||
|
Godzilla (1998): # Matches via the title "Godzilla" released in 1998
|
||||||
|
match:
|
||||||
|
title: Godzilla
|
||||||
|
year: 1998
|
||||||
|
edits...
|
||||||
|
```
|
||||||
|
|
||||||
|
#### Example 3 - using `editions`
|
||||||
|
|
||||||
|
The edition attributes can be used to further specify which version of a movie should be matched within Plex.
|
||||||
|
|
||||||
|
This can be combined with Example 1 as follows
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
metadata:
|
||||||
|
movie1: # Matches via the title "Star Wars" and edition containing "4K77"
|
||||||
|
match:
|
||||||
|
title: Star Wars
|
||||||
|
edition_contains: 4K77
|
||||||
|
edits...
|
||||||
|
```
|
||||||
|
|
||||||
|
If you wanted to specify the version of Star Wars which does not have an edition, then the `blank_edition` attribute can be used as shown below:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
metadata:
|
||||||
|
movie1: # Matches via the title "Star Wars" and checks for no edition version
|
||||||
|
match:
|
||||||
|
title: Star Wars
|
||||||
|
blank_edition: true
|
||||||
|
edits...
|
||||||
|
```
|
||||||
|
|
||||||
|
## Metadata Edits
|
||||||
|
|
||||||
|
The available attributes for editing movies are as follows
|
||||||
|
|
||||||
|
### Special Attributes
|
||||||
|
|
||||||
|
| Attribute | Description |
|
||||||
|
|:-----------------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|
||||||
|
| `tmdb_show` | TMDb Show ID to use for metadata. Used when the Movie in your library is actually a miniseries on TMDb. (Example: [Halo 4: Forward Unto Dawn](https://www.themoviedb.org/tv/56295) or [IT](https://www.themoviedb.org/tv/19614)) **This is not used to say this movie is the given ID.** |
|
||||||
|
| `run_definition` | Used to specify if this definition runs.<br>Multiple can be used for one definition as a list or comma separated string. One `false` or unmatched library type will cause it to fail.<br>**Values:** `movie`, `show`, `artist`, `true`, `false` |
|
||||||
|
|
||||||
|
1. If the server does not have a Plex Pass then the Edition Field is not accessible. In this case PMM will check the movies filepath for `{edition-MOVIES EDITION}` to determine what the edition is.
|
||||||
|
|
||||||
|
### General Attributes
|
||||||
|
|
||||||
|
| Attribute | Allowed Values |
|
||||||
|
|:-----------------------|:---------------------------------------------------------------|
|
||||||
|
| `title` | Text to change Title. |
|
||||||
|
| `sort_title` | Text to change Sort Title. |
|
||||||
|
| `edition`<sup>1</sup> | Text to change Edition. |
|
||||||
|
| `original_title` | Text to change Original Title. |
|
||||||
|
| `originally_available` | Date to change Originally Available.<br>**Format:** YYYY-MM-DD |
|
||||||
|
| `content_rating` | Text to change Content Rating. |
|
||||||
|
| `user_rating` | Number to change User Rating. |
|
||||||
|
| `audience_rating` | Number to change Audience Rating. |
|
||||||
|
| `critic_rating` | Number to change Critic Rating. |
|
||||||
|
| `studio` | Text to change Studio. |
|
||||||
|
| `tagline` | Text to change Tagline. |
|
||||||
|
| `summary` | Text to change Summary. |
|
||||||
|
|
||||||
|
1. Requires Plex Pass
|
||||||
|
|
||||||
|
### Tag Attributes
|
||||||
|
|
||||||
|
You can add `.remove` to any tag attribute to only remove those tags i.e. `genre.remove`.
|
||||||
|
|
||||||
|
You can add `.sync` to any tag attribute to sync all tags vs just appending the new ones i.e. `genre.sync`.
|
||||||
|
|
||||||
|
| Attribute | Allowed Values |
|
||||||
|
|:-------------|:-----------------------------------------------------|
|
||||||
|
| `director` | List or comma-separated text of each Director Tag. |
|
||||||
|
| `country` | List or comma-separated text of each Country Tag. |
|
||||||
|
| `genre` | List or comma-separated text of each Genre Tag. |
|
||||||
|
| `writer` | List or comma-separated text of each Writer Tag. |
|
||||||
|
| `producer` | List or comma-separated text of each Producer Tag. |
|
||||||
|
| `collection` | List or comma-separated text of each Collection Tag. |
|
||||||
|
| `label` | List or comma-separated text of each Label Tag. |
|
||||||
|
|
||||||
|
### Image Attributes
|
||||||
|
|
||||||
|
| Attribute | Allowed Values |
|
||||||
|
|:------------------|:-------------------------------------------------|
|
||||||
|
| `url_poster` | URL of image publicly available on the internet. |
|
||||||
|
| `file_poster` | Path to image in the file system. |
|
||||||
|
| `url_background` | URL of image publicly available on the internet. |
|
||||||
|
| `file_background` | Path to image in the file system. |
|
||||||
|
|
||||||
|
### Advanced Attributes
|
||||||
|
|
||||||
|
| Attribute | Allowed Values |
|
||||||
|
|:---------------------------------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|
||||||
|
| `metadata_language`<sup>1</sup> | `default`, `ar-SA`, `ca-ES`, `cs-CZ`, `da-DK`, `de-DE`, `el-GR`, `en-AU`, `en-CA`, `en-GB`, `en-US`, `es-ES`, `es-MX`, `et-EE`, `fa-IR`, `fi-FI`, `fr-CA`, `fr-FR`, `he-IL`, `hi-IN`, `hu-HU`, `id-ID`, `it-IT`, `ja-JP`, `ko-KR`, `lt-LT`, `lv-LV`, `nb-NO`, `nl-NL`, `pl-PL`, `pt-BR`, `pt-PT`, `ro-RO`, `ru-RU`, `sk-SK`, `sv-SE`, `th-TH`, `tr-TR`, `uk-UA`, `vi-VN`, `zh-CN`, `zh-HK`, `zh-TW` |
|
||||||
|
| `use_original_title`<sup>1</sup> | `default`: Library default<br>`no`: No<br>`yes`: Yes |
|
||||||
|
|
||||||
|
1. Must be using the **New Plex Movie Agent**.
|
||||||
@ -0,0 +1,138 @@
|
|||||||
|
# Music Library Metadata
|
||||||
|
|
||||||
|
You can have the script edit the metadata of Artists, Albums, and Tracks by adding them to the `metadata` mapping of a Metadata File.
|
||||||
|
|
||||||
|
An example of multiple metadata edits in a music library is below:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
metadata:
|
||||||
|
"Linkin Park":
|
||||||
|
country: "United States of America"
|
||||||
|
album_sorting: newest
|
||||||
|
albums:
|
||||||
|
"Hybrid Theory":
|
||||||
|
originally_available: "2000-10-24"
|
||||||
|
tracks:
|
||||||
|
1:
|
||||||
|
user_rating: 5
|
||||||
|
"One Step Closer":
|
||||||
|
user_rating: 5
|
||||||
|
"Meteora":
|
||||||
|
originally_available: "2003-03-25"
|
||||||
|
album_sorting: newest
|
||||||
|
tracks:
|
||||||
|
9:
|
||||||
|
user_rating: 5
|
||||||
|
"Numb":
|
||||||
|
user_rating: 5
|
||||||
|
"Minutes To Midnight":
|
||||||
|
originally_available: "2007-05-14"
|
||||||
|
```
|
||||||
|
|
||||||
|
## Matching Artist
|
||||||
|
|
||||||
|
The `match` attribute is used to match artists within Plex to that definition within the Metadata file. One definition can match and edit multiple artists. The available matching options are outlined below.
|
||||||
|
|
||||||
|
| Attribute | Allowed Values |
|
||||||
|
|:-------------------------------|:-----------------------------------------------------------------------------------------------------|
|
||||||
|
| `title`<sup>1</sup> | Only matches artists that exactly match the artist's Title. Can be a list (only one needs to match). |
|
||||||
|
|
||||||
|
1. When `title` is not provided and the mapping name was not specified as an ID, the default behaviour is to use the mapping name as `title` for matching.
|
||||||
|
|
||||||
|
### Examples
|
||||||
|
|
||||||
|
Below are some examples on how artists can be matched.
|
||||||
|
|
||||||
|
#### Example 1 - `title`
|
||||||
|
|
||||||
|
The below example shows how `title` can be used to match artists.
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
metadata:
|
||||||
|
artist1: # Matches via the title "Ke$ha"
|
||||||
|
match:
|
||||||
|
title: Ke$ha
|
||||||
|
edits...
|
||||||
|
artist2: # Matches via the title "311"
|
||||||
|
match:
|
||||||
|
title: 311
|
||||||
|
edits...
|
||||||
|
```
|
||||||
|
|
||||||
|
The Mapping Name can also be used to reduce line-count, as shown here:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
metadata:
|
||||||
|
Ke$ha: # Matches via the Name "Ke$ha"
|
||||||
|
edits...
|
||||||
|
"311": # Matches via the Name "311"
|
||||||
|
edits...
|
||||||
|
```
|
||||||
|
|
||||||
|
## Metadata Edits
|
||||||
|
|
||||||
|
The available attributes for editing artists, albums, and tracks are as follows
|
||||||
|
|
||||||
|
### Special Attributes
|
||||||
|
|
||||||
|
| Attribute | Values | Artists | Album | Tracks |
|
||||||
|
|:------------|:----------------------------------------------------------------------------------------------------------------------|:--------:|:--------:|:--------:|
|
||||||
|
| `albums` | Attribute used to edit album metadata. The mapping name is the album name. | :fontawesome-solid-circle-check:{ .green } | :fontawesome-solid-circle-xmark:{ .red } | :fontawesome-solid-circle-xmark:{ .red } |
|
||||||
|
| `tracks` | Attribute used to edit track metadata. The mapping name is the track number on that Album, or the title of the Track. | :fontawesome-solid-circle-xmark:{ .red } | :fontawesome-solid-circle-check:{ .green } | :fontawesome-solid-circle-xmark:{ .red } |
|
||||||
|
|
||||||
|
* If you know of another Title your item might exist under, but you want it titled differently you can use `alt_title` to specify another title to look under and then be changed to the mapping name. For Example the Artist `Kesha` used to be stylized as `Ke$ha`, and might still be found that way in Metadata results.
|
||||||
|
```yaml
|
||||||
|
metadata:
|
||||||
|
"Kesha":
|
||||||
|
alt_title: "Ke$ha"
|
||||||
|
```
|
||||||
|
This would change the name of the default `Ke$ha` to `Kesha` and would not mess up any subsequent runs.
|
||||||
|
``
|
||||||
|
### General Attributes
|
||||||
|
|
||||||
|
| Attribute | Values | Artists | Album | Tracks |
|
||||||
|
|:-----------------------|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:--------:|:--------:|:--------:|
|
||||||
|
| `title` | Text to change Title. | :fontawesome-solid-circle-xmark:{ .red } | :fontawesome-solid-circle-xmark:{ .red } | :fontawesome-solid-circle-check:{ .green } |
|
||||||
|
| `sort_title` | Text to change Sort Title. | :fontawesome-solid-circle-check:{ .green } | :fontawesome-solid-circle-check:{ .green } | :fontawesome-solid-circle-check:{ .green } |
|
||||||
|
| `user_rating` | Number to change User Rating. | :fontawesome-solid-circle-check:{ .green } | :fontawesome-solid-circle-check:{ .green } | :fontawesome-solid-circle-check:{ .green } |
|
||||||
|
| `critic_rating` | Number to change Critic Rating. | :fontawesome-solid-circle-xmark:{ .red } | :fontawesome-solid-circle-check:{ .green } | :fontawesome-solid-circle-xmark:{ .red } |
|
||||||
|
| `originally_available` | Date to change Originally Available.<br>**Format:** YYYY-MM-DD | :fontawesome-solid-circle-xmark:{ .red } | :fontawesome-solid-circle-check:{ .green } | :fontawesome-solid-circle-xmark:{ .red } |
|
||||||
|
| `record_label` | Text to change Record Label. | :fontawesome-solid-circle-xmark:{ .red } | :fontawesome-solid-circle-check:{ .green } | :fontawesome-solid-circle-xmark:{ .red } |
|
||||||
|
| `summary` | Text to change Summary. | :fontawesome-solid-circle-check:{ .green } | :fontawesome-solid-circle-check:{ .green } | :fontawesome-solid-circle-check:{ .green } |
|
||||||
|
| `track` | Text to change Track. | :fontawesome-solid-circle-xmark:{ .red } | :fontawesome-solid-circle-xmark:{ .red } | :fontawesome-solid-circle-check:{ .green } |
|
||||||
|
| `disc` | Text to change Disc. | :fontawesome-solid-circle-xmark:{ .red } | :fontawesome-solid-circle-xmark:{ .red } | :fontawesome-solid-circle-check:{ .green } |
|
||||||
|
| `original_artist` | Text to change Original Artist. | :fontawesome-solid-circle-xmark:{ .red } | :fontawesome-solid-circle-xmark:{ .red } | :fontawesome-solid-circle-check:{ .green } |
|
||||||
|
| `run_definition` | Used to specify if this definition runs.<br>Multiple can be used for one definition as a list or comma separated string. One `false` or unmatched library type will cause it to fail.<br>**Values:** `movie`, `show`, `artist`, `true`, `false` | :fontawesome-solid-circle-check:{ .green } | :fontawesome-solid-circle-xmark:{ .red } | :fontawesome-solid-circle-xmark:{ .red } |
|
||||||
|
|
||||||
|
### Tag Attributes
|
||||||
|
|
||||||
|
You can add `.remove` to any tag attribute to only remove those tags i.e. `genre.remove`.
|
||||||
|
|
||||||
|
You can add `.sync` to any tag attribute to sync all tags vs just appending the new ones i.e. `genre.sync`.
|
||||||
|
|
||||||
|
| Attribute | Values | Artists | Album | Tracks |
|
||||||
|
|:-----------------|:---------------------------------------------------------|:--------:|:--------:|:--------:|
|
||||||
|
| `genre` | List or comma-separated text of each Genre Tag. | :fontawesome-solid-circle-check:{ .green } | :fontawesome-solid-circle-check:{ .green } | :fontawesome-solid-circle-xmark:{ .red } |
|
||||||
|
| `collection` | List or comma-separated text of each Collection Tag. | :fontawesome-solid-circle-check:{ .green } | :fontawesome-solid-circle-check:{ .green } | :fontawesome-solid-circle-check:{ .green } |
|
||||||
|
| `label` | List or comma-separated text of each Label Tag. | :fontawesome-solid-circle-check:{ .green } | :fontawesome-solid-circle-check:{ .green } | :fontawesome-solid-circle-check:{ .green } |
|
||||||
|
| `style` | List or comma-separated text of each Style Tag. | :fontawesome-solid-circle-check:{ .green } | :fontawesome-solid-circle-check:{ .green } | :fontawesome-solid-circle-xmark:{ .red } |
|
||||||
|
| `mood` | List or comma-separated text of each Mood Tag. | :fontawesome-solid-circle-check:{ .green } | :fontawesome-solid-circle-check:{ .green } | :fontawesome-solid-circle-check:{ .green } |
|
||||||
|
| `country` | List or comma-separated text of each Country Tag. | :fontawesome-solid-circle-check:{ .green } | :fontawesome-solid-circle-xmark:{ .red } | :fontawesome-solid-circle-xmark:{ .red } |
|
||||||
|
| `similar_artist` | List or comma-separated text of each Similar Artist Tag. | :fontawesome-solid-circle-check:{ .green } | :fontawesome-solid-circle-xmark:{ .red } | :fontawesome-solid-circle-xmark:{ .red } |
|
||||||
|
|
||||||
|
### Image Attributes
|
||||||
|
|
||||||
|
| Attribute | Values | Artists | Album | Tracks |
|
||||||
|
|:------------------|:-------------------------------------------------|:-------:|:-------:|:--------:|
|
||||||
|
| `url_poster` | URL of image publicly available on the internet. | :fontawesome-solid-circle-check:{ .green } | :fontawesome-solid-circle-check:{ .green } | :fontawesome-solid-circle-xmark:{ .red } |
|
||||||
|
| `file_poster` | Path to image in the file system. | :fontawesome-solid-circle-check:{ .green } | :fontawesome-solid-circle-check:{ .green } | :fontawesome-solid-circle-xmark:{ .red } |
|
||||||
|
| `url_background` | URL of image publicly available on the internet. | :fontawesome-solid-circle-check:{ .green } | :fontawesome-solid-circle-check:{ .green } | :fontawesome-solid-circle-xmark:{ .red } |
|
||||||
|
| `file_background` | Path to image in the file system. | :fontawesome-solid-circle-check:{ .green } | :fontawesome-solid-circle-check:{ .green } | :fontawesome-solid-circle-xmark:{ .red } |
|
||||||
|
|
||||||
|
### Advanced Attributes
|
||||||
|
|
||||||
|
All these attributes only work with Artists.
|
||||||
|
|
||||||
|
| Attribute | Values |
|
||||||
|
|:----------------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|
||||||
|
| `album_sorting` | <table class="clearTable"><tbody><tr><td>`default`</td><td>Library default</td></tr><tr><td>`oldest`</td><td>Oldest first</td></tr><tr><td>`newest`</td><td>Newest first</td></tr><tr><td>`name`</td><td>Alphabetical</td></tr></tbody></table> |
|
||||||
@ -0,0 +1,210 @@
|
|||||||
|
# TV Show Library Metadata
|
||||||
|
|
||||||
|
You can have the script edit the metadata of Shows, Seasons, and Episodes by adding them to the `metadata` mapping of a Metadata File.
|
||||||
|
|
||||||
|
An example of multiple metadata edits in a show library is below:
|
||||||
|
```yaml
|
||||||
|
metadata:
|
||||||
|
"Avatar: The Last Airbender":
|
||||||
|
sort_title: Avatar 01
|
||||||
|
seasons:
|
||||||
|
1:
|
||||||
|
title: "Book One: Water"
|
||||||
|
summary: >-
|
||||||
|
After a lapse of 100 years, the Avatar-spiritual master of the elements-has returned. And just in
|
||||||
|
the nick of time. The Four Nations (Water, Earth, Fire, and Air) have become unbalanced. The Fire
|
||||||
|
Nation wants to rule the world, and its first conquest will be the Northern Water Tribe. It's up to
|
||||||
|
a 12-year-old Airbender named Aang to find a way to stop it. Join Aang, Katara, Sokka, Momo, and
|
||||||
|
Appa as they head north on the adventure of a lifetime.
|
||||||
|
episodes:
|
||||||
|
1:
|
||||||
|
user_rating: 9.1
|
||||||
|
2:
|
||||||
|
title: "Book Two: Earth"
|
||||||
|
summary: >-
|
||||||
|
Avatar Aang continues his quest to master the four elements before the end of summer. Together with
|
||||||
|
Katara, Sokka, Momo, and Appa, he journeys across the Earth Kingdom in search of an Earthbending
|
||||||
|
mentor. Along the way, he confronts Princess Azula, treacherous daughter of Firelord Ozai and
|
||||||
|
sister to Prince Zuko. More powerful than her brother, Azula will stop nothing to defeat the Avatar.
|
||||||
|
But Aang and the gang find plenty of Earth Kingdom allies to help them along the way. From the swamps
|
||||||
|
of the South to the Earth King's palace, Avatar: Book 2 is an adventure like no other.
|
||||||
|
3:
|
||||||
|
title: "Book Three: Fire"
|
||||||
|
summary: >-
|
||||||
|
Having survived the terrible battle with Azula, Aang faces new challenges as he and his brave
|
||||||
|
friends secretly enter the Fire Nation. Their quest is to find and defeat Firelord Ozai. Along
|
||||||
|
the way, they discover that Ozai has plans of his own. The leader of the Fire Nation intends to
|
||||||
|
use the massive power of Sozin's comet to spread his dominion permanently across the four nations.
|
||||||
|
Short on time, Aang has a lot of bending to learn and no master to help him learn it. However, his
|
||||||
|
friends are there to help, and he finds unexpected allies deep in the heart of the Fire Nation. In
|
||||||
|
the spectacular four-part conclusion, Aang must fulfill his destiny and become a fully realized
|
||||||
|
Avatar, or watch the world go up in smoke.
|
||||||
|
episodes:
|
||||||
|
21:
|
||||||
|
summary: The Epic Series Final of Avatar The Last Airbender
|
||||||
|
"Avatar: The Legend of Korra":
|
||||||
|
match:
|
||||||
|
title:
|
||||||
|
- "Avatar: The Legend of Korra"
|
||||||
|
- The Legend of Korra
|
||||||
|
sort_title: Avatar 02
|
||||||
|
original_title: The Legend of Korra
|
||||||
|
seasons:
|
||||||
|
1:
|
||||||
|
title: "Book One: Air"
|
||||||
|
2:
|
||||||
|
title: "Book Two: Spirits"
|
||||||
|
3:
|
||||||
|
title: "Book Three: Change"
|
||||||
|
4:
|
||||||
|
title: "Book Four: Balance"
|
||||||
|
```
|
||||||
|
|
||||||
|
## Matching Shows
|
||||||
|
|
||||||
|
The `match` attribute is used to match shows within Plex to that definition within the Metadata file. One definition can match and edit multiple shows. The available matching options are outlined below.
|
||||||
|
|
||||||
|
| Attribute | Allowed Values |
|
||||||
|
|:-------------------------------|:------------------------------------------------------------------------------------------------------------------|
|
||||||
|
| `title`<sup>1</sup> | Only matches shows that exactly match the show's Title. Can be a list (only one needs to match). |
|
||||||
|
| `year` | Only matches shows that were released in the given year. |
|
||||||
|
| `mapping_id`<sup>2</sup> | Only matches shows that have the given TVDb or IMDb ID. |
|
||||||
|
|
||||||
|
1. When `title` is not provided and the mapping name was not specified as an ID, the default behaviour is to use the mapping name as `title` for matching.
|
||||||
|
2. When `mapping_id` is not provided and the mapping name was specified as an ID, the default behaviour is to use the mapping name as `mapping_id` for matching.
|
||||||
|
|
||||||
|
### Examples
|
||||||
|
|
||||||
|
Below are some examples on how shows can be matched.
|
||||||
|
|
||||||
|
#### Example 1 - `title` and `mapping_id`
|
||||||
|
|
||||||
|
The below example shows how `title` and `mapping_id` can be used to match shows.
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
metadata:
|
||||||
|
show1: # Matches via the title "Game of Thrones"
|
||||||
|
match:
|
||||||
|
title: Game of Thrones
|
||||||
|
edits...
|
||||||
|
show2: # Matches via TVDb ID: 366524
|
||||||
|
match:
|
||||||
|
mapping_id: 366524
|
||||||
|
edits...
|
||||||
|
show3: # Matches via IMDb ID: tt10234724
|
||||||
|
match:
|
||||||
|
mapping_id: tt10234724
|
||||||
|
edits...
|
||||||
|
show4: # Matches via the title "24"
|
||||||
|
match:
|
||||||
|
title: 24
|
||||||
|
edits...
|
||||||
|
```
|
||||||
|
|
||||||
|
The Mapping Name can also be used to reduce line-count, as shown here:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
metadata:
|
||||||
|
Game of Thrones: # Matches via the Name "Game of Thrones"
|
||||||
|
edits...
|
||||||
|
366524: # Matches via TVDb ID: 366524
|
||||||
|
edits...
|
||||||
|
tt10234724: # Matches via IMDb ID: tt10234724
|
||||||
|
edits...
|
||||||
|
"24": # Matches via the Name "24"
|
||||||
|
edits...
|
||||||
|
```
|
||||||
|
|
||||||
|
**Note:** to search for a show titled with a number from the mapping name you must surround the number in quotes like in the example below. Otherwise, it will look for the show associated with that TVDb ID.
|
||||||
|
|
||||||
|
#### Example 2 - `title` and `year`
|
||||||
|
|
||||||
|
The below example shows how `title` and `year` can be used to match shows.
|
||||||
|
|
||||||
|
In this example, there are two shows in the library called "Vikings", so the `year` attribute is used to identify which show is being matched.
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
metadata:
|
||||||
|
Vikings (2012): # Matches via the title "Vikings" released in 2012
|
||||||
|
match:
|
||||||
|
title: Vikings
|
||||||
|
year: 2012
|
||||||
|
edits...
|
||||||
|
Vikings (2013): # Matches via the title "Vikings" released in 2013
|
||||||
|
match:
|
||||||
|
title: Vikings
|
||||||
|
year: 2013
|
||||||
|
edits...
|
||||||
|
```
|
||||||
|
|
||||||
|
## Metadata Edits
|
||||||
|
|
||||||
|
The available attributes for editing shows, seasons, and episodes are as follows
|
||||||
|
|
||||||
|
### Special Attributes
|
||||||
|
|
||||||
|
| Attribute | Description | Shows | Seasons | Episodes |
|
||||||
|
|:------------------|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:--------:|:--------:|:--------:|
|
||||||
|
| `f1_season` | F1 Season Year to make the Show represent a Season of F1 Races. See [Formula 1 Metadata Guide](../../../pmm/install/guides/formula.md) for more information. | :fontawesome-solid-circle-check:{ .green } | :fontawesome-solid-circle-xmark:{ .red } | :fontawesome-solid-circle-xmark:{ .red } |
|
||||||
|
| `round_prefix` | Used only with `f1_season` to add the round as a prefix to the Season (Race) Titles i.e. `Australian Grand Prix` --> `01 - Australian Grand Prix`. | :fontawesome-solid-circle-check:{ .green } | :fontawesome-solid-circle-xmark:{ .red } | :fontawesome-solid-circle-xmark:{ .red } |
|
||||||
|
| `shorten_gp` | Used only with `f1_season` to shorten `Grand Prix` to `GP` in the Season (Race) Titles i.e. `Australian Grand Prix` --> `Australian GP`. | :fontawesome-solid-circle-check:{ .green } | :fontawesome-solid-circle-xmark:{ .red } | :fontawesome-solid-circle-xmark:{ .red } |
|
||||||
|
| `seasons` | Attribute used to edit season metadata. The mapping name is the season number (use 0 for specials) or the season name. | :fontawesome-solid-circle-check:{ .green } | :fontawesome-solid-circle-xmark:{ .red } | :fontawesome-solid-circle-xmark:{ .red } |
|
||||||
|
| `episodes` | Attribute used to edit episode metadata. The mapping name is the episode number in that season, the title of the episode, or the Originally Available date in the format `MM/DD`. | :fontawesome-solid-circle-xmark:{ .red } | :fontawesome-solid-circle-check:{ .green } | :fontawesome-solid-circle-xmark:{ .red } |
|
||||||
|
| `run_definition` | Used to specify if this definition runs.<br>Multiple can be used for one definition as a list or comma separated string. One `false` or unmatched library type will cause it to fail.<br>**Values:** `movie`, `show`, `artist`, `true`, `false` | :fontawesome-solid-circle-check:{ .green } | :fontawesome-solid-circle-xmark:{ .red } | :fontawesome-solid-circle-xmark:{ .red } |
|
||||||
|
| `update_seasons` | Used to specify if this definition's seasons metadata will update.<br>Multiple can be used for one definition as a list or comma separated string. One `false` will cause it to fail.<br>**Values:** `true`, `false` | :fontawesome-solid-circle-check:{ .green } | :fontawesome-solid-circle-xmark:{ .red } | :fontawesome-solid-circle-xmark:{ .red } |
|
||||||
|
| `update_episodes` | Used to specify if this definition's episodes metadata will update.<br>Multiple can be used for one definition as a list or comma separated string. One `false` will cause it to fail.<br>**Values:** `true`, `false` | :fontawesome-solid-circle-check:{ .green } | :fontawesome-solid-circle-xmark:{ .red } | :fontawesome-solid-circle-xmark:{ .red } |
|
||||||
|
|
||||||
|
### General Attributes
|
||||||
|
|
||||||
|
| Attribute | Allowed Values | Shows | Seasons | Episodes |
|
||||||
|
|:-----------------------|:---------------------------------------------------------------|:-------:|:--------:|:--------:|
|
||||||
|
| `title` | Text to change Title. | :fontawesome-solid-circle-check:{ .green } | :fontawesome-solid-circle-check:{ .green } | :fontawesome-solid-circle-check:{ .green } |
|
||||||
|
| `sort_title` | Text to change Sort Title. | :fontawesome-solid-circle-check:{ .green } | :fontawesome-solid-circle-xmark:{ .red } | :fontawesome-solid-circle-check:{ .green } |
|
||||||
|
| `original_title` | Text to change Original Title. | :fontawesome-solid-circle-check:{ .green } | :fontawesome-solid-circle-xmark:{ .red } | :fontawesome-solid-circle-xmark:{ .red } |
|
||||||
|
| `originally_available` | Date to change Originally Available.<br>**Format:** YYYY-MM-DD | :fontawesome-solid-circle-check:{ .green } | :fontawesome-solid-circle-xmark:{ .red } | :fontawesome-solid-circle-check:{ .green } |
|
||||||
|
| `content_rating` | Text to change Content Rating. | :fontawesome-solid-circle-check:{ .green } | :fontawesome-solid-circle-xmark:{ .red } | :fontawesome-solid-circle-check:{ .green } |
|
||||||
|
| `user_rating` | Number to change User Rating. | :fontawesome-solid-circle-check:{ .green } | :fontawesome-solid-circle-check:{ .green } | :fontawesome-solid-circle-check:{ .green } |
|
||||||
|
| `audience_rating` | Number to change Audience Rating. | :fontawesome-solid-circle-check:{ .green } | :fontawesome-solid-circle-xmark:{ .red } | :fontawesome-solid-circle-check:{ .green } |
|
||||||
|
| `critic_rating` | Number to change Critic Rating. | :fontawesome-solid-circle-check:{ .green } | :fontawesome-solid-circle-xmark:{ .red } | :fontawesome-solid-circle-check:{ .green } |
|
||||||
|
| `studio` | Text to change Studio. | :fontawesome-solid-circle-check:{ .green } | :fontawesome-solid-circle-xmark:{ .red } | :fontawesome-solid-circle-xmark:{ .red } |
|
||||||
|
| `tagline` | Text to change Tagline. | :fontawesome-solid-circle-check:{ .green } | :fontawesome-solid-circle-xmark:{ .red } | :fontawesome-solid-circle-xmark:{ .red } |
|
||||||
|
| `summary` | Text to change Summary. | :fontawesome-solid-circle-check:{ .green } | :fontawesome-solid-circle-check:{ .green } | :fontawesome-solid-circle-check:{ .green } |
|
||||||
|
|
||||||
|
### Tag Attributes
|
||||||
|
|
||||||
|
You can add `.remove` to any tag attribute to only remove those tags i.e. `genre.remove`.
|
||||||
|
|
||||||
|
You can add `.sync` to any tag attribute to sync all tags vs just appending the new ones i.e. `genre.sync`.
|
||||||
|
|
||||||
|
| Attribute | Allowed Values | Shows | Seasons | Episodes |
|
||||||
|
|:-------------|:-----------------------------------------------------|:--------:|:--------:|:--------:|
|
||||||
|
| `director` | List or comma-separated text of each Director Tag. | :fontawesome-solid-circle-xmark:{ .red } | :fontawesome-solid-circle-xmark:{ .red } | :fontawesome-solid-circle-check:{ .green } |
|
||||||
|
| `genre` | List or comma-separated text of each Genre Tag. | :fontawesome-solid-circle-check:{ .green } | :fontawesome-solid-circle-xmark:{ .red } | :fontawesome-solid-circle-xmark:{ .red } |
|
||||||
|
| `writer` | List or comma-separated text of each Writer Tag. | :fontawesome-solid-circle-xmark:{ .red } | :fontawesome-solid-circle-xmark:{ .red } | :fontawesome-solid-circle-check:{ .green } |
|
||||||
|
| `collection` | List or comma-separated text of each Collection Tag. | :fontawesome-solid-circle-check:{ .green } | :fontawesome-solid-circle-check:{ .green } | :fontawesome-solid-circle-check:{ .green } |
|
||||||
|
| `label` | List or comma-separated text of each Label Tag. | :fontawesome-solid-circle-check:{ .green } | :fontawesome-solid-circle-check:{ .green } | :fontawesome-solid-circle-check:{ .green } |
|
||||||
|
|
||||||
|
### Image Attributes
|
||||||
|
|
||||||
|
| Attribute | Allowed Values | Shows | Seasons | Episodes |
|
||||||
|
|:------------------|:-------------------------------------------------|:-------:|:-------:|:--------:|
|
||||||
|
| `url_poster` | URL of image publicly available on the internet. | :fontawesome-solid-circle-check:{ .green } | :fontawesome-solid-circle-check:{ .green } | :fontawesome-solid-circle-check:{ .green } |
|
||||||
|
| `file_poster` | Path to image in the file system. | :fontawesome-solid-circle-check:{ .green } | :fontawesome-solid-circle-check:{ .green } | :fontawesome-solid-circle-check:{ .green } |
|
||||||
|
| `url_background` | URL of image publicly available on the internet. | :fontawesome-solid-circle-check:{ .green } | :fontawesome-solid-circle-check:{ .green } | :fontawesome-solid-circle-check:{ .green } |
|
||||||
|
| `file_background` | Path to image in the file system. | :fontawesome-solid-circle-check:{ .green } | :fontawesome-solid-circle-check:{ .green } | :fontawesome-solid-circle-check:{ .green } |
|
||||||
|
|
||||||
|
### Advanced Attributes
|
||||||
|
|
||||||
|
All these attributes only work with Shows.
|
||||||
|
|
||||||
|
| Attribute | Allowed Values |
|
||||||
|
|:---------------------------------|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|
||||||
|
| `episode_sorting` | <table class="clearTable"><tbody><tr><td>`default`</td><td>Library default</td></tr><tr><td>`oldest`</td><td>Oldest first</td></tr><tr><td>`newest`</td><td>Newest first</td></tr></tbody></table> |
|
||||||
|
| `keep_episodes` | <table class="clearTable"><tbody><tr><td>`all`</td><td>All episodes</td></tr><tr><td>`5_latest`</td><td>5 latest episodes</td></tr><tr><td>`3_latest`</td><td>3 latest episodes</td></tr><tr><td>`latest`</td><td>Latest episodes</td></tr><tr><td>`past_3`</td><td>Episodes added in the past 3 days</td></tr><tr><td>`past_7`</td><td>Episodes added in the past 7 days</td></tr><tr><td>`past_30`</td><td>Episodes added in the past 30 days</td></tr></tbody></table> |
|
||||||
|
| `delete_episodes` | <table class="clearTable"><tbody><tr><td>`never`</td><td>Never</td></tr><tr><td>`day`</td><td>After a day</td></tr><tr><td>`week`</td><td>After a week</td></tr><tr><td>`refresh`</td><td>On next refresh</td></tr></tbody></table> |
|
||||||
|
| `season_display` | <table class="clearTable"><tbody><tr><td>`default`</td><td>Library default</td></tr><tr><td>`show`</td><td>Show</td></tr><tr><td>`hide`</td><td>Hide</td></tr></tbody></table> |
|
||||||
|
| `episode_ordering` | <table class="clearTable"><tbody><tr><td>`default`</td><td>Library default</td></tr><tr><td>`tmdb_aired`</td><td>The Movie Database (Aired)</td></tr><tr><td>`tvdb_aired`</td><td>TheTVDb (Aired)</td></tr><tr><td>`tvdb_dvd`</td><td>TheTVDb (DVD)</td></tr><tr><td>`tvdb_absolute`</td><td>TheTVDb (Absolute)</td></tr></tbody></table> |
|
||||||
|
| `metadata_language`<sup>1</sup> | `default`, `ar-SA`, `ca-ES`, `cs-CZ`, `da-DK`, `de-DE`, `el-GR`, `en-AU`, `en-CA`, `en-GB`, `en-US`, `es-ES`, `es-MX`, `et-EE`, `fa-IR`, `fi-FI`, `fr-CA`, `fr-FR`, `he-IL`, `hi-IN`, `hu-HU`, `id-ID`, `it-IT`, `ja-JP`, `ko-KR`, `lt-LT`, `lv-LV`, `nb-NO`, `nl-NL`, `pl-PL`, `pt-BR`, `pt-PT`, `ro-RO`, `ru-RU`, `sk-SK`, `sv-SE`, `th-TH`, `tr-TR`, `uk-UA`, `vi-VN`, `zh-CN`, `zh-HK`, `zh-TW` |
|
||||||
|
| `use_original_title`<sup>1</sup> | <table class="clearTable"><tbody><tr><td>`default`</td><td>Library default</td></tr><tr><td>`no`</td><td>No</td></tr><tr><td>`yes`</td><td>Yes</td></tr></tbody></table> |
|
||||||
|
|
||||||
|
1. Must be using the **New Plex TV Agent**
|
||||||
|
After Width: | Height: | Size: 452 KiB |
@ -0,0 +1,626 @@
|
|||||||
|
# Overlay Files
|
||||||
|
|
||||||
|
Overlay Files holds information on how Plex Meta Manager should create Overlays. There are a large number of builders available to build Overlays,
|
||||||
|
|
||||||
|
## Overview
|
||||||
|
|
||||||
|
This example is an Overlay file with a basic overlay which is saved in a file called `MyOverlays.yml` within the location mapped as `config` in my setup.
|
||||||
|
|
||||||
|
This specific example will target items in my library with a 4K resolution and will add an overlay with text that says "Direct Play" located at the bottom of the poster in the center.
|
||||||
|
|
||||||
|
???+ tip "Example Overlay"
|
||||||
|
|
||||||
|
Click the :fontawesome-solid-circle-plus: icon to learn more
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
overlays: #(1)!
|
||||||
|
directplay:
|
||||||
|
overlay:
|
||||||
|
name: text(Direct Play) #(2)!
|
||||||
|
horizontal_offset: 0
|
||||||
|
horizontal_align: center
|
||||||
|
vertical_offset: 150
|
||||||
|
vertical_align: bottom
|
||||||
|
font_size: 63
|
||||||
|
font_color: "#FFFFFF"
|
||||||
|
back_color: "#00000099"
|
||||||
|
back_radius: 30
|
||||||
|
back_padding: 30
|
||||||
|
plex_search: #(3)!
|
||||||
|
all:
|
||||||
|
resolution: 4K
|
||||||
|
```
|
||||||
|
|
||||||
|
1. This must appear once and **only once** in any Overlay file
|
||||||
|
2. This tells PMM to use text as the overlay rather than an image
|
||||||
|
3. This is the criteria that PMM will use to define what should receive the overlay
|
||||||
|
|
||||||
|
Here is an example of how the Overlay will look
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
For the purpose of this example, we are going to save the File as `MyOverlays.yml` within the location mapped as `config` in our setup.
|
||||||
|
|
||||||
|
I then call "MyOverlays.yml" in my [Configuration File](../configuration.md) within the `Overlay_files` section
|
||||||
|
|
||||||
|
???+ example "config.yml Example Overlay File Addition"
|
||||||
|
|
||||||
|
Click the :fontawesome-solid-circle-plus: icon to learn more
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
libraries:
|
||||||
|
Movies: #(1)!
|
||||||
|
overlay_files:
|
||||||
|
- remove_overlays: false
|
||||||
|
- file: config/MyOverlays.yml #(2)!
|
||||||
|
```
|
||||||
|
|
||||||
|
1. This must match the name of a library in your Plex server
|
||||||
|
2. `config` refers to the location that you mapped to `config` when following the PMM Installation Guides.
|
||||||
|
|
||||||
|
???+ example "config.yml Example Collection File Addition"
|
||||||
|
|
||||||
|
Click the :fontawesome-solid-circle-plus: icon to learn more
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
libraries:
|
||||||
|
Movies: #(1)!
|
||||||
|
Overlay_files:
|
||||||
|
- file: config/MyOverlays.yml #(2)!
|
||||||
|
```
|
||||||
|
|
||||||
|
1. This must match the name of a library in your Plex server
|
||||||
|
2. `config` refers to the location that you mapped to `config` when following the PMM Installation Guides.
|
||||||
|
|
||||||
|
Whenever I execute Plex Meta Manager and the Movies library is run, MyOverlays.yml will run and my "Direct Play" overlay will appear on all items with a 4K resolution.
|
||||||
|
|
||||||
|
## File Attributes
|
||||||
|
|
||||||
|
Overlay Files can utilize the following top-level attributes
|
||||||
|
|
||||||
|
| Attribute | Description |
|
||||||
|
|:-----------------------------------------------------------------------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|
||||||
|
| [`templates`](../../builders/templates.md) | contains definitions of templates that can be leveraged by multiple Overlays |
|
||||||
|
| [`external_templates`](../../builders/templates.md#external-templates) | contains [path types](../paths.md) that point to external templates that can be leveraged by multiple Overlays |
|
||||||
|
| [`overlays`](#overlay-attributes) | contains definitions of Overlays you wish to add to one or more libraries |
|
||||||
|
|
||||||
|
* Example Files can be found in the [Plex Meta Manager Configs Repository](https://github.com/meisnate12/Plex-Meta-Manager-Configs/tree/master/PMM)
|
||||||
|
|
||||||
|
## Overlay Understandings
|
||||||
|
|
||||||
|
???+ danger "Important Notes"
|
||||||
|
|
||||||
|
When using overlays, there is some knowledge that you should be aware of at all times. This is outlined below.
|
||||||
|
|
||||||
|
Failure to understand all of these points may cause issues when utilizing Overlays.
|
||||||
|
|
||||||
|
All overlay coordinates assume 1000 x 1500 for Posters and 1920 x 1080 for Backgrounds and Title Cards.
|
||||||
|
|
||||||
|
All overlays should be in a format that is supports transparency should it be required (i.e. PNG)
|
||||||
|
|
||||||
|
If an overlay is not 1000 x 1500 or 1920 x 1080 in size, you will need to use positional attributes to specify where on the base poster the Overlay should be. This is exampled in [Overview](#overview)
|
||||||
|
|
||||||
|
Although Overlays are modular in that you can pick and choose what you would like to apply, each overlay you want to apply **must** be executed in the same Plex Meta Manager run and should not be scheduled, this will result in overlays that are not scheduled to run being deleted.
|
||||||
|
|
||||||
|
* For example, you cannot schedule a "4K Resolution" overlay to only apply on a Monday and a "Direct Play" overlay to only apply on a Tuesday. This will not work, both overlays must be scheduled to run at the same time.
|
||||||
|
|
||||||
|
Plex Meta Manager and Plex **will not** remove old Overlaid images from the Plex file structure or database when new updates are available. On large libraries, this can often result in Image Bloat.
|
||||||
|
|
||||||
|
* We recommend you read more about this and the solution on the [Plex Image Cleanup](../../pmm/essentials/scripts/image-cleanup.md) page.
|
||||||
|
|
||||||
|
There is an attribute called `reapply_overlays` which, when set to true, will force overlays to reapply even when it is not necessary to do so [overlays only update when something has changed, this bypasses that behaviour]. This will increase how long Plex Meta Manager takes to run and will also result in Image Bloat.
|
||||||
|
|
||||||
|
* Ensure `reapply_overlays` is set to `false` if you see it in your Configuration File. If it has previously been set to true we recommend using [Plex Image Cleanup](../../pmm/essentials/scripts/image-cleanup.md) to get rid of the bloat.
|
||||||
|
|
||||||
|
To remove all overlays from your library, add `remove_overlays: true` to the `overlay_files` [Libraries Attribute](../libraries.md#remove-overlays).**
|
||||||
|
|
||||||
|
* See the above note on Plex Meta Manager not removing the overlaid images, this is still true here.
|
||||||
|
|
||||||
|
|
||||||
|
???+ danger "Important Notice"
|
||||||
|
|
||||||
|
Once you have applied overlays to your posters in Plex, it is highly recommended that you never change artwork on a thing directly in Plex again. PMM uses labels on the items in Plex to decide if an overlay has been applied, so if you change artwork behind PMM's back things can become confused and items can end up with double-overlaid posters. It's recommended to set new artwork using the asset directory, which will ensure that this doesn't happen.
|
||||||
|
|
||||||
|
**To change a single overlay original image either remove the `Overlay` shared label and update the Image in Plex or replace the image in the assets folder and then PMM will overlay the new image**
|
||||||
|
|
||||||
|
## Overlay Attributes
|
||||||
|
|
||||||
|
Overlay Files can utilize the following top-level attributes
|
||||||
|
|
||||||
|
| Attribute | Description |
|
||||||
|
|:--------------------------------------------------------|:-------------------------------------------------------------------------------------------------------------------|
|
||||||
|
| [`templates`](../../builders/templates.md) | contains definitions of templates that can be leveraged by multiple overlays |
|
||||||
|
| [`external_templates`](../../builders/templates.md#external-templates) | contains [path types](../paths.md) that point to external templates that can be leveraged by multiple overlays |
|
||||||
|
| [`queues`](#overlay-queues) | contains the positional attributes of queues |
|
||||||
|
| [`overlays`](#overlays-attributes) | contains definitions of overlays you wish to add |
|
||||||
|
|
||||||
|
* `overlays` is required in order to run the Overlay File.
|
||||||
|
* Example Overlay Files can be found in the [Plex Meta Manager Configs Repository](https://github.com/meisnate12/Plex-Meta-Manager-Configs/tree/master/PMM)
|
||||||
|
|
||||||
|
There are multiple types of attributes that can be utilized within an overlay:
|
||||||
|
|
||||||
|
* [Builders](../../builders/overview.md)
|
||||||
|
* [Settings/Updates](../../metadata/update.md)
|
||||||
|
* [Filters](../../builders/filters.md)
|
||||||
|
|
||||||
|
## Example Files
|
||||||
|
|
||||||
|
Below is a common Overlay File which will create an Overlay for all items which have a 4K resolution.
|
||||||
|
|
||||||
|
To get you started, Plex Meta Manager includes three files for Overlays - 4K, Dolby and HDR.
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
overlays:
|
||||||
|
4K:
|
||||||
|
plex_search:
|
||||||
|
all:
|
||||||
|
resolution: 4K
|
||||||
|
```
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
I can then layer another Overlay for items which have HDR.
|
||||||
|
|
||||||
|
Plex Meta Manager will apply Overlays in the order they are defined in the file, so my HDR overlay appears on top of my 4K overlay in this scenario.
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
overlays:
|
||||||
|
4K:
|
||||||
|
plex_search:
|
||||||
|
all:
|
||||||
|
resolution: 4K
|
||||||
|
HDR:
|
||||||
|
plex_search:
|
||||||
|
all:
|
||||||
|
hdr: true
|
||||||
|
```
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
## Advanced Overlay Attributes
|
||||||
|
|
||||||
|
The below attributes are also available for Overlay files, to give more granular control over how they function.
|
||||||
|
|
||||||
|
|
||||||
|
| Attribute | Description | Required |
|
||||||
|
|:---------------------------|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:--------:|
|
||||||
|
| `name` | Name of the overlay. | ✅ |
|
||||||
|
| `file` | Local location of the Overlay Image. | ❌ |
|
||||||
|
| `url` | URL of Overlay Image Online. | ❌ |
|
||||||
|
| `git` | Location in the [Configs Repo](https://github.com/meisnate12/Plex-Meta-Manager-Configs) of the Overlay Image. | ❌ |
|
||||||
|
| `repo` | Location in the [Custom Repo](../settings.md#custom-repo) of the Overlay Image. | ❌ |
|
||||||
|
| [`group`](#overlay-groups) | Name of the Grouping for this overlay. Only one overlay with the highest weight per group will be applied.<br>**`weight` is required when using `group`**<br>**Values:** group name | ❌ |
|
||||||
|
| [`queue`](#overlay-queues) | Name of the Queue for this overlay. Define `queue` positions using the `queues` attribute at the top level of an Overlay File. Overlay with the highest weight is applied to the first position and so on.<br>**`weight` is required when using `queue`**<br>**Values:** queue name | ❌ |
|
||||||
|
| `weight` | Weight of this overlay in its group or queue.<br>**`group` or `queue` is required when using `weight`**<br>**Values:** Integer 0 or greater | ❌ |
|
||||||
|
| `horizontal_offset` | Horizontal Offset of this overlay. Can be a %.<br>**`vertical_offset` is required when using `horizontal_offset`**<br>**Value:** Integer 0 or greater or 0%-100% | ❌ |
|
||||||
|
| `horizontal_align` | Horizontal Alignment of the overlay.<br>**Values:** `left`, `center`, `right` | ❌ |
|
||||||
|
| `vertical_offset` | Vertical Offset of this overlay. Can be a %.<br>**`horizontal_offset` is required when using `vertical_offset`**<br>**Value:** Integer 0 or greater or 0%-100% | ❌ |
|
||||||
|
| `vertical_align` | Vertical Alignment of the overlay.<br>**Values:** `top`, `center`, `bottom` | ❌ |
|
||||||
|
| `font` | System Font Filename or path to font file for the Text Overlay.<br>**Value:** System Font Filename or path to font file | ❌ |
|
||||||
|
| `font_style` | Font style for Variable Fonts. Only needed when using a Variable Font.<br>**Value:** Variable Font Style | ❌ |
|
||||||
|
| `font_size` | Font Size for the Text Overlay.<br>**Value:** Integer greater than 0 | ❌ |
|
||||||
|
| `font_color` | Font Color for the Text Overlay.<br>**Value:** Color Hex Code in format `#RGB`, `#RGBA`, `#RRGGBB` or `#RRGGBBAA`. | ❌ |
|
||||||
|
| `stroke_width` | Font Stroke Width for the Text Overlay.<br>**Value:** Integer greater than 0 | ❌ |
|
||||||
|
| `stroke_color` | Font Stroke Color for the Text Overlay.<br>**Value:** Color Hex Code in format `#RGB`, `#RGBA`, `#RRGGBB` or `#RRGGBBAA`. | ❌ |
|
||||||
|
| `back_color` | Backdrop Color for the Text Overlay.<br>**Value:** Color Hex Code in format `#RGB`, `#RGBA`, `#RRGGBB` or `#RRGGBBAA`. | ❌ |
|
||||||
|
| `back_width` | Backdrop Width for the Text Overlay. If `back_width` is not specified the Backdrop Sizes to the text<br>**`back_height` is required when using `back_width`**<br>**Value:** Integer greater than 0 | ❌ |
|
||||||
|
| `back_height` | Backdrop Height for the Text Overlay. If `back_height` is not specified the Backdrop Sizes to the text<br>**`back_width` is required when using `back_height`**<br>**Value:** Integer greater than 0 | ❌ |
|
||||||
|
| `back_align` | Alignment for the Text Overlay inside the backdrop. If `back_align` is not specified the Backdrop Centers the text<br>**`back_width` and `back_height` are required when using `back_align`**<br>**Values:** `left`, `right`, `center`, `top`, `bottom` | ❌ |
|
||||||
|
| `back_padding` | Backdrop Padding for the Text Overlay.<br>**Value:** Integer greater than 0 | ❌ |
|
||||||
|
| `back_radius` | Backdrop Radius for the Text Overlay.<br>**Value:** Integer greater than 0 | ❌ |
|
||||||
|
| `back_line_color` | Backdrop Line Color for the Text Overlay.<br>**Value:** Color Hex Code in format `#RGB`, `#RGBA`, `#RRGGBB` or `#RRGGBBAA`. | ❌ |
|
||||||
|
| `back_line_width` | Backdrop Line Width for the Text Overlay.<br>**Value:** Integer greater than 0 | ❌ |
|
||||||
|
| `addon_offset` | Text Addon Image Offset from the text.<br>**`addon_offset` Only works with text overlays**<br>**Value:** Integer 0 or greater | ❌ |
|
||||||
|
| `addon_position` | Text Addon Image Alignment in relation to the text.<br>**`addon_position` Only works with text overlays**<br>**Values:** `left`, `right`, `top`, `bottom` | ❌ |
|
||||||
|
|
||||||
|
* If `url`, `git`, and `repo` are all not defined then PMM will look in your `config/overlays` folder for a `.png` file named the same as the `name` attribute.
|
||||||
|
|
||||||
|
|
||||||
|
### Positional Image Overlays
|
||||||
|
|
||||||
|
Positional overlays can be of any size and use `horizontal_offset`, `horizontal_align`, `vertical_offset`, and `vertical_align` to position the overlay on the image.
|
||||||
|
|
||||||
|
???+ tip
|
||||||
|
|
||||||
|
This overlay example uses one of the [PMM Default Overlay](../../defaults/overlays.md) images, which isn't necessary but is used just for this example.
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
overlays:
|
||||||
|
IMDB-Top-250:
|
||||||
|
imdb_chart: top_movies
|
||||||
|
overlay:
|
||||||
|
name: IMDB-Top-250
|
||||||
|
pmm: ribbon/yellow/imdb.png
|
||||||
|
horizontal_offset: 0
|
||||||
|
horizontal_align: right
|
||||||
|
vertical_offset: 0
|
||||||
|
vertical_align: bottom
|
||||||
|
```
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
### Blurring Overlay
|
||||||
|
|
||||||
|
There is a special overlay named `blur` that when given as the overlay name will instead of finding the image will just blur the image instead.
|
||||||
|
|
||||||
|
You can control the level of the blur by providing a number with the attribute like so `blur(##)`.
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
overlays:
|
||||||
|
blur:
|
||||||
|
overlay:
|
||||||
|
name: blur(50)
|
||||||
|
builder_level: episode
|
||||||
|
plex_search:
|
||||||
|
all:
|
||||||
|
resolution: 4K
|
||||||
|
```
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
### Backdrop Overlay
|
||||||
|
|
||||||
|
There is a special overlay named `backdrop` that when given as the overlay name will instead of finding the image will just apply the background instead.
|
||||||
|
|
||||||
|
You can set the size of the backdrop with `back_width` and `back_height`. By Default, they will extend the length of the Image.
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
overlays:
|
||||||
|
backdrop:
|
||||||
|
overlay:
|
||||||
|
name: backdrop
|
||||||
|
back_color: "#00000099"
|
||||||
|
back_height: 100
|
||||||
|
vertical_position: top
|
||||||
|
plex_all: true
|
||||||
|
```
|
||||||
|
|
||||||
|
This example could be useful if you want to have a black banner, and then use a [Text Overlay](#text-overlay) to add text on top.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
### Text Overlay
|
||||||
|
|
||||||
|
You can add text as an overlay using the special `text()` overlay name. Anything inside the parentheses will be added as an overlay onto the image. Ex `text(4K)` adds `4K` to the image.
|
||||||
|
|
||||||
|
You can control the font, font size and font color using the `font`, `font_size`, and `font_color` overlay attributes.
|
||||||
|
|
||||||
|
You can control the backdrop of the text using the various `back_*` attributes.
|
||||||
|
|
||||||
|
The `horizontal_offset` and `vertical_offset` overlay attributes are required when using Text Overlays.
|
||||||
|
|
||||||
|
PMM includes multiple fonts in the [`fonts` folder](https://github.com/meisnate12/Plex-Meta-Manager/tree/master/fonts) which can be called using `fonts/fontname.ttf`
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
overlays:
|
||||||
|
backdrop:
|
||||||
|
overlay:
|
||||||
|
name: backdrop
|
||||||
|
back_color: "#00000099"
|
||||||
|
back_height: 100
|
||||||
|
vertical_position: top
|
||||||
|
plex_all: true
|
||||||
|
mytext:
|
||||||
|
overlay:
|
||||||
|
name: text(This Movie Is Awesome)
|
||||||
|
horizontal_offset: 0
|
||||||
|
horizontal_align: center
|
||||||
|
vertical_offset: 30
|
||||||
|
vertical_align: top
|
||||||
|
font_size: 63
|
||||||
|
font_color: "#FFFFFF"
|
||||||
|
plex_all: true
|
||||||
|
```
|
||||||
|
|
||||||
|
Note that we have built up on our backdrop overlay that we created in our previous example
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
#### Special Text Variables
|
||||||
|
|
||||||
|
You can use the item's metadata to determine the text by adding Special Text Variables to your text Overlay.
|
||||||
|
|
||||||
|
There are multiple Special Text Variables that can be used when formatting the text. The variables are defined like so `<<name>>` and some can have modifiers like so `<<name$>>` where `$` is the modifier. The available options are:
|
||||||
|
|
||||||
|
| Special Text Variables & Mods | Movies | Shows | Seasons | Episodes |
|
||||||
|
|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:--------:|:--------:|:--------:|:--------:|
|
||||||
|
| `<<audience_rating>>`: audience rating (`8.7`, `9.0`)<br>`<<audience_rating%>>`: audience rating out of 100 (`87`, `90`)<br>`<<audience_rating#>>`: audience rating removing `.0` as needed (`8.7`, `9`)<br>`<<audience_rating/>>`: audience rating on a 5 point scale (`8.6` shows as `4.3`) | ✅ | ✅ | ❌ | ✅ |
|
||||||
|
| `<<critic_rating>>`: critic rating (`8.7`, `9.0`)<br>`<<critic_rating%>>`: critic rating out of 100 (`87`, `90`)<br>`<<critic_rating#>>`: critic rating removing `.0` as needed (`8.7`, `9`)<br>`<<critic_rating/>>`: critic rating on a 5 point scale (`8.6` shows as `4.3`) | ✅ | ✅ | ❌ | ✅ |
|
||||||
|
| `<<user_rating>>`: user rating (`8.7`, `9.0`)<br>`<<user_rating%>>`: user rating out of 100 (`87`, `90`)<br>`<<user_rating#>>`: user rating removing `.0` as needed (`8.7`, `9`)<br>`<<user_rating/>>`: user rating on a 5 point scale (`8.6` shows as `4.3`) | ✅ | ✅ | ✅ | ✅ |
|
||||||
|
| `<<title>>`: Title of the Item<br>`<<titleU>>`: Uppercase Title of the Item<br>`<<titleL>>`Lowercase Title of the Item<br>`<<titleP>>`Proper Title of the Item | ✅ | ✅ | ✅ | ✅ |
|
||||||
|
| `<<show_title>>`: Title of the Item's Show<br>`<<show_itleU>>`: Uppercase Title of the Item's Show<br>`<<show_titleL>>`Lowercase Title of the Item's Show<br>`<<show_titleP>>`Proper Title of the Item's Show | ❌ | ❌ | ✅ | ✅ |
|
||||||
|
| `<<season_title>>`: Title of the Item's Season<br>`<<season_titleU>>`: Uppercase Title of the Item's Season<br>`<<season_titleL>>`Lowercase title of the Item's Season<br>`<<season_titleP>>`Proper title of the Item's Season | ❌ | ❌ | ❌ | ✅ |
|
||||||
|
| `<<original_title>>`: Original Title of the Item<br>`<<original_titleU>>`: Original Title of the Item<br>`<<original_titleL>>`Lowercase Original Title of the Item<br>`<<original_titleP>>`Proper Original Title of the Item | ✅ | ✅ | ❌ | ❌ |
|
||||||
|
| `<<edition>>`: Edition of the Item<br>`<<editionU>>`: Uppercase Edition of the Item<br>`<<editionL>>`Lowercase Edition of the Item<br>`<<editionP>>`Proper Edition of the Item | ✅ | ❌ | ❌ | ❌ |
|
||||||
|
| `<<content_rating>>`: Content Rating of the Item<br>`<<content_ratingU>>`: Uppercase Content Rating of the Item<br>`<<content_ratingL>>`Lowercase Content Rating of the Item<br>`<<content_ratingP>>`Proper Content Rating of the Item | ✅ | ✅ | ❌ | ✅ |
|
||||||
|
| `<<episode_count>>`: Number of Episodes (`1`)<br>`<<episode_countW>>`: Number of Episodes As Words (`One`)<br>`<<episode_countWU>>`: Number of Episodes As Uppercase Words (`ONE`)<br>`<<episode_countWL>>`: Number of Episodes As Lowercase Words (`one`)<br>`<<episode_count0>>`: Number of Episodes With 10s Padding (`01`)<br>`<<episode_count00>>`: Number of Episodes With 100s Padding (`001`) | ❌ | ✅ | ✅ | ❌ |
|
||||||
|
| `<<season_number>>`: Season Number (`1`)<br>`<<season_numberW>>`: Season Number As Words (`One`)<br>`<<season_numberWU>>`: Season Number As Uppercase Words (`ONE`)<br>`<<season_numberWL>>`: Season Number As Lowercase Words (`one`)<br>`<<season_number0>>`: Season Number With 10s Padding (`01`)<br>`<<season_number00>>`: Season Number With 100s Padding (`001`) | ❌ | ❌ | ✅ | ✅ |
|
||||||
|
| `<<episode_number>>`: Episode Number (`1`)<br>`<<episode_numberW>>`: Episode Number As Words (`One`)<br>`<<episode_numberWU>>`: Episode Number As Uppercase Words (`One`)<br>`<<episode_numberWL>>`: Episode Number As Lowercase Words (`one`)<br>`<<episode_number0>>`: Episode Number With 10s Padding (`01`)<br>`<<episode_number00>>`: Episode Number With 100s Padding (`001`) | ❌ | ❌ | ❌ | ✅ |
|
||||||
|
| `<<versions>>`: Number of Versions of the Item (`1`)<br>`<<versionsW>>`: Number of Versions of the Item As Words (`One`)<br>`<<versionsWO>>`: Number of Versions of the Item As Uppercase Words (`ONE`)<br>`<<versionsWL>>`: Number of Versions of the Item As Words (`one`)<br>`<<versions0>>`: Number of Versions of the Item With 10s Padding (`01`)<br>`<<versions00>>`: Number of Versions of the Item With 100s Padding (`001`) | ✅ | ❌ | ❌ | ✅ |
|
||||||
|
| `<<runtime>>`: Complete Runtime of the Item in minutes (`150`)<br>`<<runtimeH>>`: Hours in runtime of the Item (`2`)<br>`<<runtimeM>>`: Minutes remaining in the hour in the runtime of the Item (`30`)<br>**Show and Season use average Episode Runtime.** | ✅ | ✅ | ✅ | ✅ |
|
||||||
|
| `<<bitrate>>`: Bitrate of the first media file for an item.<br>`<<bitrateH>>`: Bitrate of the media file with the highest bitrate<br>`<<bitrateL>>`: Bitrate of the media file with the lowest bitrate | ✅ | ❌ | ❌ | ✅ |
|
||||||
|
| `<<originally_available>>`: Original Available Date of the Item<br>`<<originally_available[FORMAT]>>`: Original Available Date of the Item in the given format. [Format Options](https://strftime.org/) | ✅ | ✅ | ❌ | ✅ |
|
||||||
|
|
||||||
|
???+ tip
|
||||||
|
|
||||||
|
You can use the `mass_audience_rating_update` or `mass_critic_rating_update` [Library Operation](../operations.md) to update your plex ratings to various services like `tmdb`, `imdb`, `mdb`, `metacritic`, `letterboxd` and many more.
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
overlays:
|
||||||
|
backdrop:
|
||||||
|
overlay:
|
||||||
|
name: backdrop
|
||||||
|
back_color: "#00000099"
|
||||||
|
back_height: 100
|
||||||
|
vertical_position: top
|
||||||
|
plex_all: true
|
||||||
|
mytext:
|
||||||
|
overlay:
|
||||||
|
name: text(Critic Rating is <<critic_rating>>)
|
||||||
|
horizontal_offset: 0
|
||||||
|
horizontal_align: center
|
||||||
|
vertical_offset: 20
|
||||||
|
vertical_align: top
|
||||||
|
font_size: 63
|
||||||
|
font_color: "#FFFFFF"
|
||||||
|
plex_all: true
|
||||||
|
```
|
||||||
|
|
||||||
|
Note that we have once again built up on our backdrop overlay that we created in one of our previous examples
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
#### Special Text Modifiers
|
||||||
|
|
||||||
|
Some Special Text attributes (such as ratings) have modifiers which control how they are output. This is detailed in the above table.
|
||||||
|
|
||||||
|
Using the above example for the Critic Rating overlay, I now want to display the rating as "out of 5 stars" instead of "out of 10", so I will use the `/` modifier on my `<<critic_rating>>` attribute
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
overlays:
|
||||||
|
backdrop:
|
||||||
|
overlay:
|
||||||
|
name: backdrop
|
||||||
|
back_color: "#00000099"
|
||||||
|
back_height: 100
|
||||||
|
vertical_position: top
|
||||||
|
plex_all: true
|
||||||
|
mytext:
|
||||||
|
overlay:
|
||||||
|
name: text(Rated <<critic_rating/>> out of 5!)
|
||||||
|
horizontal_offset: 0
|
||||||
|
horizontal_align: center
|
||||||
|
vertical_offset: 20
|
||||||
|
vertical_align: top
|
||||||
|
font_size: 63
|
||||||
|
font_color: "#FFFFFF"
|
||||||
|
plex_all: true
|
||||||
|
```
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
I want to add `S##E##` to all my episode images.
|
||||||
|
```yaml
|
||||||
|
overlays:
|
||||||
|
backdrop:
|
||||||
|
builder_level: episode
|
||||||
|
overlay:
|
||||||
|
name: backdrop
|
||||||
|
back_color: "#00000099"
|
||||||
|
back_height: 100
|
||||||
|
vertical_position: top
|
||||||
|
plex_all: true
|
||||||
|
season_episode_info:
|
||||||
|
builder_level: episode
|
||||||
|
overlay:
|
||||||
|
name: text(This is S<<season_number0>>E<<episode_number0>>)
|
||||||
|
horizontal_offset: 0
|
||||||
|
horizontal_align: center
|
||||||
|
vertical_offset: 20
|
||||||
|
vertical_align: top
|
||||||
|
font_size: 63
|
||||||
|
font_color: "#FFFFFF"
|
||||||
|
plex_all: true
|
||||||
|
```
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
##### Common Special Text Uses
|
||||||
|
|
||||||
|
These are some commonly-used examples of Special Text overlays:
|
||||||
|
|
||||||
|
| Special Text | Example Output |
|
||||||
|
|:------------------------------------------------------------------|--------------------|
|
||||||
|
| `name: text(S<<season_number0>>E<<episode_number0>>)` | S01E01 |
|
||||||
|
| `name: text(Season <<season_number>> Episode <<episode_number>>)` | Season 1 Episode 1 |
|
||||||
|
| `name: text(Season <<season_number>>)` | Season 1 |
|
||||||
|
| `name: text(Episode <<episode_number>>)` | Episode 1 |
|
||||||
|
| `name: "text(Runtime: <<runtime>>m)"` | Runtime: 90m |
|
||||||
|
| `name: "text(Runtime: <<runtimeH>>h <<runtimeM>>m)"` | Runtime: 1h 30m |
|
||||||
|
|
||||||
|
#### Text Addon Images
|
||||||
|
|
||||||
|
You can add an image to accompany the text by specifying the image location using `file`, `url`, `git`, or `repo`.
|
||||||
|
|
||||||
|
Use `addon_offset` to control the space between the text and the image.
|
||||||
|
|
||||||
|
Use `addon_position` to control which side of the text the image will be located on.
|
||||||
|
|
||||||
|
???+ tip
|
||||||
|
|
||||||
|
This overlay example uses one of the [PMM Default Overlay](../../defaults/overlays.md) images, which isn't necessary but is used just for this example.
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
overlays:
|
||||||
|
rating_with_logo:
|
||||||
|
overlay:
|
||||||
|
name: text(audience_rating)
|
||||||
|
pmm: rating/IMDb.png
|
||||||
|
horizontal_offset: 15
|
||||||
|
horizontal_align: left
|
||||||
|
vertical_offset: 15
|
||||||
|
vertical_align: top
|
||||||
|
font: fonts/Inter-Medium.ttf
|
||||||
|
font_size: 63
|
||||||
|
font_color: "#FFFFFF"
|
||||||
|
back_color: "#00000099"
|
||||||
|
back_radius: 30
|
||||||
|
back_width: 300
|
||||||
|
back_height: 105
|
||||||
|
addon_position: left
|
||||||
|
addon_offset: 25
|
||||||
|
plex_all: true
|
||||||
|
```
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
### Overlay Groups
|
||||||
|
|
||||||
|
Overlay groups are defined by the name given to the `group` attribute. Only one overlay with the highest weight per group will be applied.
|
||||||
|
|
||||||
|
This is an example where the Multi-Audio overlay will be applied over the Dual-Audio overlay for every item found by both.
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
overlays:
|
||||||
|
Dual-Audio:
|
||||||
|
overlay:
|
||||||
|
name: Dual-Audio
|
||||||
|
pmm: images/Dual-Audio
|
||||||
|
group: audio_language
|
||||||
|
weight: 10
|
||||||
|
horizontal_offset: 0
|
||||||
|
horizontal_align: center
|
||||||
|
vertical_offset: 15
|
||||||
|
vertical_align: bottom
|
||||||
|
plex_all: true
|
||||||
|
filters:
|
||||||
|
audio_language.count_gt: 1
|
||||||
|
Multi-Audio:
|
||||||
|
overlay:
|
||||||
|
name: Multi-Audio
|
||||||
|
pmm: images/Multi-Audio
|
||||||
|
group: audio_language
|
||||||
|
weight: 20
|
||||||
|
horizontal_offset: 0
|
||||||
|
horizontal_align: center
|
||||||
|
vertical_offset: 15
|
||||||
|
vertical_align: bottom
|
||||||
|
plex_all: true
|
||||||
|
filters:
|
||||||
|
audio_language.count_gt: 2
|
||||||
|
```
|
||||||
|
|
||||||
|
### Overlay Queues
|
||||||
|
|
||||||
|
Overlay queues are defined by the name given to the `queue` attribute. The overlay with the highest weight is put into the first queue position, then the second highest is placed in the second queue position and so on.
|
||||||
|
|
||||||
|
You can define the queue positions by using the `queues` attribute at the top level of an Overlay File. You can define as many positions as you want.
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
queues:
|
||||||
|
custom_queue_name:
|
||||||
|
- horizontal_offset: 300 # This is the first position
|
||||||
|
horizontal_align: center
|
||||||
|
vertical_offset: 1375
|
||||||
|
vertical_align: top
|
||||||
|
- horizontal_offset: 300 # This is the second position
|
||||||
|
horizontal_align: center
|
||||||
|
vertical_offset: 1250
|
||||||
|
vertical_align: top
|
||||||
|
|
||||||
|
overlays:
|
||||||
|
IMDb:
|
||||||
|
imdb_chart: popular_movies
|
||||||
|
overlay:
|
||||||
|
name: text(IMDb Popular)
|
||||||
|
queue: custom_queue_name
|
||||||
|
weight: 20
|
||||||
|
font: fonts/Inter-Medium.ttf
|
||||||
|
font_size: 65
|
||||||
|
font_color: "#FFFFFF"
|
||||||
|
back_color: "#00000099"
|
||||||
|
back_radius: 30
|
||||||
|
back_width: 380
|
||||||
|
back_height: 105
|
||||||
|
TMDb:
|
||||||
|
tmdb_popular: 100
|
||||||
|
overlay:
|
||||||
|
name: text(TMDb Popular)
|
||||||
|
queue: custom_queue_name
|
||||||
|
weight: 10
|
||||||
|
font: fonts/Inter-Medium.ttf
|
||||||
|
font_size: 65
|
||||||
|
font_color: "#FFFFFF"
|
||||||
|
back_color: "#00000099"
|
||||||
|
back_radius: 30
|
||||||
|
back_width: 400
|
||||||
|
back_height: 105
|
||||||
|
```
|
||||||
|
|
||||||
|
## Suppress Overlays
|
||||||
|
|
||||||
|
You can add `suppress_overlays` to an overlay definition and give it a list or comma separated string of overlay names you want suppressed from this item if this overlay is attached to the item.
|
||||||
|
|
||||||
|
So in this example if the `4K-HDR` overlay matches an item then the `4K` and `HDR` overlays will also match. The `suppress_overlays` attribute on `4K-HDR` will stop the overlays specified (`4K` and `HDR`) from also being applied.
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
overlays:
|
||||||
|
4K:
|
||||||
|
plex_search:
|
||||||
|
all:
|
||||||
|
resolution: 4K
|
||||||
|
HDR:
|
||||||
|
plex_search:
|
||||||
|
all:
|
||||||
|
hdr: true
|
||||||
|
4K-HDR:
|
||||||
|
suppress_overlays:
|
||||||
|
- 4K
|
||||||
|
- HDR
|
||||||
|
plex_search:
|
||||||
|
all:
|
||||||
|
resolution: 4K
|
||||||
|
hdr: true
|
||||||
|
```
|
||||||
|
|
||||||
|
## Examples
|
||||||
|
|
||||||
|
### Example Overlay File
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
overlays:
|
||||||
|
4K:
|
||||||
|
overlay:
|
||||||
|
name: 4K # This will look for a local overlays/4K.png in your config folder
|
||||||
|
plex_search:
|
||||||
|
all:
|
||||||
|
resolution: 4K
|
||||||
|
HDR:
|
||||||
|
overlay:
|
||||||
|
name: HDR
|
||||||
|
pmm: HDR
|
||||||
|
plex_search:
|
||||||
|
all:
|
||||||
|
hdr: true
|
||||||
|
Dolby:
|
||||||
|
overlay:
|
||||||
|
name: Dolby
|
||||||
|
url: https://somewebsite.com/dolby_overlay.png
|
||||||
|
plex_all: true
|
||||||
|
filters:
|
||||||
|
has_dolby_vision: true
|
||||||
|
```
|
||||||
|
|
||||||
|
### Example Folder Structure
|
||||||
|
|
||||||
|
```
|
||||||
|
config
|
||||||
|
├── config.yml
|
||||||
|
├── Movies.yml
|
||||||
|
├── TV Shows.yml
|
||||||
|
├── Overlays.yml
|
||||||
|
├── overlays
|
||||||
|
│ ├── 4K.png
|
||||||
|
│ ├── Dolby.png
|
||||||
|
│ ├── HDR.png
|
||||||
|
```
|
||||||
@ -0,0 +1,139 @@
|
|||||||
|
# Playlist Files
|
||||||
|
|
||||||
|
Playlist files are used to create and maintain playlists on the Plex Server.
|
||||||
|
|
||||||
|
If utilized to their fullest, these files can be used to maintain the entire server's collections and playlists, and can be used as a backup for these in the event of a restore requirement.
|
||||||
|
|
||||||
|
???+ tip
|
||||||
|
|
||||||
|
Playlists are defined in one or more Playlist files that are mapped in the [Playlist Files Attribute](../playlists.md) within the Configuration File.
|
||||||
|
|
||||||
|
You can use the [`playlist_report` setting](../settings.md#playlist-report) to get a list of your playlists printed out in your log.
|
||||||
|
|
||||||
|
## Example
|
||||||
|
|
||||||
|
This example is a Playlist file with a basic overlay which is saved in a file called `MyPlaylists.yml` within the location mapped as `config` in my setup.
|
||||||
|
|
||||||
|
|
||||||
|
???+ example "Example "MyPlaylists.yml""
|
||||||
|
|
||||||
|
Click the :fontawesome-solid-circle-plus: icon to learn more
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
collections: #(1)!
|
||||||
|
Top 50 Grossing Films of All Time (Worldwide):
|
||||||
|
tmdb_list: 10 #(2)!
|
||||||
|
collection_order: custom #(3)!
|
||||||
|
sync_mode: sync #(4)!
|
||||||
|
```
|
||||||
|
|
||||||
|
1. This must appear once and **only once** in any Metadata file
|
||||||
|
2. This creates a collection based on tmdb list ID 10, https://www.themoviedb.org/list/10 would also be accepted
|
||||||
|
3. This will sort the items in the Plex collection to be the same as the order in the list
|
||||||
|
4. Syncs the collection to the list, so that if an item is added/removed from the list, the same is done to the collection. Set this to `append` if you only want it to add things and not remove them.
|
||||||
|
|
||||||
|
???+ example "config.yml Example Collection File Addition"
|
||||||
|
|
||||||
|
Click the :fontawesome-solid-circle-plus: icon to learn more
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
playlists: #(1)!
|
||||||
|
Marvel Cinematic Universe Chronological Order:
|
||||||
|
sync_mode: sync
|
||||||
|
libraries: Movies, TV Shows #(2)!
|
||||||
|
sync_to_users: User1, someone@somewhere.com, User3 #(3)!
|
||||||
|
trakt_list: https://trakt.tv/users/donxy/lists/marvel-cinematic-universe
|
||||||
|
summary: Marvel Cinematic Universe In Chronological Order
|
||||||
|
```
|
||||||
|
|
||||||
|
1. This must appear once and **only once** in any Playlist file
|
||||||
|
2. These libraries must exist in your Plex library
|
||||||
|
3. Leave this blank if you only only want the Playlist to sync to the server owner's account
|
||||||
|
|
||||||
|
This file would then be defined in my `config.yml` file as a `playlist_files` item:
|
||||||
|
|
||||||
|
???+ warning "Important Note"
|
||||||
|
|
||||||
|
Playlist files are not called within the `libraries` section, they are defined at the root identation as you can see in the below example.
|
||||||
|
|
||||||
|
???+ example "config.yml Example Playlists Addition"
|
||||||
|
|
||||||
|
Click the :fontawesome-solid-circle-plus: icon to learn more
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
libraries:
|
||||||
|
Movies:
|
||||||
|
# Metadata and Overlay files here
|
||||||
|
TV Shows:
|
||||||
|
# Metadata and Overlay files here
|
||||||
|
playlist_files: #(1)!
|
||||||
|
- file: config/MyPlaylists.yml #(2)!
|
||||||
|
```
|
||||||
|
|
||||||
|
1. Note that Playlist files are not called within the `libraries` section, they are defined at the root identation as you can see here
|
||||||
|
2. `config` refers to the location that you mapped to `config` when following the PMM Installation Guides.
|
||||||
|
|
||||||
|
## Playlist Attributes
|
||||||
|
|
||||||
|
Plex Meta Manager can automatically build and update playlists defined within the `playlists` attribute.
|
||||||
|
|
||||||
|
These are the attributes which can be utilized within the Playlist File:
|
||||||
|
|
||||||
|
| Attribute | Description |
|
||||||
|
|:--------------------------------------------------------|:--------------------------------------------------------------------------------------------------------------------|
|
||||||
|
| [`templates`](../../builders/templates.md) | contains definitions of templates that can be leveraged by multiple playlists |
|
||||||
|
| [`external_templates`](../../builders/templates.md#external-templates) | contains [path types](../paths.md) that point to external templates that can be leveraged by multiple playlists |
|
||||||
|
| [`playlists`](#playlist-attributes) | contains definitions of playlists you wish to add to the server |
|
||||||
|
|
||||||
|
* `playlists` is required in order to run the Playlist File.
|
||||||
|
* You can find example Playlist Files in the [Plex Meta Manager Configs Repository](https://github.com/meisnate12/Plex-Meta-Manager-Configs/tree/master/PMM)
|
||||||
|
* Plex does not support the "Continue Watching" feature for playlists, you can [vote for the feature here](https://forums.plex.tv/t/playlists-remember-position-for-subsequent-resume/84866/39)
|
||||||
|
|
||||||
|
|
||||||
|
Each playlist requires its own section within the `playlists` attribute and unlike collections, playlists can only be built using one Builder as their ordering is inherited from the builder; it is not possible to combine builders.
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
playlists:
|
||||||
|
Marvel Cinematic Universe Chronological Order:
|
||||||
|
# ... builder, details, and filters for this playlist
|
||||||
|
Star Wars Clone Wars Chronological Order:
|
||||||
|
# ... builder, details, and filters for this playlist
|
||||||
|
etc:
|
||||||
|
# ... builder, details, and filters for this playlist
|
||||||
|
```
|
||||||
|
|
||||||
|
There are multiple types of attributes that can be utilized within a playlist:
|
||||||
|
|
||||||
|
* [Builders](../../builders/overview.md)
|
||||||
|
* [Settings/Updates](../../metadata/update.md)[update.md]
|
||||||
|
* [Filters](../../builders/filters.md)
|
||||||
|
|
||||||
|
### Special Playlist Attributes
|
||||||
|
|
||||||
|
| Attribute | Description | Required |
|
||||||
|
|:------------------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:--------:|
|
||||||
|
| `libraries` | Determine which libraries the playlist will be built from.<br>**Options:** Comma-separated string or list of library mapping names defined in the `libraries` attribute in the base of your [Configuration File](../configuration.md. | ✅ |
|
||||||
|
| `sync_to_users` | Determine which Users have the playlist synced.<br>This will override the global [`playlist_sync_to_users` Setting](../settings.md#playlist-sync-to-users).<br>**Options:** Comma-separated string or list of users, `all` for every user who has server access, or leave blank for just the server owner. | ❌ |
|
||||||
|
| `exclude_users` | Determine which Users will be excluded from having the playlist synced.<br>This will override the global [`playlist_excude_users` Setting](../settings.md#playlist-exclude-users).<br>**Options:** Comma-separated string or list of users, `all` for every user who has server access, or leave blank for just the server owner. | ❌ |
|
||||||
|
| `delete_playlist` | Will delete this playlist for the users defined by sync_to_users.<br>**Options:** `true` or `false` | ❌ |
|
||||||
|
|
||||||
|
* Any defined playlist will be always be visible by The Plex Media Server owner, so it doesn't need to be defined within `sync_to_users`.
|
||||||
|
|
||||||
|
## Example Playlists
|
||||||
|
|
||||||
|
In the following example, media is pulled from the `Movies` and `TV Shows` libraries into the one Playlist, and the playlist is shared with a specific set of users:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
playlists:
|
||||||
|
Marvel Cinematic Universe Chronological Order:
|
||||||
|
sync_mode: sync
|
||||||
|
libraries: Movies, TV Shows
|
||||||
|
sync_to_users: User1, someone@somewhere.com, User3
|
||||||
|
trakt_list: https://trakt.tv/users/donxy/lists/marvel-cinematic-universe?sort=rank,asc
|
||||||
|
summary: Marvel Cinematic Universe In Chronological Order
|
||||||
|
Star Wars Clone Wars Chronological Order:
|
||||||
|
sync_to_users: all
|
||||||
|
sync_mode: sync
|
||||||
|
libraries: Movies, TV Shows
|
||||||
|
trakt_list: https://trakt.tv/users/tomfin46/lists/star-wars-the-clone-wars-chronological-episode-order
|
||||||
|
```
|
||||||
@ -0,0 +1,39 @@
|
|||||||
|
# Files
|
||||||
|
|
||||||
|
Files define the structure and format for creating Collections, Overlays, Playlists, and Metadata Edits within your libraries.
|
||||||
|
|
||||||
|
Files are modular and when properly leveraged, they not only facilitate the management of your library's collections and metadata but also serve as a crucial backup resource in case a restore is necessary.
|
||||||
|
|
||||||
|
There are four main File types that can be utilized against Plex servers:
|
||||||
|
|
||||||
|
| File Type | Description |
|
||||||
|
|:-----------------------------------------------------------------------------------------------------------------|:-----------------------------------------------------------------------------------------------------------------------------------------|
|
||||||
|
| [Collection Files](data/collections.md) | Defines the data for building collections, allowing you to group and showcase your library in unique ways |
|
||||||
|
| [Overlay Files](data/overlays.md) | Defines the data for building overlays, allowing you to place information such as resolutions and ratings onto your posters. |
|
||||||
|
| Metadata Files ([Movies](data/metadata/movie.md)/[Shows](data/metadata/show.md)/[Music](data/metadata/music.md)) | Defines the data for editing metadata, allowing you to find and manipulate the metadata on individual items within your library. |
|
||||||
|
| [Playlist Files](data/playlists.md) | Defines the data for building playlists, allowing you to combine media from multiple libraries and share them with users on your server |
|
||||||
|
|
||||||
|
Collection, Overlay and Metadata Files can be linked to libraries in the [Libraries Attribute](../config/libraries.md#metadata-path) within the [Configuration File](../config/configuration.md).
|
||||||
|
|
||||||
|
## Example
|
||||||
|
|
||||||
|
This is a basic Files structure showing the use of all four File types.
|
||||||
|
|
||||||
|
???+ example "Example Files"
|
||||||
|
|
||||||
|
Unlike the other three, Playlist Files are not defined per-library.
|
||||||
|
|
||||||
|
Theis examples utilizes the [PMM Defaults](../defaults/files.md)
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
libraries:
|
||||||
|
Movies:
|
||||||
|
collection_files:
|
||||||
|
- pmm: imdb
|
||||||
|
overlay_files:
|
||||||
|
- pmm: resolution
|
||||||
|
metadata_files:
|
||||||
|
- file: config/metadata.yml
|
||||||
|
playlist_files:
|
||||||
|
- pmm: playlists
|
||||||
|
```
|
||||||
Some files were not shown because too many files have changed in this diff Show More
Loading…
Reference in new issue