Skip to content

Data Files

Jump to bottom
Collin Heist edited this page Feb 11, 2023 · 13 revisions

Background

Data files are created automatically by the Maker to store the episode information used for title card creation. These data files are formatted in YAML, and stored in the series' source directory.

Even though the Maker will create and modify these during its normal operation, you can freely add/change the data as you wish. Whether it's to update a title for an episode, add some arbitrary data, or add a new episode not in Sonarr.

Complete Example

data:
  Season 0:
    1:
      title: Mr. Robot_dec0d3d.doc
    # ...
  Season 1:
    1:
      abs_number: 1
      title: eps1.0_hellofriend.mov
    2:
      abs_number: 2
      title: eps1.1_ones-and-zer0es.mpeg
    # ...

File Structure

In broad terms, datafiles are organized in groups of episodes within seasons (see example).

Seasons

Each season is a section of the format Season {x}, with Specials using season number 0.

Episodes

Each episode is listed within the season under the episode number. All the data listed within these entries is what's used to create title cards.

When identifying new episodes with a series' specified episode data source - i.e. Sonarr/Plex/TMDb - matching is done using only the season and episode numbers, even if the specific episode information within the datafile doesn't match what's in that data source (such as a different title).

Absolute Number

The abs_number key is used within an episode to contain an episode's absolute numbering. This data is written to automatically by the Maker if Sonarr syncing is enabled globally and for the series for all episodes with an absolute number.

This value is used for episode text formatting when the {abs_number} key is specified, or for custom season titles when episode ranges are specified.

Title

The title key is (somewhat obviously) used within an episode to contain the episode's title. If specified directly, then the title is split by the Maker (based upon the series' card type characteristics). For example, if specified as:

title: "Longish Episode Title: With Many, Many Parts"

The text on the Title Card might look like "Longish Episode Title:" / "With Many Many Parts" (split into two lines by character count). However, if the title is specified as a list, then the title is taken as-is. For example:

title:
- "Longish"
- "Episode Title:"
- "With Many, Many Parts"

Will produce a Title Card with title text as "Longish" / "Episode Title:" / "With Many, Many Parts", independent of the card type's characteristics. This can lead to poorly formatted cards, but is intended as a way to manually specify title formatting should the Maker's splitting algorithm fail for some specific titles.

Preferred Title

The preferred_title key is used to contain a title for an episode that will be used instead of the title key. The same specification rules are used for this as title.

The intention of this is to allow for translated titles to be added and used automatically by the Maker. For example, the french titles of Mr. Robot will be used instead of the english ones if the series YAML looks like:

series:
  Mr. Robot:
    year: 2015
    translation:
      language: fr
      key: preferred_title

Database ID's

In order to better find episodes for title translation or source image gathering, the Maker can use the the ID of the episode to make matching more accurate/faster. These are not required, as typically the Maker is able to find an episode at runtime - or get them from Emby, Plex, Sonarr, or TMDb - but manually specifying them is permitted.

An episode can have its emby_id, imdb_id, tmdb_id, tvdb_id, and tvrage_id specified.

Example 
data:
  # Other episodes ..
  Season 4:
    1:
      title: 401 Unauthorized
      abs_number: 33
      emby_id: 75       # This number is unique to each Emby server
      imdb_id: tt7748418
      tmdb_id: 1905049
      tvdb_id: 7337251
      # tvrage_id: 123 TVRage is an archived database, and only has series pre-2016
Finding Database ID's

An episode's IMDb ID can be found in the URL of the episode's IMDb webpage, like so:

An episode's TVDb ID can be found in the URL of the episode's TVDb webpage, like so:

An episode's TMDb ID is only accessible via the TMDb API, under id:

Arbitrary Data

NOTE: This section mostly ties into the creation of custom card types, and is not applicable to most users

Because the Maker is designed to support any style of title card, datafiles are generalized to permit arbitrary data within each episode that is then passed to the series' respective card type class during initialization, as well as the given episode text format string. This can be used to override attributes per-episode, such as changing font file/color/other characteristic, episode text, etc.

For example, the AnimeCard style uses an argument called kanji. If this data is listed for a given entry, then the Maker will pass it (and any other unrecognized/non-standard attributes) to the AnimeCard during initialization. See the title translation section for more details on customizing this.

As a more generalized example, take the following data file:

data:
  Season 1:
    1: 
      title: Pilot
    2:
      title: Episode Title 2
      air_date: 01-01-2022

Because the "extra" air_date attribute is present for Episode 2, that data will be passed as a keyword argument to whatever CardType associated with this series, and might be used to modify the resulting Title card in some way. But this data will not be passed to the card for Episode 1. Whether this information is required or not is up to the creator of the CardType class.

Clone this wiki locally