Skip to content

Options Attributes

Jump to bottom
Collin Heist edited this page Aug 5, 2022 · 53 revisions

Background

This is the only required YAML section for setting up the TitleCardMaker, and lists the primary source directory to use, any number of series YAML files to create cards for, as well as some optional global values that apply to all created cards.

Complete Example

options:
  source: /source/
  series:
  - /series/tv_4k.yml
  - /series/tv.yml
  - /series/anime.yml
  card_type: standard
  card_extension: jpg
  episode_data_source: sonarr
  image_source_priority: tmdb, plex
  filename_format: "{full_name} - S{season:02}E{episode:02} - {title}"
  card_extension: jpg
  validate_fonts: true
  season_folder_format: "Season {season:02}"
  sync_specials: False

Attributes

Name YAML Attribute Allowed Values Default Value Required
Source Directory source Any valid directory - ✔️
Series YAML Files series Any YAML file, or a list of YAML file(s) - ✔️
Card Type card_type Any known TitleCard identifier - see here standard ❌
Episode Data Source episode_data_source Either sonarr, plex, or tmdb sonarr ❌
Image Source Priority image_source_priority Any order/combination of tmdb and plex tmdb, plex ❌
Card Filename Format filename_format A valid Python formatting string {full_name} - S{season:02}E{episode:02} ❌
Card Extension card_extension One of jpg, jpeg, png, tiff, or gif jpg ❌
Font Validation validate_fonts Boolean (true or false) true ❌
Season Folder Format season_folder_format A valid format string Season {season} ❌
Sync Specials sync_specials Boolean (true or false) true ❌

Source Directory

The default location for all source data and images will be searched for and stored by the Maker.

Example

The following example specifies the top-level source folder of /user/source/. For the series Mr. Robot (2015), that means the source images and files will be created at /user/source/Mr. Robot (2015)/.

options:
  source: /user/source/

Series YAML Files

Separate YAML files that specify for which series to create title cards for, as well as outline specifically how those cards are to be created. This can be a single file, or a list of files which will be parsed in the listed order.

The exact structure and contents of this file is outlined here.

Example

The following example lists a single YAML file located at /yaml/all_tv.yml for which cards will be created for:

options:
  series: /yaml/all_tv.yml

While this example defines two files, /yaml/tv.yml and /yaml/anime.yml to create cards for.

options:
  series:
  - /yaml/tv.yml
  - /yaml/anime.yml
  - ...

Card Type

The default card type/style to use for title card creation. The default value of standard uses the StandardTitleCard class, defined here.

This can be overwritten on a per-series or library basis; see here.

Any valid card type is allowed, but user-created types are not. Those can only be set for a library/series.

Example

The following example sets the global default card type to the RomanNumeralTitleCard:

options:
  card_type: roman

Episode Data Source

The default source to pull episode data from. In this context, episode data refers to episode titles/numbers for a given series. The default value is sonarr.

If sonarr is specified, Sonarr must be globally enabled, and the series must be present in Sonarr (not necessarily downloaded, just added to Sonarr). If plex is specified, Plex must be globally enabled, and only episodes that exist in the given series' library will be downloaded. If tmdb is specified, TMDb must be globally enabled.

This can be overwritten on a per-series basis, see here.

Example

The following example sets the global default episode data source to plex, effectively only creating cards for episodes that you "own".

options:
  episode_data_source: plex

Image Source Priority

The Maker will attempt to automatically gather source images (the images used in the title cards) from a variety of sources. This option can be used to specify which sources to look for images from, as well as their relative priority.

Currently there are only two "interfaces" for source images, tmdb, and plex - these can be combined in the following configurations:

image_source_priority Description
plex Only get sources images from Plex
tmdb Only get source images from TMDb
plex, tmdb Get source images from Plex first, then TMDb
tmdb, plex Get source images from TMDb first, then Plex1

1 Plex will only be queried for source images after that episode has been "permanently blacklisted" - i.e. has failed more than the specified retry count.

For obvious reasons, tmdb is only a valid image source if TMDb is globally enabled, and plex is only valid if Plex is globally enabled.

If plex is specified as an image source, the currently selected episode thumbnail will be pulled.

Example

The following example will source images from Plex, and for any episodes either not present in Plex, or that doesn't have a thumbnail, TMDb will be queried instead.

options:
  image_source_priority: plex, tmdb

Card Filename Format

The format for how to name the files of title cards. The default value of {full_name} - S{season:02}E{episode:02} results in cards titled as ShowName (Year) - SxxEyy, which is the recommended Plex naming convention for media. If you'd like to modify the names of these cards to match your specific media naming conventions, then the following format options are available:

The example values will be using Mr. Robot Season 4 Episode 1 (absolute episode 33), titled "401 Unauthorized"

Option Description Example Value Notes
{name} The series name Mr. Robot -
{full_name} The series name and year (in parenthesis) Mr. Robot (2015) -
{year} The series year 2015 Can be zero-padded (but why?)
{season} The episode's season number 4 Can be zero-padded like so {season:02}
{episode} The episode's episode number 1 Can be zero-padded like so {episode:02}
{title} The episode's title1 401 Unauthorized -
{abs_number} The episode's absolute episode number2 33 Can be zero-padded like so {abs_number:02}

1The episode title is modified so that any bad characters (like :, /, \, etc.) are removed/replaced.

2If an episode does not have an absolute ordering, then 0 is used instead.

Example

The following example will name cards in the "recommended" way, but include their episode title:

options:
  filename_format: "{full_name} - S{season:02}E{episode:02} - {title}"

For the above example, producing a file like Mr. Robot (2015) - S04E01 - 401 Unauthorized.jpg.

Card Extension

The image extension to use for all cards created by the TitleCardMaker. I have never tested anything except jpg, jpeg, and png, but theoretically Plex can take any image format when loading these.

There is no real reason, beyond minor performance differences and filesize, to select one extension over another.

Example

The following example sets the global image extension for all title cards to .png (which, due to it's uncompressed nature, will slow down card creation):

options:
  card_extension: png

Font Validation

Whether to globally validate all characters for a font (both custom and generic) before creating a title card. This is enabled by default, but can be overwritten for each series.

This is described in greater detail here.

Example

The following example globally disables font validation, but it can still be enabled for each series individually.

options:
  validate_fonts: false

Season Folder Format

Format to use for season folders - this does not apply to the Specials (0th) folders, which is always Specials (unless hidden). This option can be used to disable season folder altogether if a blank format (e.g. "") is given, or can be used to zero-pad the season numbers.

This option also allows for non-English season folder names like Temporada or Saison.

The below table shows how to use this option for some of the most common folder name conventions:

season_folder_format Season Number Folder Name
""1 0
""1 1
""1 10
Season {season} 0 Specials
Season {season} 1 Season 1
Season {season} 10 Season 10
Season {season:02} 0 Specials
Season {season:02} 1 Season 01
Season {season:02} 10 Season 10
Temporada {season:03} 0 Specials
Temporada {season:03} 1 Temporada 001
Temporada {season:03} 2 Temporada 010

1 If enabled then all cards will be created directly under their main media/archive folder. This can be useful for integrating the Maker with Emby/Jellyfin.

Example

The following example creates Spanish-titled folders with zero-padded digits, producing folders like Temporada 01, Temporada 02, etc.

options:
  season_folder_format: "Temporada {season:02}"

Special Syncing

Whether to sync specials (episodes from season 0) when getting new episodes from the specified episode data source. This is enabled by default (meaning specials will be skipped).

It is often difficult to find high quality images for special episodes, so these can be skipped altogether by enabling this setting. This can be overwritten for each series.

Clone this wiki locally