TMDb Attributes
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
# 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 ...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: spanishIf 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.
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: kanjiFor 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.
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:
- Filter out all images whose TMDb-identified languages are not English, or a transparent filetype (
.pngor.svg) - Select the first
.svgimage if one exists - If no
.svgimage exist, select the image with the largest pixel count - If multiple images have the same pixel count, select the first image in this list (as returned by TMDb)
NOTE:
.svgimages require ImageMagick conversion to.png
| Name | YAML Attribute | Allowed Values | Default Value | Required |
|---|---|---|---|---|
| API Key | api_key |
A valid TMDb API Key | - | ✔️ |
| 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 |
❌ |
TMDb requires an API key to validate all API queries. Follow the procedure below to obtain your own unique key.
See the TMDb documentation here.
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:
- Increase the global retry count value
- Delete the blacklist file manually (under
modules/.objects/tmdb_blacklist.ymlor/maker/modules/.objects/tmdb_blacklist.jsonon Docker) - User the fixer to un-blacklist a series
- 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.
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.
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:
- Filter out all images with widths less than the minimum width, or heights less than the minimum height
- If localized image rejection is enabled, filter out images with a language set
- Select the image(s) with the largest pixel count
- If multiple images have the same pixel count, select the image(s) with the highest user rating score
- If multiple images have the same pixel count and user rating, select the first image in this list (as returned by TMDb)
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.
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, jaAny of the following language codes are supported: ar, ar-AE, ar-SA, bg, ca, cn-CN, cs, da, de-AT, de-CH, de-DE, el, en, es-ES, es-MX, fa, fi, fr-CA, fr-FR, he, hi, hu, id, it-IT, it-CH, ja, ka, ko, lb, lt, lv, my, nb-NO, nl-BE, nl-NL, nn-NO, ms-BN, ms-MY, ms-SG, no, pl, pt-BR, pt-PT, ro, ru, sk, sr-RS, sv-FI, sv-SE, th, tr, uk, uz-UZ, vi, zh, zh-CN, zh-HK, or zh-SG.