Series YAML Files - CollinHeist/TitleCardMaker GitHub Wiki

Background

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.

Complete Example

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

Attributes

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

Libraries

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.

Library Name

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.

Library Path

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.

Override Name

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

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.

Default Data

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.

Example

The following example defines a few things:

  • Two libraries labelled Anime and TV
  • The Anime library is located at /media/Anime, and TV at /media/TV Shows
  • The Anime library is labeled Anime within Plex, while TV is labeled Television
  • All series that are a part of the Anime library 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: TV

This 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)/

Fonts

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_1

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

Series

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 - ✅ ❌
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 just Breaking Bad.

2 This is 0 -> Specials, 1 -> Season 1, 2 -> Season 2, etc.

Series Year

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.

Series Name

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.

Episode Data Source

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, or plex, 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: plex

Image Source Priority

The priority of sources to gather images from. This is described in greater detail here, and overrides the global value.

Refresh Titles

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.

Library

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: TV

Filename Format

This 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}"

Card Type

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: roman

Episode Text Format

Format string for how to format all episode text for this series. This is described in much greater detail here.

Sonarr Sync

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: false

TMDb Sync

Whether 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: false

Localized Image Rejection

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

Special Syncing

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.

Styles

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: blur

Media Directory

Optional 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)/"

Font

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 label

The above is identical to:

series:
  The Mandalorian (2019):
    font:
      case: lower
      color: "#AB8630"
      file: ./fonts/StarWars.ttf
      size: 110%

Season Posters

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

Season Hiding

Whether 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: true

Season Titles

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

Title Translation

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.

Title Translation Language

Which language titles should be requested in, must be an ISO-639-1 language code.

Title Translation Key

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: kanji

Extras

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: skyblue

Database ID's

In 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 TVRage

Archive

Whether to archive this series. Requires a globally enabled archive.

Example

The following example prevents Mr. Robot from being archived:

series:
  Mr. Robot (2015):
    archive: false

Archive Name

Custom 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 Variation

Archive All Variations

Whether to archive all sub-variations of this series. This overrides the global setting.

Archive Variations

In 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
⚠️ **GitHub.com Fallback** ⚠️