Background

This is an optional YAML section of your global preferences file (preferences.yml) for outlining how the Maker should interact with the public database service TMDb. TMDb is used for many things by the Maker, but notably the following:

• Automatically downloading source image files for use in the title cards
• Automatically downloading series logos for creating Show Summaries
• Automatically adding episode title translations to data files

Complete Example

# preferences.yml
tmdb:
  api_key: abcdef0123456789
  retry_count: 5
  mimimum_resolution: 800x400
  skip_localized_images: false
  logo_language_priority: en

options:     # Global options ....
archive:     # Archive options ...
plex:        # Plex options ...
jellyfin:    # Jellyfin options ...
emby:        # Emby options ...
sonarr:      # Sonarr options ...
tautulli:    # Tautulli options ...
imagemagick: # Imagemagick options ...

Title Translation

When a given series uses the Maker's title translation functionality, such as the AnimeTitleCard, the Maker queries TMDb for a translated title of a given episode to add to the series' datafile.

For example, the following (when added to a series YAML file) adds Spanish titles to the datafile under the "label" or "key" spanish:

translation:
  language: es
  key: spanish

If you'd like the Spanish titles to be utilized automatically when generating title cards, the key needs to be specified as preferred_title so the Maker knows to use it instead of the standard English one - this is detailed here.

If a translation is not available when a card is first created and then a translation is later added, then the card will be deleted by the Maker so it can be remade with this new translation.

NOTE: These translations are user submitted, so there is no guarantee a given episode will have a given translation (or if it will be correct). Blacklisting is used to limit translation queries.

Multiple Translations

If you want to add translations of multiple languages for a single series - such as wanting Spanish episode titles, but adding Kanji to the AnimeTitleCard, these translations can be specified as list, like so:

translation:
- language: es
  key: preferred_title
- language: ja
  key: kanji

Generic Translations

For some reason, many episode titles are "translated" as Episode x independent of the actual episode title. The Maker will attempt to recognize "translations" of this form and reject them. So for example, if TMDb has a French title as Épisode {number} or the Japanese title as 第{number}話; that data will not be added to the datafile.

When these are noticed, I encourage you to contribute to TMDb and translate the title yourself, if possible.

NOTE: I entered a majority of these translations without speaking these languages (duh), so if you see that the Maker is rejecting non-generic titles, or is missing a translation for a given language code, submit an issue.

Logo Selection

When summary creation is enabled, the Maker will attempt to download logos from TMDb if they don't already exist. Logos are selected in the following manner:

1. Filter out all images whose TMDb-identified languages are not English, or a transparent filetype (.png or .svg)
2. Select the first .svg image if one exists
3. If no .svg image exist, select the image with the largest pixel count
4. If multiple images have the same pixel count, select the first image in this list (as returned by TMDb)

NOTE: .svg images require ImageMagick conversion to .png

Attributes

Name	YAML Attribute	Allowed Values	Default Value	Required
API Key	api_key	A valid TMDb API Key	-	:heavy_check_mark:
Retry Count	retry_count	A number	5	❌
Minimum Resolution	minimum_resolution	A resolution, specified as WIDTHxHEIGHT	0x0	❌
Localized Image Rejection	skip_localized_images	Boolean (true or false)	false	❌
Logo Language Priority	logo_language_priority	Any number of comma-separated languages	en	❌

API Key

TMDb requires an API key to validate all API queries. Follow the procedure below to obtain your own unique key.

Obtaining an API Key

See the TMDb documentation here.

Retry Count

How many times a request can fail before permanently being 'blacklisted' and immediately skipped. For a variety of reasons, the Maker can fail to successfully find a given resource. This is most commonly one of the following:

• The requested episode not existing in TMDb
• The requested episode might exist in TMDb, but cannot be matched/found
• All source images for a given episode aren't of the minimum resolution
• There are no source images for a given episode

In order to limit unnecessary API queries to TMDb caused by repeatedly asking for a resource that does not exist, a specific episode is "blacklisted" after this specified number of operations. All failed operations are temporarily blacklisted for 12 hours before being tried again; however, if the same operation has failed retry_count many times, it is permanently skipped.

If some query is blacklisted that shouldn't be, you have a few options:

1. Increase the global retry count value
2. Delete the blacklist file manually (under modules/.objects/tmdb_blacklist.yml or /maker/modules/.objects/tmdb_blacklist.json on Docker)
3. User the fixer to un-blacklist a series
4. Use the fixer to delete the blacklist file

NOTE: Despite offering a very reliable and useful service, TMDb is free to all users (even through the API). As such, please be mindful in not abusing this service, and of course contribute to TMDb if possible.

Minimum Resolution

Although TMDb has resolution and aspect-ratio restrictions on images users can contribute, the Maker permits enforcing specific resolution restrictions on images that are downloaded from TMDb if you choose to ignore 'low quality' images outright. This value should be specified as WIDTHxHEIGHT.

Depending on your screen size, there is marginal benefit to using images with a resolution larger than 1920x1080.

Source Image Selection

Beyond filtering out images below the specified minimum resolution, the Maker does implement some logic when choosing which image to download for a given entry (if there is more than one option). Source images are selected in the following manner:

1. Filter out all images with widths less than the minimum width, or heights less than the minimum height
2. If localized image rejection is enabled, filter out images with a language set
3. Select the image(s) with the largest pixel count
4. If multiple images have the same pixel count, select the image(s) with the highest user rating score
5. If multiple images have the same pixel count and user rating, select the first image in this list (as returned by TMDb)

Localized Image Rejection

Whether to reject images with langauge codes from TMDb. This option can also be overwritten per-series

When images are uploaded to TMDb, users have the ability to select a language. This can be used to categorize images with subtitles in them, in-universe text (such as signs), or, in rare cases, title cards uploaded directly to TMDb - such as Fringe S01E01. This option allows for rejection of those images.

Logo Language Priority

TCM will automatically look for series logos on TMDb. By default, TCM will only look for and download English logos, but if you would like to download other languages if they are available, then this option can be used to specify those.

This option takes a sorted comma-separated list of language codes and uses that to identify which logo to select. Any number of languages can be specified. The first language listed is the highest priority.

For example, if I wanted to download English logos, and the Japanese logo only if no English ones are available, then I'd specify the following:

tmdb:
  # other options
  logo_language_priority: en, ja

Any of the following language codes are supported: ar, cs, de, en, es, fr, he, hu, id, it, ja, ko, pl, pt, ro, ru, sk, th, tr, uk, vi, or zh.