TMDB Ratings and Metadata

TMDB Ratings & Metadata

TMDB integration adds a gold-star rating (e.g. ★ 7.6) to movie programmes in the guide, and richer poster/synopsis/rating/director overlays for on-demand video — off by default, since it needs your own free API token.

Getting a token

Create a TMDB account, then under Settings → API request an API key (any use-case description is fine) and copy the API Read Access Token — the long JWT-looking string, not the shorter "API Key". That's the value --tmdb-api-token wants.

What it adds

• Guide ratings — --tmdb-api-token adds a rating to movie programmes in the guide grid and details popup, matched by title/year against the programme's category. Fetched in background threads (never blocking guide rendering) and cached on disk for 30 days. The TMDB attribution mark shown alongside every rating is required by TMDB's API terms.
• Director — the i overlay (compact banner, guide details popup, and the VOD info overlay) shows a movie's director when available. Some EPG feeds already tag this themselves (XMLTV's <credits><director>) — that's used directly, for free, with no token needed at all. Only when a feed doesn't provide one does --tmdb-api-token fall back to a TMDB lookup, and unlike the rating above, that fallback isn't bulk-fetched for the whole guide grid — only for whatever's currently shown in an i overlay, so a fresh view sometimes shows no director yet; reopening it picks it up once fetched.
• Local files & YouTube — a local video file or YouTube video gets its full poster/synopsis/rating/ director from a TMDB lookup against its guessed/oEmbed title, the same as any other VOD item's i overlay. See each page for exactly how the title guess/search works.

Plex never needs a TMDB token for its own metadata — it already has all of that from Plex's own library data.

Saving a token

Retyping --tmdb-api-token on every invocation gets old fast. Two ways to save one instead, checked in this order:

1. Per bookmark — like the Xtream/Stalker/Plex credentials, stored as plain text in bookmarks.json, but fully masked (not just redacted) in the log file. Launching that bookmark applies its token the same as typing --tmdb-api-token directly.
2. A global default — tvdinner store-tmdb TOKEN applies to every invocation that doesn't otherwise specify one, stored as plain text in ~/.config/tvdinner/tmdb_token.json (%APPDATA%\tvdinner\tmdb_token.json on Windows; override with --tmdb-token-file). tvdinner clear-tmdb removes it.

An explicit --tmdb-api-token (typed directly, or carried by a launched bookmark) always overrides the global default.

Clearing a bad cache entry

If a cached rating/metadata entry ever looks wrong (a mismatched title, say):

• --no-tmdb-cache — always query TMDB fresh, and don't write a cache either.
• --refresh-tmdb-cache — force one fresh lookup now for whatever's fetched this run, then resume normal caching after that.

Everything else

• Keybindings Reference — i is the key that shows all of this.