Skip to content

TMDb Attributes

Jump to bottom
Collin Heist edited this page Apr 9, 2022 · 25 revisions

Background

This is an optional YAML section 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

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.

These translations are user submitted, so there is no guarantee a given episode will have a given translation. Blacklisting is used to limit translation queries.

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

Complete Example

tmdb:
  api_key: abcdef0123456789
  retry_count: 5
  mimimum_resolution: 800x400

Attributes

Name YAML Attribute Allowed Values Default Value Required
API Key api_key A valid TMDb API Key - ✔️
Retry Count retry_count A number 3 ❌
Minimum Resolution minimum_resolution A resolution, specified as WIDTHxHEIGHT 0x0 ❌

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 24 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/db_blacklist.pkl)
  3. Use the fixer to delete the blacklist

NOTE: Despite offering a 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. Select the image(s) with the largest pixel count
  3. If multiple images have the same pixel count, select the image(s) with the highest user rating score
  4. If multiple images have the same pixel count and user rating, select the first image in this list (as returned by TMDb)
Clone this wiki locally