You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
237 lines
12 KiB
237 lines
12 KiB
# Overlay Files
|
|
|
|
Overlay files are used to create and maintain overlays within the Plex libraries on the server.
|
|
|
|
Overlays and templates are defined within one or more Overlay files, which are linked to libraries in the [Libraries Attribute](../config/libraries.md#overlay-path) within the [Configuration File](../config/configuration.md).
|
|
|
|
**To remove all overlays add `remove_overlays: true` to the `overlay_path` [Libraries Attribute](../config/libraries.md#remove-overlays).**
|
|
|
|
**To change a single overlay original image either replace the image in the assets folder or remove the `Overlay` shared label and then PMM will overlay the new image**
|
|
|
|
These are the attributes which can be used within the Overlay File:
|
|
|
|
| Attribute | Description |
|
|
|:--------------------------------------------------------|:-------------------------------------------------------------------------------------------------------------------|
|
|
| [`templates`](templates) | contains definitions of templates that can be leveraged by multiple overlays |
|
|
| [`external_templates`](templates.md#external-templates) | contains [path types](../config/paths) that point to external templates that can be leveraged by multiple overlays |
|
|
| [`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)
|
|
|
|
## Overlays Attributes
|
|
|
|
Each overlay definition requires its own section within the `overlays` attribute.
|
|
|
|
```yaml
|
|
overlays:
|
|
IMDb Top 250:
|
|
# ... builders, details, and filters for this overlay
|
|
4K:
|
|
# ... builders, details, and filters for this overlay
|
|
etc:
|
|
# ... builders, details, and filters for this overlay
|
|
```
|
|
|
|
## Overlay
|
|
|
|
Each overlay definition needs to specify what overlay to use. This can happen in 3 ways.
|
|
|
|
1. If there is no `overlay` attribute PMM will look in your `config/overlays` folder for a `.png` file named the same as the mapping name of the overlay definition. This example below would look for `IMDb Top 250.png`.
|
|
```yaml
|
|
overlays:
|
|
IMDb Top 250:
|
|
imdb_chart: top_movies
|
|
```
|
|
|
|
2. If the `overlay` attribute is given a string PMM will look in your `config/overlays` folder for a `.png` file named the same as the string given. This example below would look for `IMDbTop.png`.
|
|
```yaml
|
|
overlays:
|
|
overlay: IMDbTop
|
|
IMDb Top 250:
|
|
imdb_chart: top_movies
|
|
```
|
|
|
|
3. Using a dictionary for more overlay location options.
|
|
|
|
| Attribute | Description | Required |
|
|
|:--------------------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:--------:|
|
|
| `name` | Name of the overlay. Each overlay name should be unique. | ✅ |
|
|
| `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](../config/settings.md#custom-repo) of the Overlay Image. | ❌ |
|
|
| `group` | 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 | ❌ |
|
|
| `weight` | Weight of this overlay in its group.<br>**`group` is required when using `weight`**<br>**Values:** Integer | ❌ |
|
|
| `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 1%-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 1%-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_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`. | ❌ |
|
|
| `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_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 | ❌ |
|
|
|
|
* 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.
|
|
|
|
```yaml
|
|
overlays:
|
|
IMDb Top 250:
|
|
overlay:
|
|
name: IMDb Top 250
|
|
imdb_chart: top_movies
|
|
```
|
|
|
|
### 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)
|
|
plex_search:
|
|
all:
|
|
resolution: 4K
|
|
```
|
|
|
|
### 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.
|
|
|
|
The `horizontal_offset` and `vertical_offset` overlay attributes are required when using Text Overlays.
|
|
|
|
You can add an items rating number (`8.7`) to the image by using `text(audience_rating)`, `text(critic_rating)`, or `text(user_rating)`
|
|
|
|
You can add an items rating percentage (`87%`) to the image by using `text(audience_rating%)`, `text(critic_rating%)`, or `text(user_rating%)`
|
|
|
|
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:
|
|
audience_rating:
|
|
overlay:
|
|
name: text(audience_rating)
|
|
horizontal_offset: 15
|
|
vertical_offset: 15
|
|
font: fonts/Roboto-Medium.ttf
|
|
font_size: 200
|
|
plex_all: true
|
|
```
|
|
|
|
**Note: This only adds the text you may want to also add an overlay banner in the same spot.**
|
|
|
|
## 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
|
|
```
|
|
|
|
## Builders
|
|
|
|
Builders use third-party services to source items for overlays. Multiple builders can be used in the same overlay from a variety of sources listed below.
|
|
|
|
* [Plex Builders](builders/plex)
|
|
* [TMDb Builders](builders/tmdb)
|
|
* [TVDb Builders](builders/tvdb)
|
|
* [IMDb Builders](builders/imdb)
|
|
* [Trakt Builders](builders/trakt)
|
|
* [Tautulli Builders](builders/tautulli)
|
|
* [Radarr Builders](builders/radarr)
|
|
* [Sonarr Builders](builders/sonarr)
|
|
* [MdbList Builders](builders/mdblist)
|
|
* [Letterboxd Builders](builders/letterboxd)
|
|
* [ICheckMovies Builders](builders/icheckmovies)
|
|
* [FlixPatrol Builders](builders/flixpatrol)
|
|
* [Reciperr Builders](builders/reciperr)
|
|
* [StevenLu Builders](builders/stevenlu)
|
|
* [AniDB Builders](builders/anidb)
|
|
* [AniList Builders](builders/anilist)
|
|
* [MyAnimeList Builders](builders/myanimelist)
|
|
|
|
## Details
|
|
|
|
Only a few details can be used with overlays: `limit`, `show_missing`, `save_missing`, `missing_only_released`, `minimum_items`, `cache_builders`, `tmdb_region`
|
|
|
|
* [Setting Details](details/setting)
|
|
* [Metadata Details](details/metadata)
|
|
|
|
## Filters
|
|
|
|
These filter media items added to the collection by any of the Builders.
|
|
|
|
* [Filters](filters)
|
|
|
|
## Example
|
|
|
|
### 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
|
|
git: PMM/overlays/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
|
|
```
|