Skip to content

Options Attributes

Jump to bottom
Collin Heist edited this page Apr 10, 2023 · 53 revisions

Background

This is the only required YAML section of your global preferences file (preferences.yml) 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

# preferences.yml
options:
  source: /source/
  series:
  - /series/tv_4k.yml
  - /series/tv.yml
  - /series/anime.yml
  execution_mode: serial
  card_type: standard
  card_extension: jpg
  card_dimensions: 3200x1800
  episode_data_source: sonarr
  image_source_priority: tmdb, plex
  filename_format: "{full_name} - S{season:02}E{episode:02} - {title}"
  validate_fonts: true
  season_folder_format: "Season {season:02}"
  sync_specials: false
  language_codes:
  - es
  - fr

archive:     # Archive options ...
plex:        # Plex 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
Source Directory source Any valid directory - ✅
Series YAML Files series Any YAML file, or a list of YAML file(s) - ✅
Execution Mode execution_mode Either batch, or serial serial ❌
Card Type card_type Any known TitleCard identifier - see here standard ❌
Card Extension card_extension Either jpg, jpeg, png, tiff, gif, or webp jpg ❌
Card Dimensions card_dimensions Dimensions like WIDTHxHEIGHT 3200x1800 ❌
Episode Data Source episode_data_source Either emby, jellyfin, plex, sonarr, or tmdb sonarr ❌
Image Source Priority image_source_priority Any order/combination of emby, jellyfin, tmdb, or plex tmdb, plex ❌
Card Filename Format filename_format A valid Python formatting string {full_name} - S{season:02}E{episode:02} ❌
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 ❌
Language Codes language_codes A list of any language codes - ❌

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
  - ...

Execution Mode

How TitleCardMaker executes its core/main "loop" - must be either serial or batch.

serial mode processes each show one-at-a-time - meaning that TCM will read the first show in your series YAML files, look for episodes, create cards, and update Plex (among other things), then repeat for the 2nd show, 3rd, etc. While batch mode does each step for all shows in order. Although the two modes take (practically) the same amount of time, the default execution mode is serial as this gives immediate results for first-time users because cards are created and loaded into Plex right away.

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.

Example

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

options:
  card_type: roman

Card Extension

The image extension to use for all cards created by the TitleCardMaker. The benefits to changing this are minor performance differences (compressed types like jpg are faster to create), transparency (all card types support transparent images), and file size.

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

Card Dimensions

The image dimensions for all output title cards created by TCM. This is formatted as WIDTHxHEIGHT, e.g. 3200x1800. Reducing this can speed up card creation, reduce output file sizes, and (of course) affects the image quality; increasing this has the opposite effect.

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.

Whatever is specified here must be globally enabled (has an API key, URL if applicable, etc.).

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 are on the Plex server.

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. The first listed source is the highest priority, second is second highest, etc. These must be comma-separated, like tmdb, plex.

Currently there are four "interfaces" for source images, emby, jellyfin, tmdb, and plex - these can be combined in any order. For example, tmdb (for TMDb only), tmdb, plex (for TMDb and then Plex), etc.

If tmdb is a higher priority than Emby/Jellyfin/Plex, then Emby/Jellyfin/Plex will only be queried for source images after that episode has been "permanently blacklisted" by TMDb - i.e. has failed more than the specified retry count.

If emby, jellyfin, or 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 (this is uncommon).

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.

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.

Example

The following example globally enables special syncing for all series episodes gathered from Sonarr.

options:
  episode_data_source: sonarr
  sync_specials: true

Language Codes

TCM can translate spelled versions of an episode's season and episode numbers for custom episode text format and season titles - for example tres instead of three. If any non-English translations are desired, then the language code of the translation must be added to this option. This is done so that TCM doesn't waste time translating every number for every language when 99.9% of users won't use them.

There are some limitations on the supported language codes - i.e. not all languages support ordinal and cardinal versions - but each supported language code is listed below. Any number of languages can be listed.

All Supported Language Codes
  • cz
  • en
  • en_IN
  • fr
  • fr_CH
  • fr_BE
  • fr_DZ
  • de
  • fi
  • es
  • es_CO
  • es_NI
  • es_VE
  • id
  • ja
  • kn
  • ko
  • kz
  • lt
  • lv
  • pl
  • ro
  • ru
  • sl
  • sr
  • sv
  • no
  • dk
  • pt
  • pt_BR
  • he
  • it
  • vi
  • th
  • tr
  • nl
  • uk
  • te
  • hu
Example

The following example makes the Spanish (es) and Japanese (ja) translations of each episode's ordinal and cardinal season, episode, and absolute number available.

options:
  # other options
  language_codes:
  - es
  - ja

These could be used in a series YAML file like so:

series:
  Mr. Robot (2015):
    episode_text_format: "{episode_number_ordinal_es} Épisodio"
    # OR
    episode_text_format: "{episode_number_ordinal_ja}"

Which would produce text like Cuarto Épisodio or 四番目 - translated versions of "fourth episode".

Clone this wiki locally