Series YAML Files
These YAML files are used to indicate to the Maker which series (interchangeably referred to as shows) to create title cards for. They describe card characteristics (type, fonts, season titles, etc.), as well as details of whether that show should sync to individual interfaces.
Creating and populating these files is the only way to 'tell' TitleCardMaker what series to automatically create title cards for. These can be automatically generated/synced to your instance of Plex or Sonarr so that the Maker can automatically create all cards for all series within your libraries; or they can be manually created and edited. This is described in greater detail here.
Note
The TitleCardMaker keeps records of the exact card config used to create a series' title cards. Changing some aspect of this config that affects the card style/look will result in TCM deleting, remaking, and potentially reloading these cards. This process is done automatically. These attributes are labelled as monitored in the main series table.
In this example, there is an instance of Plex with (at least) one library called TV located under the /Media/TV Shows/ directory. The Maker will automatically create cards for the "Mr. Robot" series.
Note
This example lists every possible customization of a series, and because of that is very messy and not indicative of a realistic use-case of the Maker. It is intended to showcase the possibilities/format of each option.
Click to Expand
libraries:
TV:
path: /Media/TV Shows/
plex_name: TV Shows
media_server: plex
fonts:
font_1:
color: "rgb(100, 0, 255)"
size: 110%
templates:
no-sync:
archive: <<archive>>
sonarr_sync: false
tmdb_sync: false
tmdb_skip_localized_images: false
sync_specials: false
series:
Mr Robot (2015):
name: Mr. Robot
episode_data_source: plex
library: TV
filename_format: "{full_name} - S{season:02}E{episode:02} - {title}"
card_type: standard
template: {name: no-sync, archive: false}
episode_text_format: "EPISODE {episode_number}"
watched_style: unique
unwatched_style: blur
archive_style: unique
media_directory: /Media_2/TV Shows/Mr. Robot/
font: font_1
translation:
- language: fr
key: preferred_title
- language: es
key: spanish_title
ignore_preferred_titles: false
seasons:
hide: false
0:
title: "specials_0.0"
source: backdrop-specials.jpg
source_applies_to: unwatched
1: "season_1.0"
2: "season_2.0"
3: "season_3.0"
4: "season_4.0"
episode_ranges: # This is redundant to season map
1-10: season_1.0 # Just for example purposes
11-22: season_2.0
23-32: season_3.0
33-45: season_4.0
extras: # Not used by this card
background: black
imdb_id: tt4158110
sonarr_id: 100
tmdb_id: 62560
tvdb_id: 289590
season_posters:
create: true
titles:
0: Specials
font:
file: ./fonts/MR ROBOT.ttf
color: "#CE3F39"
size: 95%
kerning: 105%
archive_name: French Titles
archive_all_variations: true
archive_variations:
- card_type: anime
- card_type: Beedman/GradientLogoTitleCard
extras:
logo: ./source/Mr. Robot (2015)/logo.pngThere are four major sections within a series YAML file. They are:
- Libraries - which defines where to physically put title cards, and under which libraries within Plex those series can be found to load title cards into
- Fonts - which defines any custom fonts to be repeatedly used by series
- Templates - which defines common "structures" of options to simplify the process of specifying series
- Series - which defines the actual series/TV Shows to make title cards for
All of these sections are technically optional for a series YAML file; however, defining a file with no series would effectively render that file meaningless as no cards will be created (this is the TitleCard Maker after-all).
This optional section of the series YAML file is used to define media libraries where title cards should be created and stored. This section can be entirely omitted if cards are only going to be archived, and can contain any number of libraries.
| Name | YAML Attribute | Allowed Values | Default Value | Required |
|---|---|---|---|---|
| Library Name | {library} |
Any string | - | ❌ |
| Library Path |
{library}, path
|
Any valid directory | - | ✅ |
| Override Name |
{library}, library_name
|
Any string | - | ❌ |
| Media Server |
{library}, media_server
|
emby, jellyfin, or plex
|
Depends1 | ✅ 2 |
| Default Data |
{library}, any series option |
- | - | ❌ |
1If only one server type is listed in your preferences file, that will be used by default.
2Only required if multiple media server types are listed in your preferences file.
This library name is used to map the library key within a given series to the media directory for the created cards. This name is also used to find series within the given library within Plex to add the title cards (unless plex_name is specified). In the above example, the cards will be created within the /Media/TV Shows/Mr. Robot (2015)/ directory, and the metadata of "Mr. Robot" within the Plex "TV Shows" library will be refreshed if any new cards are created.
NOTE: Because YAML does not allow duplicate values - i.e. two libraries of the same name - if you are mapping multiple directories to the same Plex library, give them unique names, and then the same plex_name.
Required for each listed library, this path indicates the top-level media directory for cards created under this library. All series will be created below this card as the format /{library}/{series name} ({year})/, unless overwritten with the media directory option for a specific series.
NOTE: It is not required that this path corresponds to the actual location of the media for this series, or for this library.
Optional name of the library within Emby/Plex a given series will be found in. If not provided, the actual name of the library in YAML will be used.
Media server the given library will be found in. This is only required if you are using more than one of Emby, Jellyfin, and Plex. If using only one of these, then that server is used automatically.
This is necessary because you can hypothetically have two libraries of the same name within these servers, and then TCM would have no way to determine which server the cards should be loaded into.
Any default attributes that will apply to all series within this library. This data can be overwritten by each series, and can be anything adjustable per-series. See the example for details.
The following example defines a few things:
- Two libraries labelled
AnimeandTV - The
Animelibrary is located at/media/Anime, andTVat/media/TV Shows - The
Animelibrary is labeledAnimewithin Plex, whileTVis labeledTelevision - All series that are a part of the
Animelibrary have their seasons hidden by default - Attack on Titan overrides the default season-hiding behavior
libraries:
Anime:
path: /media/Anime
card_type: anime
seasons:
hide: true
TV:
path: /media/TV Shows
plex_name: Television
series:
Attack on Titan (2013):
library: Anime
seasons:
hide: false
Cowboy Bebop (1998):
library: Anime
Only Murders in the Building (2021):
year: 2021
library: TVThis will automatically create cards at /media/Anime/Attack on Titan (2013)/, /media/Anime/Cowboy Bebop (1998)/, and /media/TV Shows/Only Murders in the Building (2021)/
This optional section of the file can be used to define any number of custom fonts that can be referenced by multiple series here. These should be specified under a label, that can be referred to by a series. For example, the below YAML creates a custom font labelled font_label_1 and then two example shows (Example Show and Example 2) uses all the font characteristics it defines.
fonts:
font_label_1:
size: 110%
color: red
# ...
series:
Example Show:
year: 2000
font: font_label_1
Example 2:
year: 1999
font: font_label_1Any combination of font customization may be given, but depending on the series' card type, not all customization will necessarily by utilized. For example, if the series card type is star wars no custom font characteristics will be utilized.
For specific customization options, see here.
Each series listed under the series key defines a new set of title cards to create. For series titles with colons (:), be sure to surround the name in quotes.
Every series has the following possible configurable attributes listed below. If an attribute is indicated as monitored, then changing it after cards have been made will result in TCM deleting and remaking those cards
| Name | YAML Attribute | Allowed Values | Default Value | Monitored | Required |
|---|---|---|---|---|---|
| Series Year | year |
Any 4-digit integer | - | ❌ | ✅1 |
| Series Name | name |
Any string | - | ❌ | ❌ |
| Episode Data Source | episode_data_source |
See here | Global episode data source | ❌ | ❌ |
| Image Source Priority | image_source_priority |
See here | Global priority | ❌ | ❌ |
| Refresh Titles | refresh_titles |
Boolean (true or false) |
true |
❌ | ❌ |
| Library | library |
Any listed library | - | ❌ | ❌ |
| Filename Format | filename_format |
See here | Global filename format | ❌ | ❌ |
| Card Type | card_type |
Any valid card type | Global or Library card type | ✅ | ❌ |
| Episode Text Format | episode_text_format |
Format string | This series' card type's default | ✅ | ❌ |
| Sonarr Syncing | sonarr_sync |
Boolean (true or false) |
true |
❌ | ❌ |
| Special Syncing | sync_specials |
Boolean (true or false) |
Global sync_specials value | ❌ | ❌ |
| TMDb Syncing | tmdb_sync |
Boolean (true or false) |
true |
❌ | ❌ |
| Localized Image Rejection | tmdb_skip_localized_images |
Boolean (true or false) |
Global skip_localized_images | ❌ | ❌ |
| Watched Style | watched_style |
Any valid style | Global watched style | ✅ | ❌ |
| Unwatched Style | unwatched_style |
Any valid style | Global unwatched style | ❌ | ❌ |
| Archive Style | archive_style |
Any valid style | The series unwatched style | ✅ | ❌ |
| Media Directory | media_directory |
Any valid path | Library path | ❌ | ❌ |
| Font | font |
A font identifier, or font customization options | - | ✅ | ❌ |
| Season Posters | season_posters |
A season poster specification | - | ❌ | ❌ |
| Season Hiding |
season, hide
|
Boolean (true or false) |
false |
✅ | ❌ |
| Season Titles |
season, {integer}
|
Season number to text (and/or source) | Default season titles2 | ✅ | ❌ |
| Episode Ranges |
episode_ranges, {start}-{end}
|
Absolute episode number to text (and/or source) | - | ✅ | ❌ |
| Title Translation Language |
translation, language
|
An ISO-639-1 language code | - | ✅ | ❌ |
| Title Translation Key |
translation, key
|
Any string | - | ✅ | ❌ |
| Ignore Preferred Titles | ignore_preferred_titles |
Boolean (true or false) |
false |
✅ | ❌ |
| Extras |
extras, {anything}
|
Anything | - | ✅ | ❌ |
| Database ID's |
emby_id, imdb_id, sonarr_id, tmdb_id, tvdb_id, or tvrage_id
|
Any valid ID | - | ❌ | ❌ |
| Archive Enable | archive |
Boolean (true or false) |
true |
❌ | ❌ |
| Archive Name | archive_name |
Any string | Default name | ❌ | ❌ |
| Archive All Variations | archive_all_variations |
Boolean (true or false) |
Global all_variations value | ❌ | ❌ |
| Archive Variations | archive_variations |
A list of modifications | - | ❌ | ❌ |
1 The year is not required if the series is listed under its full name - i.e.
Breaking Bad (2008)instead of justBreaking Bad.
2 This is
0->Specials,1->Season 1,2->Season 2, etc.
This required attribute is the first air-date year of the series. If the series is listed under its full name, then the year can be omitted. See the example for details.
Example
The following example showcases the most basic requirements for an entry. It also showcases the two ways in which this data can be specified (normally and under its full name).
series:
# Long method, year required
Mr. Robot:
year: 2015
# Full name method, year optional - the preferred method
Mr. Robot (2015): {}In the full name method, because there are no customizations given to Mr. Robot, it can be given as "blank" with {}. In general this is not necessary, as you'll specify a library, template, or something else.
This optional attribute can be used to override a series' name. Really only necessary if there are two series of the same name as YAML does not permit duplicate attributes.
Where to source episode data - i.e. episode titles and numbers - for this series. If unspecified, the global setting is used by default.
Setting this to your media server (e.g. emby or plex) for series like "Firefly", "Star Wars: The Clone Wars" or some Anime that are stored in "arc" order (as opposed to the aired seasons you'd find on Sonarr or TMDb) can save you the effort of manually adjusting your data files to these custom orders. This also has the added bonus of only creating cards for episodes that you personally have on your server.
This can be emby, jellyfin, plex, sonarr, or tmdb (each requiring the associated settings to be enabled. There is more detail here.
NOTE: If a series' source is
emby,jellyfin, orplex, then that series must have an associated library so the Maker can find the series in order to pull data from.
Example
The following example sources episode titles/info for Firefly from Plex.
libraries:
TV Shows:
path: /media/TV
media_server: plex
series:
Firefly (2002):
library: TV Shows
episode_data_source: plexThe priority of sources to gather images from. This is described in greater detail here, and overrides the global value.
Whether to refresh titles in this series' data file to match the titles present on this series' episode data source. When new titles are detected, the old title is replaced, and that episode's associated card is deleted and remade. This is enabled by default.
If you are entering manually adjusted/custom episode titles in the data file, and would like those custom titles to be utilized instead of the "correct" ones, this should be disabled.
Example
If the "official" title for the movie of Demon Slayer is Demon Slayer Movie: Mugen Train on Sonarr/TVDb, but I'd like to instead create the card with the title Mugen Train, then this setting should be disabled so that TCM doesn't automatically replace my "custom" title with the "official" one.
In order to automatically create title cards for a library within Emby/Jellyfin/Plex, this attribute must be specified and match a library name. If unspecified, cards will only be created within an archive.
Example
The following example specifies a library labeled TV, and adds Breaking Bad to it - meaning the Maker will attempt to create title cards for Breaking Bad and load them into Plex under the library name TV Shows.
libraries:
TV:
path: /media/TV
library_name: TV Shows
series:
Breaking Bad:
year: 2008
library: TVThis optional attribute can be used to override the filename format for all cards created for this series. If unspecified, the global format is used.
The specification for this format is detailed here.
Example
The following example names files like Breaking Bad [tt0903747] - S01E01 - Pilot.jpg for Season 1 Episode 1 of Breaking Bad:
series:
Breaking Bad (2008):
filename_format: "Breaking Bad [tt0903747] - S{season:02}E{episode:02} - {title}"This optional attribute specifies what type of card to create for the given series. Must be a known custom card type.
Example
The following example specifies the RomanNumeral card type for Tower of God:
series:
Tower of God:
year: 2020
card_type: romanFormat string for how to format all episode text for this series. This is described in much greater detail here.
Whether to sync this series with Sonarr. Requires a globally enabled instance of Sonarr.
Disabling this prevents new episodes being added automatically if the series' episode data source is Sonarr.
Example
The following example disables Sonarr syncing for Mr. Robot:
series:
Mr. Robot:
year: 2015
sonarr_sync: falseWhether to sync this series with TMDb. Requires a globally enabled instance of TMDb.
Disabling this prevents the Maker from automatically downloading source images from TMDb for this series if TMDb is an enabled image source.
Example
The following example disables TMDb syncing for Mr. Robot:
series:
Mr. Robot:
year: 2015
tmdb_sync: falseWhether this series should reject images from TMDb that have a set language. This overrides the global setting.
Disabling this prevents the Maker from downloading source images from TMDb if the image has a language.
Whether to sync all specials from this series episode source to this series' datafile. This overwrites the global prefernce.
If disabled, you can still manually add specials to the datafile of this series, the Maker will just not add them for you.
How to modify the cards created for either watched/unwatched episodes of this series. Whether to create all cards as "normal", blur the source image, or use generic series backdrop art. The default behavior is to use the global setting set in the preferences file.
By default, a series' archive uses the specified watched style, but if you want a different style to be used then this can be manually specified via archive_style.
A complete summary of the available options is located here.
Example
The following example blurs all unwatched episodes of Better Call Saul within Plex, and creates unblurred (standard) cards for watched episodes. The archived cards are created in the blurred style as well. In order for the Maker to properly determine the watch status of each episode, Plex must be enabled, and Better Call Saul must be present in the library called TV.
libraries:
TV:
path: /media/TV/
series:
Better Call Saul (2015):
library: TV
watched_style: unique
unwatched_style: blur
archive_style: blurOptional attribute to override the media directory for a given series. Can be specified if your library series aren't formatted as title (year).
NOTE: It is not required that this path corresponds to the actual location of the media for this series, or for this library.
Example
The following example creates the cards for Money Heist at the directory /media/TV/La casa de papel (2017)/, instead of the library-default of /media/TV/Money Heist (2017)/ (as determined by the series name/year).
libraries:
TV:
path: /media/TV/
series:
Money Heist (2017):
library: TV
media_directory: "/media/TV/La casa de papel (2017)/"Custom font to use for this series. This can be a font identifier present under fonts, or it can be any font options (all detailed here).
Example
For example, the two following YAML sections are both valid and specify the exact same font characteristics:
fonts:
Star Wars Font:
case: lower
color: "#AB8630"
file: ./fonts/StarWars.ttf
size: 110%
series:
The Mandalorian (2019):
font: Star Wars Font # This must match the fonts labelThe above is identical to:
series:
The Mandalorian (2019):
font:
case: lower
color: "#AB8630"
file: ./fonts/StarWars.ttf
size: 110%Customize automatic season poster creation for this series. All customization is detailed here.
Example
The following example will automatically create season posters for Mr. Robot, looking for the files season1.jpg, season2.jpg, etc. The resulting files will be at locations like /media/TV/Mr. Robot (2015)/Season 1/Season1.jpg, etc.
libraries:
TV:
path: /media/TV/
series:
Mr. Robot (2015):
library: TV
season_posters:
titles:
1: season_1.0
2: season_2.0
3: season_3.0
4: season_4.0Whether to hide season titles in cards created for this series. Not all card types utilize season titles (see StarWarsTitleCard), so this attribute is not always utilized.
Example
The following example will create cards that have no season titles.
series:
Abbot Elementary (2021):
seasons:
hide: trueThe seasons and episode_ranges options are described in greater detail here.
NOTE: Both season titles and episode ranges cannot both be specified for a given series.
Example
The following example will create the title cards for One Piece with their arc titles used as season text. Not all arcs are listed below (for obvious reasons..).
series:
One Piece (1999):
episode_ranges:
1-3: Romance Dawn
4-8: Orange Town
9-18: Syrup Village
19-30: Baratie
31-44: Arlong Park
# etc.The Maker supports adding translated episode titles under an arbitrary key within the series' datafile. This is detailed here, and is utilized by the AnimeTitleCard class to add kanji to a card.
You can specify any number of translations per-series, as long as they're specified as list - see the following example for details.
Which language titles should be requested in, must be an ISO-639-1 language code.
Under which key within the series datafile should these translations be stored. If the translated titles are preferred instead of the original (English) titles, this key should be preferred_title.
Example
The following example will create the title cards for Attack on Titan with their French titles, and with Kanji (as that's supported by the AnimeTitleCard).
series:
Attack on Titan (2013):
card_type: anime
translation:
- language: fr
key: preferred_title
- language: ja
key: kanjiIf you have previously specified a preferred title translation and would like to disable those titles, instead using the original titles as they appear in your episode data source, specify ignore_preferred_titles: false.
This is useful for archive variations, or maintaining cards in multiple languages.
To support any type of card, arbitrary "extra" information can be specified within a given series, and this data will be passed to that series' card. This allows for any data to be entered for a series and given to the card type, and is especially useful for user-submitted card types.
Example
For example, the LogoTitleCard requires a logo and optionally a background. These aren't explicitly handled, but can (and must for the logo) be specified as an extra - this is shown below:
series:
Survivor:
year: 2000
card_type: reality tv
extras:
logo: ./source/Survivor (2000)/logo.png
background: skyblueIn order to better find episodes for title translation or source image gathering, the Maker can use the the ID of that series to make matching more accurate/faster. These are not required, as typically the Maker is able to determine them at runtime and/or find the series by the name and year, but specifying them is permitted.
A series can have its emby_id, imdb_id, jellyfin_id, sonarr_id, tmdb_id, tvdb_id, and tvrage_id specified.
Emby
A series' Emby ID can be viewed via the API, or looking at the web URL of the series when viewing the show. For example, a URL of http://192.168.0.11:8096/emby/web/index.html#!/item?id=75&context=home&serverId=... indicates the ID of the series to be 75.
IMDb
Specifying the IMDb ID of a series can improve matching within Emby, TMDb, and Plex.
This can be found on a series' IMDb page getting the tt... string from the main URL. For example:
The IMDb ID of Mr. Robot is tt4158110.
Sonarr
Sonarr doesn't typically "expose" a series' ID, however the fixer can be used to list all ID's. This is only typically necessary if your name within YAML doesn't match that within Sonarr.
For example, if I have my YAML generating cards for Agents of SHIELD, but the series is named Marvel's Agents of S.H.I.E.L.D., by specifying the Sonarr ID manually, the Maker will be able to find that series more accurately. The ID for this series is 32, as shown in the excerpt from the fixer printout:
30 : It's Always Sunny in Philadelphia
Colgados en Filadelfia
31 : Los Espookys
32 : Marvel's Agents of S.H.I.E.L.D.
Marvel Agents of SHIELD
Agents of SHIELD
Marvels Agents of SHIELD
Agents Of S.H.I.E.L.D.
Marvels Agents of S H I E L D
A SHIELD ügynökei
A SHIELD ugynokei
Agentes de S H I E L D
Agentes de S H I E L D
33 : Marvel's Daredevil
Daredevil
Marvels Daredevil
TMDb
Specifying the TMDb ID can help the Maker find a series on TMDb it otherwise cannot.
This can be determined by finding the series on TMDb's website and getting the number from the main URL. For example:
The TMDb ID of Mr. Robot is 62560.
TVDb
Specifying the TVDb ID can help the Maker find a series on Emby, TMDb, and Plex.
This can be found on a series' main landing page on TVDb. For example:
The TVDb ID of Mr. Robot is 289590.
TVRage
TVRage is a now archived database service that can help the Maker find a series on TMDb.
This can be found on a series' main landing page on tvrage.com. However, only series pre-2016 are available.
Example
The following example specifies all ID's for Mr. Robot.
series:
Mr. Robot (2015):
imdb_id: tt4158110
jellyfin_id: abcdef123456678 # Unique to each Jellyfin server
emby_id: 75 # Unique to each Emby server
sonarr_id: 100 # Unique to each Sonarr instance
tmdb_id: 62560
tvdb_id: 289590
# tvrage_id: # Mr. Robot is not on TVRageWhether to archive this series. Requires a globally enabled archive.
Example
The following example prevents Mr. Robot from being archived:
series:
Mr. Robot (2015):
archive: falseCustom name to use for the archive of this series. If specified, no sub-variations will be created - i.e. a series with a custom font will not create a generic font archive as well - unless manually specified with archive variations. Requires a globally enabled archive.
Example
The following example will name the archive for Mr. Robot named "Seasonless Variation". No other archives will be created.
series:
Mr. Robot (2015):
seasons:
hide: true
archive_name: Seasonless VariationIn order make archiving different variations of the same series more efficient, this attribute can take any number of variations to apply on top of the base YAML for this series. These variations will always ignore the library and media_directory specification of the series, meaning they'll only ever be created in the archive.
This is most typically used with different card_type's.
Example
The following example shows a situation where the cards for The Mandalorian are created in the star wars style, but archive variations of this series are kept in the standard and the Wdvh/StarWarsTitleOnly style.
libraries:
TV:
path: /media/TV/
series:
The Mandalorian (2019):
library: TV
card_type: star wars
episode_text_format: "Chapter {abs_number}"
archive_variations:
- card_type: standard
- card_type: Wdvh/StarWarsTitleOnly