Skip to content

Plex Attributes

Jump to bottom
Collin Heist edited this page May 15, 2024 · 55 revisions

Background

This is an optional YAML section of your global preferences file (preferences.yml) for outlining how the Maker should interact with an instance of Plex. Cards are created and can be placed alongside media files, but if properly setup, this allows the Maker to directly load the title cards within Plex.

Plex can also be used to determine an episode's watched status and modify a title card based on it.

Note

The watch status of an episode is determine by the server owner, and cannot be tied to a specific user. This means if you (as the server owner) haven't watched an episode, and have enabled a specific style of card based on this, then all users will see the unwatched style - even if they personally have marked the episode as seen. This is a limitation within Plex, not TCM.

Complete Example

Warning

The following YAML is only meant to showcase all available options. A vast majority of options are not required (or recommended).

# preferences.yml
plex:
  url: http://192.168.0.1:32400/
  token: pz_fZwxW-ygxaac-t_Pw
  verify_ssl: true
  watched_style: unique
  unwatched_style: blur
  integrate_with_kometa: true
  filesize_limit: 4 MB
  timeout: 30
  sync:
    file: ./yaml/plex_sync.yml
    mode: append
    compact_mode: true
    add_template: my_template
    libraries:
    - TV Shows
    - Anime
    volumes: 
      /plex/media/: /maker/media/
    exclusions:
    - series: Pokémon (1997)
    - yaml: ./yaml/ignore.yml

options:     # Global options ...
archive:     # Archive options ...
jellyfin:    # Jellyfin options ...
emby:        # Emby options ...
sonarr:      # Sonarr options ...
tautulli:    # Tautulli options ...
tmdb:        # TMDb options ...
imagemagick: # Imagemagick options ...

Attributes

Name YAML Attribute Allowed Values Default Value Required
Plex URL url A valid Plex URL - ✔️
Plex Token token An X-Plex-Token N/A ❌1
Verify SSL verify_ssl Boolean (true or false) true ❌
Timeout timeout Any number ≥1 30 ❌
Watched Style watched_style A valid style unique ❌
Unwatched Style unwatched_style A valid style unique ❌
Kometa Integration integrate_with_kometa Boolean (true or false) false ❌
Filesize Limit filesize_limit Any valid filesize2 10 MB ❌
YAML Syncing sync A sync configuration - ❌

1A Plex token is only not required if the device running the Maker is a trusted device.

2Any valid size is technically allowed, but Plex will reject images larger than 10 MB.

Plex URL

URL of Plex to send API requests to, should include the port number (32400).

Plex Token

Plex uses a "api key" of sorts for all API requests coming from untrusted devices. If the device running the Maker is trusted, this option is not required, as Plex will ignore the value in all requests.

Finding the X-Plex-Token

If the IP of the device running the Maker is untrusted and you do not already know your token, then follow the procedure listed here.

Adding the Maker as a Trusted Device

If you would like to authenticate the Maker's device so your internal requests do not need a token, then follow the procedure listed here.

Verify SSL

By default, TCM will attempt to verify the security of the API requests made to Plex. However, for some users running TCM or Plex on machines without valid SSL certificates, this can result in Plex communication failures. Disabling this setting can prevent those errors.

Disabling SSL verification does have marginal security risks, but given that TCM will likely be communicating with Plex internally (local to your network), the real risk is quite low.

Timeout

In the event of some network interruption, TCM will time out any Plex requests which take longer than a specific amount of time (in seconds).

The default value is 30.

Styles

Watched Style

Style of cards to create for all watched episodes. Defaults to unique.

Unwatched Style

Style of cards to create for all unwatched episodes. If an episode's watch status cannot be determined, then the episode is assumed to be unwatched, and this style is used. Defaults to unique.

Background

The Maker can use the watched status of an episode within Plex to determine whether to modify the source image of the card (by applying a "style" to it) or not. The default style of unique is to use a unique, unmodified, image for each episode. These settings can each be changed globally (here), or per-series.

The style can be any combination of the modifiers unique, art, blur, and grayscale - except unique and art cannot be combined. The order of the style does not matter (i.e. art blur is identical to blur art). A brief description of each possible modifier is listed below:

Style Description Example
art Use generic series backdrop art1 for all episodes
blur Apply a blurred effect to each image
grayscale Apply a grayscale (black & white) effect to each image
unique Use an unmodified unique image for each episode

1 Backdrop art will attempt to be downloaded from TMDb, but any file located at backdrop.jpg in the local source directory can be used.

These styles can be combined to compound their effects. For example, specifying a style of blur grayscale will apply a blurring and greyscale effect to the source image. A showcase of all valid styles is shown below:

All Valid Styles
Style Example
art
art blur
art grayscale
art blur grayscale
blur
blur grayscale
blur unique Same as blur
blur grayscale unique Same as blur grayscale
grayscale
grayscale unique Same as grayscale
unique

Changing the Watched Status

Every time the Maker is run, it checks the "spoil status" of the last-loaded card to see if it needs to be updated. This means that if a spoiler-free card was loaded and then the episode was watched within Plex, the next time the Maker runs it will delete and remake the title card in a spoiler variant (unless the two styles are the same).

The Maker will also check the type of spoiler-free card that's been loaded, so using blur and then switching to art will initiate a recreation of all the previously blurred cards.

Note

This process can be done immediately after an episode has been watched by integrating the Maker with Tautulli. This process is detailed here

Kometa Integration

If Kometa (formerly Plex Meta Manager / PMM) is being used to apply episode overlays, it's important that TCM and Kometa do not "compete" for who uploads a card. Enabling this setting ensures the Maker resets Kometa's tracker after a new title card has been uploaded, making Kometa re-apply the overlay on top of the title card, instead of in place of it.

Note

There's no downside to enabling this setting even if you aren't using Kometa overlays for every series, all the Maker does is remove Kometa's Overlay label from an episode after a card has been uploaded.

Filesize Limit

Limit on the filesize of assets uploaded to Plex. This applies to both title cards and season posters - and will presumably to reduce the size of your Plex metadata database. This should be specified as {digit} {unit} - e.g. 10 MB, 5000 KiB, etc. The acceptable units are: B, KB, KiB, MB, MiB, GB, GiB, TB, and TiB.

Plex enforces a hard limit of 10 MB on all files, and attempting to upload an image larger than this will result in a warning/error within TCM.

When specified, the card will be created and stored in the original quality - even if it exceeds this filesize limit. However, when the file is being uploaded to Plex, it will be incrementally compressed until below this limit. If a file cannot be compressed below the limit, it will be logged and skipped.

YAML Sync

TitleCardMaker can automatically create/update series YAML files so that cards can be created for series within Plex automatically, without the need to add all series manually. This behavior is disabled by default.

Note

Plex syncing is very slow - taking 10+ minutes (depending on your library size) - this is due to the speed of the Plex API, and is outside of TCM's control. Keep this in mind as it might appear as though the startup sequence is frozen/stalled.

This functionality is detailed here.

Clone this wiki locally