Background

This is an optional YAML section of your global preferences file (preferences.yml) for outlining how the Maker should interact with a Jellyfin server. 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 Jellyfin.

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

Complete Example

# preferences.yml
jellyfin:
  url: http://192.168.0.1:8096/
  api_key: e25b06a1aee34fc0949c35d74f379d03
  username: CollinHeist
  verify_ssl: true
  watched_style: unique
  unwatched_style: blur
  filesize_limit: 4 MB
  sync:
  - file: ./yaml/jellyfin_sync.yml
    mode: append
    compact_mode: true
    add_template: my_template
    libraries:
    - TV Shows
    - Anime
    exclusions:
    - series: Pokémon (1997)
    - yaml: ./yaml/ignore.yml

options:     # Global options ...
archive:     # Archive options ...
plex:        # Plex 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
Emby URL	`url`	A valid Jellyfin URL	-	✅
Emby API Key	`api_key`	A valid Jellyfin API Key	-	✅
Emby Username	`username`	Username	-	✅
Verify SSL	`verify_ssl`	Boolean (`true` or `false`)	`true`	❌
Watched Style	`watched_style`	A valid style	`unique`	❌
Unwatched Style	`unwatched_style`	A valid style	`unique`	❌
Filesize Limit	`filesize_limit`	Any valid file size	-	❌
YAML Syncing	`sync`	A sync configuration	-	❌

Jellyfin URL

URL of Jellyfin to send API requests to, should include the port number (likely 8096).

Jellyfin API Key

Jellyfinrequires an API key in order to validate requests from external services. This is required for TCM to function.

Finding the API Key

Navigate to the Jellyfin web interface, and click the Gear icon in the top right corner
In the left sidebar, scroll to the bottom and select Api Keys
Create a new API key
Give a descriptive name (like TitleCardMaker) and then hit Ok
Copy the created API key into your preferences file

Emby Username

A valid username is required for TCM to query Jellyfin for a user's watch history, even if a non-default style is not being used. This username is only used to query an episode's watch status - loaded assets apply for all users (i.e. title cards are visible to all users).

Verify SSL

By default, TCM will attempt to verify the security of the API requests made to Jellyfin. However, for some users running TCM or Jellyfinon machines without valid SSL certificates, this can result in 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 Jellyfininternally (local to your network), the real risk is quite low.

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 Jellyfin 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 art¹ 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

¹ TCM will attempt to download backdrop art 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 grayscale 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 Jellyfin, 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.

Filesize Limit

NOTE: Unlike Plex, Jellyfin does not enforce any hard limit on the file size of a single asset, and so this setting is disabled by default.

Limit on the file size of assets uploaded to Jellyfin. This applies to both title cards and season posters - and will reduce the size of your Jellyfinmetadata. 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.

When specified, the card will be created and stored in the original quality - even if it exceeds this file size limit. However, when the file is being uploaded to Jellyfin, 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 Jellyfin automatically, without the need to add all series manually. This behavior is disabled by default.

This functionality is detailed here.

Jellyfin - CollinHeist/TitleCardMaker GitHub Wiki

Background

Complete Example

Attributes

Jellyfin URL