Skip to content

TMDb Attributes

Jump to bottom
Collin Heist edited this page Mar 17, 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

Complete Example

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

Attributes

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

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

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

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.

TMDb 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 (lowercase x).

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)

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

Clone this wiki locally