Custom Source Files

Background

TitleCardMaker looks for source images with "default" names depending on the indicated style. These defaults can be overwritten so that custom source files can be used for specific seasons, ranges of episodes, or individual episodes - and these custom source files can be toggled based on whether an episode's watch status in Plex (if linked).

This specification is done through the custom season specification YAML of a series YAML file, and is described below.

Default Source Files

The defaults source files are as follows:

Style	Source Filename	Example
Any art style1	backdrop.jpg	backdrop.jpg
Any non-art style	s{season_number}e{episode_number}.jpg	s1e1.jpg, s4e20.jpg

¹This is any style with the art modifier, so art blur, art grayscale, art unique, etc.

Each of these are looked for in the source directory for the respective show.

Specifying Custom Source Files

Per-season

Source files can be specified per-season via the seasons YAML. This means the custom source file is utilized for all episodes of the indicated season. See examples below.

Simple Example

series:
  Mr. Robot (2015):
    seasons:
      1:
        source: season1.jpg
      2:
        source: season2.jpg

The above series YAML overrides the source file for all episodes of seasons 1 and 2 in Mr. Robot to season-wide source files season1.jpg and season2.jpg respectively. Source files for any other seasons (0, 3, and 4) still use the default files.

Applying to Unwatched Episodes

libraries:
  TV Shows:
    path: ./tv/

series:
  Mr. Robot (2015):
    library: TV Shows
    seasons:
      1:
        source: season1.jpg
        source_applies_to: unwatched
      2:
        source: season2.jpg

Just like the first example, the above series YAML overrides the source file for season 1 and 2 of Mr. Robot. However, by specifying source_applies_to: unwatched for season 1, the given season file will only override the default source file if the episode is marked unwatched in Plex. If the episode is watched, the default s1e1.jpg, s1e2.jpg, etc., files will be used instead.

Because the source file is being updated based on an episode's watch status in Plex the series requires a library so that TCM can find the episode in Plex.

Using a Format String

Rather than specifying source file that applies to the entire season, a source format string can be provided instead. This can be useful if you want to use a custom file for every episode of a season, but don't want to write the custom file for every episode individually. For example:

series:
  Mr. Robot (2015):
    seasons:
      1:
        source: "s{season_number}e{episode_number}-custom.jpg"
      2:
        source: "s{season_number}e{episode_number}-custom.jpg"

The above series YAML shows the override of the source file for seasons 1 and 2, and the {} syntax shows how a format string can be specified. This effectively tells TCM to use files like s1e1-custom.jpg, s1e2-custom, ..., s2e1-custom.jpg, etc., for each episode of those seasons.

Across an Episode Range

Source files can be specified across episode ranges via the episode_ranges YAML. This means the custom source file is utilized for all episodes of the indicated range. See examples below.

NOTE: Source files can be specified via the episode indices (e.g. s1e1-s1e4), but can also be used in the absolute episode number specification (e.g. 1-4).

Simple Example

series:
  Mr. Robot (2015):
    episode_ranges:
      s1e1-s1e5:
        source: some_file.jpg
      s2e1-s2e5:
        source: another_file.jpg

The above series YAML overrides the source file for the first 5 episodes of seasons 1 and 2 in Mr. Robot to the source files some_file.jpg and another_file.jpg respectively. Source files for any other episodes outside these ranges use their default files.

Applying to Unwatched Episodes

libraries:
  TV Shows:
    path: ./tv/

series:
  Mr. Robot (2015):
    library: TV Shows
    episode_ranges:
      s1e1-s1e5:
        source: some_file.jpg
        source_applies_to: unwatched
      s2e1-s2e5:
        source: another_file.jpg

Just like the first example, the above series YAML overrides the source file for the first five episodes of season 1 and 2 of Mr. Robot. However, by specifying source_applies_to: unwatched in the first range, the given file will only override the default source file if the episode is marked unwatched in Plex. If the episode is watched, the default s1e1.jpg, s1e2.jpg, etc., files will be used instead.

Because the source file is being updated based on an episode's watch status in Plex the series requires a library so that TCM can find the episode in Plex.

Using a Format String

Rather than specifying source file that applies to the entire range, a source format string can be provided instead. This can be useful if you want to use a custom file for every episode of the range, but don't want to write the custom file for every episode individually. However, the range still cannot cross season boundaries. For example:

series:
  Mr. Robot (2015):
    episode_ranges:
      s1e1-s1e5:
        source: "s{season_number}e{episode_number}-custom.jpg"
      s2e1-s2e5:
        source: "s{season_number}e{episode_number}-custom.jpg"

The above series YAML shows the override of the source file for the first five episodes of seasons 1 and 2, and the {} syntax shows how a format string can be specified. This effectively tells TCM to use files like s1e1-custom.jpg, s1e2-custom, ..., s2e1-custom.jpg, etc., for each episode of those ranges.

How Manual Sources Interact with Series Card Styles

It might not be obvious how a series' card style interacts with manually specified sources.

If an image is specified manually (via either seasons or episode_ranges), then that image is assumed to match the style of the episodes. In other words, if the style for a series is art, and a specified source applies to all episodes, then the image is assumed to be art. If it's blur, then the image is assumed to be some image that needs to be blurred. And if it's unique, then it's assumed to be a spoiler image.