Skip to content

Custom Variables

Throughout TCM, all Card variables, inputs, and extras may take advantage of any of the internally defined variables can be used, allowing for more fine-tuned customization. Accessing these variables is done by specifying the variable name in curly brackets ({}), such as {episode_number}.

This page documents all the available variables.

Variable Reference

For reference, each variable example is shown for the same Episode of Breaking Bad with some hypothetical TCM customizations.

Variable Name Description Example
series_name Name of the Series Breaking Bad
series_full_name Full name of the Series Breaking Bad (2008)
year Series Release year 2008
season_number Season number 2
episode_number Episode number 6
absolute_number Absolute episode number 13
absolute_episode_number Absolute number (if available), otherwise the episode number 13
number_of_seasons Number of seasons in the Series 5
airdate Episode airdate3 2009-04-12
watched Whether the Episode is watched or not true
Variable Name Description Example
title Original title of the Episode Peekaboo
title_text Formatted title text of the Card1 PEEKABOO
hide_season_text Whether to hide season text False
hide_episode_text Whether to hide episode text False
season_text The season text of the Card Season 2
episode_text The episode text of the Card Episode 6

Deprecated Variables

Previously, cardinal and ordinal spelling of numbers (e.g. Two, Second) were available as direct variables (season_number_cardinal). These are now accessed by the to_cardinal() and to_ordinal() functions. See here.

Variable Name Description Example
season_episode_count Number of Episodes in the season 13
season_episode_max Maximum episode number in the season 13
season_absolute_max Maximum absolute episode number in the season 20
series_episode_count Total number of Episodes in the Series 62
series_episode_max Maximum episode number in the Series 16
series_absolute_max Maximum absolute episode number in the Series 62

How do these differ?

At first glance, the maximum and count variables (like season_episode_count and season_episode_max) might appear the same (and in most cases they are), but for Series where Episodes are missing these two would differ.

For example, if I had Episodes 3-10 of Breaking Bad in TCM, season_episode_count would be 8, while season_episode_max would be 10.

The same logic is true for their absolute-number equivalents.

Variable Name Description Example
font_color Font color yellow
font_file File path to the font file /config/assets/fonts/0/Breaking Bad.ttf
font_size Font size 1.2
font_kerning Font kerning 2.3
font_stroke_width Font stroke width 1.0
font_interline_spacing Font interline spacing 0
font_interword_spacing Font interword spacing 20
font_vertical_shift Font vertical shift 20

For more information on the logo color attributes, see here

Variable Name Description Example
source_file Path to the Source Image /config/source/Breaking Bad (2008)/s2e6.jpg
card_file Path to the Title Card /config/cards/Breaking Bad (2008)/Season 2/Breaking Bad (2008) - S02E06.jpg
source_directory Path to the Series' source directory /config/source/Breaking Bad (2008)/
backdrop_file Path to the backdrop file5 /config/source/Breaking Bad (2008)/backdrop.jpg
logo_file Path to the logo file5 /config/source/Breaking Bad (2008)/logo.png
poster_file Path to the poster file /config/source/Breaking Bad (2008)/poster.jpg
logo_color Primary color of the logo green
logo_color_no_white Primary (non-white) color of the logo green
Variable Name Description Example
series_emby_id Emby ID of the Series 0:TV Shows:abcdef
series_imdb_id IMDb ID of the Series tt0903747
series_jellyfin_id Jellyfin ID of the Series 1:TV:def0123
series_sonarr_id Sonarr ID of the Series 3:25
series_tmdb_id TMDb ID of the Series 1396
series_tvdb_id TVDb ID of the Series 81189
series_tvrage_id TV Rage ID of the Series 18164
episode_emby_id Emby ID of the Episode 0:TV Shows:993981
episode_imdb_id IMDb ID of the Episode tt1232253
episode_jellyfin_id Emby ID of the Episode 1:TV:9d9da
episode_tmdb_id TMDb ID of the Episode 62097
episode_tvdb_id TVDb ID of the Episode 438917
episode_tvrage_id TV Rage ID of the Episode 710919

Emby, Jellyfin, and Sonarr IDs

The IDs of Emby, Jellyfin, and Sonarr are all unique to your server(s) and libraries.

Variable Name Description Example
extras Any assigned extras See below
NEWLINE A character to move text to a new line \n
BACKSLASH The \ character \

Any assigned extras are added as their variable name. For example, if I specify the "Episode Text Color" extra for the Series, then the variable episode_text_color would provided. This can be used to add arbitrary extra data to a Card.

Function Reference

In addition to defining many variables which can be used, TCM also implements many functions which allow for more customization. Each is described below.

