From 87ca76fbcf2027c080141adac9e04d6f0925bda7 Mon Sep 17 00:00:00 2001 From: 4gray Date: Mon, 6 Jul 2026 20:32:53 +0200 Subject: [PATCH] docs(website): add TMDB metadata setup & features guide (draft) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit A tutorial blog post covering: getting a free TMDB API key, enabling it in Settings → Metadata (TMDB), and every feature it unlocks — enriched movie/series pages, trailers, cast & actor pages, in-library actor matching, season/episode details, the cross-portal Similar rail, and the dashboard Trending rail + hero enrichment. Also covers the language fallback, privacy/opt-in, desktop-vs-PWA differences, and TMDB attribution. Marked draft: true — image placeholders under /iptvnator/blog/tmdb/ to be filled with screenshots before publishing. Co-Authored-By: Claude Fable 5 --- .../src/content/blog/tmdb-metadata-guide.mdx | 199 ++++++++++++++++++ 1 file changed, 199 insertions(+) create mode 100644 apps/website/src/content/blog/tmdb-metadata-guide.mdx diff --git a/apps/website/src/content/blog/tmdb-metadata-guide.mdx b/apps/website/src/content/blog/tmdb-metadata-guide.mdx new file mode 100644 index 000000000..290dc0cbd --- /dev/null +++ b/apps/website/src/content/blog/tmdb-metadata-guide.mdx @@ -0,0 +1,199 @@ +--- +title: 'Richer Movies & Series: Set Up TMDB Metadata in IPTVnator' +description: How to get a free TMDB API key, where to paste it in IPTVnator, and every feature it unlocks — posters, cast and clickable actor pages, trailers, episode details, similar recommendations, and a Trending rail on your dashboard. +pubDate: 2026-07-06 +author: 4gray +featured: true +heroImage: /iptvnator/blog/tmdb/hero.jpg +tags: + - tutorial + - tmdb + - metadata +draft: true +--- + +import Alert from '../../components/blog/Alert.astro'; +import StepRail from '../../components/blog/StepRail.astro'; +import IconFeatureGrid from '../../components/blog/IconFeatureGrid.astro'; +import ImageGallery from '../../components/blog/ImageGallery.astro'; +import PostButton from '../../components/blog/PostButton.astro'; +import LinkCards from '../../components/blog/LinkCards.astro'; + +Most IPTV providers hand you a stream URL and a title — and not much else. A movie shows up as a bare filename, a series is a wall of episodes with no descriptions, and you have no idea whether the thing you're about to watch is worth two hours of your evening. + +IPTVnator can fix that. With a free **TMDB** (The Movie Database) key, your Xtream and Stalker libraries get real posters, plots, cast, trailers, ratings, episode details, "similar" recommendations, clickable actor pages, and a personalized **Trending this week** rail on the dashboard — all layered on top of the data your provider already gives you. + +It's **opt-in**, takes about two minutes to set up, and this guide walks through every step. + +## What you get + + + + + You only need a free themoviedb.org account and one API key. Everything below is a one-time setup — after that, IPTVnator does the work quietly in the background and caches results so pages stay fast. + + +## Step 1 — Get a free TMDB API key + +TMDB is a community movie & TV database with a free API. Getting a key is quick: + + + + + + + IPTVnator accepts both the classic **API Key (v3 auth)** and the newer **API Read Access Token (v4)**. If you see both on the page, the shorter v3 key is the simplest choice. + + +## Step 2 — Turn it on in IPTVnator + + + + + + + The field is labelled optional, but on public builds you should add your own key — it's free, it's yours, and it means enrichment keeps working no matter what. Your key stays on your device. + + +That's it. Open any movie or series and enrichment starts filling in the details. + +## Now explore what it unlocks + +### Movie & series pages + +Detail pages render your provider's data instantly, then TMDB patches in the rest: a proper **plot**, **poster** and wide **backdrop**, **genres**, a **rating** badge, **director** and **cast**. Your provider stays the source of truth for anything it already supplies — TMDB only fills the gaps. + + + + + Metadata is fetched in your app language. TMDB doesn't translate everything, so for a title that only has text in its original language (say, a Russian film viewed in English), IPTVnator quietly refetches the plot — and the trailer — in the original language and fills only what was missing. No more empty descriptions just because you're not using the app in the film's language. + + +### Trailers + +When TMDB has one, the **YouTube trailer** appears right on the detail page — no need to leave the app. + +![A YouTube trailer embedded on a movie page](/iptvnator/blog/tmdb/trailer.jpg) + +### Cast & actor pages + +The cast list becomes a row of **photo chips**. Click any actor to open a dedicated page with their **photo, bio and full filmography** — pulled straight from TMDB. + + + +### Find an actor's films in your library + +Here's the part that ties it all together. On an actor's filmography, titles you **already have** in your library are marked available and open straight to their detail page. The rest open a search so you can look for them. + +On desktop you can even flip the scope to **All portals** — IPTVnator matches the actor's filmography against every Xtream library you've imported, so you can see which of their films are available anywhere in your setup, and jump right in. + + + + + When a filmography title opens the portal search, that search page now has a **Back** button, so you can return to the actor page in one click instead of navigating from scratch. + + +### Seasons & episodes + +Open a season and IPTVnator lazily fetches its episode list from TMDB, overlaying **real episode names, overviews and still images** onto your provider's episodes. If the season description or names are missing in your language, the same original-language fallback kicks in. + +![Season episodes enriched with names, overviews and stills](/iptvnator/blog/tmdb/episodes.jpg) + +### "Similar" recommendations + +Every detail page can show a **Similar** rail built from TMDB recommendations — but filtered to titles you can actually watch. On Xtream it matches against your loaded catalog; on desktop it also matches against your **other imported portals**, so a recommendation available in a different library shows up with that library's name. Stalker pages, whose catalogs can't be searched locally, get their Similar rail entirely from these cross-portal matches. + +![A Similar recommendations rail on a detail page](/iptvnator/blog/tmdb/similar-rail.jpg) + +### Trending this week — on your dashboard + +The dashboard gains an opt-in **Trending this week** rail: TMDB's weekly trending movies and series, matched against your imported Xtream libraries. Titles you own open straight to their detail page (with the library name shown); the rest open a search. The dashboard hero also picks up a **backdrop**, **rating** and **genre** badges when available, plus a season/episode badge for series you're mid-watch on. + + + + + The Trending rail is a normal dashboard rail — toggle it (and any other rail) on or off in Settings → Dashboard. It only loads when TMDB is enabled. + + +## Fast by design + +The dashboard and detail pages always render your provider's data **first**, then enrichment patches in the extras a moment later. Nothing new blocks the first paint. Results are cached — on desktop in a local database, in the browser in memory — so revisiting a page or reopening the app doesn't re-fetch. Trending is cached for a day; details for a month. + +## Privacy & matching + + + Enrichment is off until you turn it on. When enabled, IPTVnator sends **movie and series titles** (and TMDB IDs when your provider supplies them) to TMDB to look up metadata — nothing else. Matching is conservative: a title is only enriched when there's a confident match on normalized title and year, so you won't get the wrong film's poster. + + +## Desktop vs. browser + +Core enrichment — plots, posters, cast, actor pages, trailers, episodes, and the in-catalog Similar rail — works in **both** the desktop app and the PWA. A few features rely on the desktop app's local database for cross-library matching and are **desktop-only**: the Trending rail, cross-portal Similar matches, the actor "All portals" scope, and global search. + +## A note on TMDB + +This product uses the TMDB API but is not endorsed or certified by TMDB. All the movie and TV metadata, artwork and trailers come from [The Movie Database](https://www.themoviedb.org/) — a huge, community-maintained resource. If you enjoy it, consider contributing data or artwork back to TMDB. + +--- + +That's the whole feature set in one place. Turn it on, add your key, and your libraries stop looking like a list of filenames and start looking like a proper media collection. + +