Mirrors/Plex-Meta-Manager
2
0
Fork 0
mirror of https://github.com/meisnate12/Plex-Meta-Manager synced 2024-11-23 04:53:07 +00:00
Code Issues Projects Releases Packages Wiki Activity
Plex-Meta-Manager/docs/metadata/overlay.md
meisnate12 1664a6002a [103] overlay text backdrop and more filters
2022-05-17 03:25:11 -04:00

12 KiB
Raw Blame History

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 within the Configuration File.

To remove all overlays add remove_overlays: true to the overlay_path Libraries Attribute.

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 contains definitions of templates that can be leveraged by multiple overlays
external_templates contains path types that point to external templates that can be leveraged by multiple overlays
overlays contains definitions of overlays you wish to add

Overlays Attributes

Each overlay definition requires its own section within the overlays attribute.

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.

    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.

    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 of the Overlay Image. ❌
repo Location in the 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.
weight is required when using group
Values: group name		 ❌
weight Weight of this overlay in its group.
group is required when using weight
Values: Integer		 ❌
horizontal_offset Horizontal Offset of this overlay. Can be a %.
vertical_offset is required when using horizontal_offset
Value: Integer 0 or greater or 1%-100%		 ❌
horizontal_align Horizontal Alignment of the overlay.
Values: left, center, right		 ❌
vertical_offset Vertical Offset of this overlay. Can be a %.
horizontal_offset is required when using vertical_offset
Value: Integer 0 or greater or 1%-100%		 ❌
vertical_align Vertical Alignment of the overlay.
Values: top, center, bottom		 ❌
font System Font Filename or path to font file for the Text Overlay.
Value: System Font Filename or path to font file		 ❌
font_size Font Size for the Text Overlay.
Value: Integer greater than 0		 ❌
font_color Font Color for the Text Overlay.
Value: Color Hex Code in format #RGB, #RGBA, #RRGGBB or #RRGGBBAA.		 ❌
back_color Backdrop Color for the Text Overlay.
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
back_height is required when using back_width
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
back_width is required when using back_height
Value: Integer greater than 0		 ❌
back_padding Backdrop Padding for the Text Overlay.
Value: Integer greater than 0		 ❌
back_radius Backdrop Radius for the Text Overlay.
Value: Integer greater than 0		 ❌
back_line_color Backdrop Line Color for the Text Overlay.
Value: Color Hex Code in format #RGB, #RGBA, #RRGGBB or #RRGGBBAA.		 ❌
back_line_width Backdrop Line Width for the Text Overlay.
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.
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(##).

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 which can be called using fonts/fontname.ttf

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.

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.

Details

Only a few details can be used with overlays: limit, show_missing, save_missing, missing_only_released, minimum_items, cache_builders, tmdb_region

Filters

These filter media items added to the collection by any of the Builders.

Example

Example Overlay File

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