Function Name Description Example Format String Example Output
titlecase() Write the number in "titlecase" - e.g. "Season" {titlecase(to_cardinal(season_number))} Two
to_cardinal() Convert the given number to its cardinal spelling {to_cardinal(episode_number)} two
to_cardinal() See above, but in another language2 {to_cardinal(episode_number, 'fr')} deux
to_ordinal() Convert the given number to its ordinal spelling {to_ordinal(episode_number)} sixth
to_ordinal() See above, but in another language2 {to_cardinal(episode_number, 'es')} sexto
to_short_ordinal() Convert the given number to a shorthand ordinal spelling {to_short_ordinal(season_number)} 2nd
to_short_ordinal() See above, but in another language2 {to_short_ordinal(season_number, 'ja')} 13番目
to_roman_numeral() Convert the given number to a roman numeral4 {to_roman_numeral(episode_number)} VI
format_date() Write the given date in some specific format3 {format_date(airdate, 'Week %-U of 52')} Week 02 of 52
get_image_color() See here {get_image_color(logo_file)} rgb(12,20,12)
Supported Language Codes
Code Language
am Amharic
ar Arabic
cz Czech
da Danish
de German
en English (the default)
eo Esperanto
es Spanish
fa Farsi
fi Finnish
fr French
fr_BE French (Belgium)
fr_CH French (Switzerland)
he Hebrew
hu Hungarian
id Indonesian
it Italian
ja Japanese
kn Kannada
ko Korean
kz Kazakh
lt Lithuanian
lv Latvian
nl Dutch
no Norwegian
pl Polish
pt Portuguese
pt_BR Portuguese (Brazil)
ro Romanian
ru Russian
sl Slovenian
sr Serbian
sv Swedish
te Telugu
tg Tajik
th Thai
tr Turkish
uk Ukrainian
vi Vietnamese

Cardinal vs. Ordinal Mnemonic

An easy way to remember whether you want the cardinal or ordinal text is that Cardinal starts with a C like Count - so one, two, three, etc.; while Oordinal starts with O like Order - so first, second, third, etc.

Parse Image Color

TCM has the ability to parse images for primary colors and use those in place of variables. This is similiar to the in-UI Analyze Pallette button. This functionality can be used with the get_image_color() function, which takes the form of:

get_image_color(
    image: Path,
    /,
    fallback: str,
    index: int = 0,
    *,
    colors: int = 8,
    alpha_threshold: int = 70,
    black_threshold: int = 40,
    white_threshold: int = 256,
)

If the above function signature does not make sense to you, see the provided examples for detail; or use the simplified {logo_color} or {logo_color_no_white} variables to avoid the function call altogether. Each available argument is described below:

  1. image The file to analyze. See the list of File variables for all available options, but generally this is logo_file to match the color of the logo.
  2. fallback The fallback color to use if the color analysis did not yield any meaningful results. This can occur if the specified file does not exist or if there was no color at the given index.
  3. index Which color number to return, zero-indexed. 0 meaning the first (most primary) color, 1 being the second, etc.
  4. colors The number of colors to group the image into. The higher the number the finer gradiations in color TCM will determine, which will result in more pixel-accurate matches - however this can also mean sequential colors may be different variations in the same color (e.g. light green, dark green, etc.). A lower number will result in TCM bucketing similiar colors together.
  5. alpha_threshold The transparency threshold which to remove colors from the analysis. Pixels which are more transparent than this will be removed - for example, if set to 75, pixels which are >25% transparent are ignored. This is a number between 0 and 100.
  6. black_threshold The RGB value threshold for determining if a color is black. Colors where all RGB values are below this threshold are considered black and ignored. This is a value between 0 and 255. For example, if set to 40, colors like rgb(30,30,30) would be ignored.
  7. white_threshold The RGB value threshold for determining if a color is white. Colors where all RGB values are above this threshold are considered white and ignored. This is a value between 0 and 255. For example, if set to 210, colors like rgb(220,220,220) would be ignored. The default being 256 means that no white colors are ignored.

The following usage will get the single most prominent color of the logo and fallback to red if one is not available.

get_image_color(logo_file, fallback="red")

The following usage will get the second most common color of the logo.

get_image_color(logo_file, fallback="blue", index=1)

The following usage will get the primary color of the poster, ignoring predominately white images.

get_image_color(poster_file, fallback="white", white_threshold=210)

Built-in Functions

Beyond the TCM-defined functions, all methods of built-in Python types - e.g. strings, lists, datetime, etc. - can also be used. See the Python docs for a complete reference; you can also ask on the Discord, or use an "AI" bot like ChatGPT.

  1. This is after any Font replacements, font case functions, and line splitting. ↩

  2. The second argument to the function is the language code. Not all languages support cardinal and ordinal numbering. These will raise an error during Card creation. ↩↩↩

  3. To write the airdate in any format other than the default, the format_date function must be used. A reference of all date variables is available here. ↩↩

  4. Roman numerals are not defined for values greater than 3999 (blame the Romans). These will raise an error during Card creation. ↩

  5. If per-season assets are enabled for the Series and exist, these will be used. Otherwise these are the Series-wide assets. ↩↩