feat(website): add the TMDB metadata guide with the required attribution

New guide at /blog/tmdb-metadata-guide/: a sent/not-sent table for the
opt-in enrichment (title, year, app language and the build's API key leave
the machine; nothing about the user, the provider or the playlist does),
how to switch it on, when to use your own free key, what the feature
unlocks, and what the local cache holds. Eight FAQ entries, and a section
for readers who would rather leave it off.

The post states plainly that TMDB is a metadata database and not a content
source, and carries TMDB's required attribution through a reusable
TmdbAttribution component (their logo plus "This product uses the TMDB API
but is not endorsed or certified by TMDB."), the same wording the app shows
in Settings and About.

Its screenshot is the settings section itself: the capture's G5 guard keeps
enrichment disabled for the whole run, so no licensed poster or still can
reach a published frame. The new action stages the switch in the form only,
which reveals the key field, the cache panel and the attribution while the
stored setting stays off.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

apps/website/public/llms.txt

@@ -22,6 +22,7 @@
 - Guide, alternative sources for a movie across your own playlists (desktop): https://4gray.github.io/iptvnator/blog/alternative-sources-guide/
 - Guide, phone remote control setup (desktop): https://4gray.github.io/iptvnator/blog/remote-control-guide/
 - Troubleshooting, EPG shows the wrong program or nothing (channel mapping, time offset): https://4gray.github.io/iptvnator/blog/epg-wrong-program-fix/
+- Guide, optional TMDB metadata enrichment (what is sent, API key, cache): https://4gray.github.io/iptvnator/blog/tmdb-metadata-guide/
 - Features overview: https://4gray.github.io/iptvnator/features/
 - Feature, M3U playlist player: https://4gray.github.io/iptvnator/features/m3u-player/
 - Feature, Xtream Codes player: https://4gray.github.io/iptvnator/features/xtream-codes-player/

apps/website/public/tmdb-logo.svg

@@ -0,0 +1,11 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 273.42 35.52" role="img" aria-label="The Movie Database (TMDB)">
+  <defs>
+    <linearGradient id="tmdbGradient" x1="0" y1="0" x2="273.42" y2="0" gradientUnits="userSpaceOnUse">
+      <stop offset="0" stop-color="#90cea1"/>
+      <stop offset="0.56" stop-color="#3cbec9"/>
+      <stop offset="1" stop-color="#00b3e5"/>
+    </linearGradient>
+  </defs>
+  <rect width="273.42" height="35.52" rx="17.76" fill="url(#tmdbGradient)"/>
+  <text x="136.71" y="24.4" text-anchor="middle" font-family="'Source Sans Pro', 'Helvetica Neue', Arial, sans-serif" font-size="19" font-weight="700" letter-spacing="1.5" fill="#0d253f">THE MOVIE DB</text>
+</svg>

apps/website/src/components/blog/TmdbAttribution.astro

@@ -0,0 +1,14 @@
+---
+/**
+ * The attribution TMDB's terms require from products that use their API. The
+ * app shows it in Settings › Metadata and in About; a page that documents the
+ * integration carries it too. Logo and wording are used as TMDB supplies them.
+ */
+---
+
+<div class="not-prose my-8 flex flex-col gap-3 rounded-xl border border-surface-800 bg-surface-900/40 p-5 sm:flex-row sm:items-center sm:gap-5">
+  <img src="/iptvnator/tmdb-logo.svg" alt="The Movie Database" width="140" height="18" class="h-[18px] w-auto shrink-0" />
+  <p class="m-0 text-sm leading-relaxed text-surface-400">
+    This product uses the TMDB API but is not endorsed or certified by TMDB.
+  </p>
+</div>

apps/website/src/content/blog/tmdb-metadata-guide.mdx

@@ -0,0 +1,157 @@
+---
+title: Posters, Cast and Trailers for Your IPTV Library - The TMDB Option in IPTVnator
+description: IPTVnator can fill in plots, cast, artwork and trailers for the movies and series in your own playlists using The Movie Database. What it sends, what stays on your device, how to switch it on, and how to use your own API key.
+pubDate: 2026-09-08
+author: 4gray
+heroImage: /iptvnator/blog/guides/screenshots/guide-tmdb-settings-dark.png
+tags:
+    - guide
+    - troubleshooting
+draft: false
+faq:
+- q: What exactly is sent to TMDB?
+  a: The title of the movie or series you opened, its year when the provider states one, and your app language. Nothing that identifies you, your provider, your playlist or your account is sent. There is no login, no telemetry and no analytics in IPTVnator.
+- q: Is it on by default?
+  a: No. Metadata enrichment is off until you switch it on in Settings under Metadata (TMDB), precisely because it sends titles to a third party. With it off, IPTVnator only shows what your own provider delivers.
+- q: Does IPTVnator get content from TMDB?
+  a: No. TMDB is a metadata database, not a content source. It supplies text and images that describe a title. Streams come only from the playlists and portals you added yourself, and nothing in this feature makes a title playable that your subscription does not already carry.
+- q: Do I need my own API key?
+  a: No, official builds ship with a key. You can enter your own free key from themoviedb.org in the settings if you prefer, and builds you compile yourself need one because the key is not stored in the public repository.
+- q: Where is the downloaded metadata stored?
+  a: In the local database of the desktop app, so a detail page you opened once loads instantly later. The settings show how many entries and how much space it uses, with a button to clear it. The browser version keeps it only for the session.
+- q: Why does a movie show the wrong plot or poster?
+  a: The match went to a different title with a similar name. IPTVnator uses the provider's TMDB id when it agrees with the title or the year, otherwise it searches by normalized title and year and refuses to guess when nothing matches confidently. Clearing the cache in the settings makes it look again.
+- q: Does this work in the browser version?
+  a: The enrichment itself does, but its cache lasts only for the session, and the features that read the local catalog, the cross-playlist Similar rail and the All portals scope on actor pages, are desktop only.
+- q: Can I use it without sending anything anywhere?
+  a: Yes, by leaving it off. Every provider-supplied plot, poster and description keeps working; you only lose the extra fields TMDB would have filled in.
+---
+
+import Alert from '../../components/blog/Alert.astro';
+import ContentDisclaimer from '../../components/blog/ContentDisclaimer.astro';
+import TmdbAttribution from '../../components/blog/TmdbAttribution.astro';
+import PostButton from '../../components/blog/PostButton.astro';
+import StepRail from '../../components/blog/StepRail.astro';
+import LinkCards from '../../components/blog/LinkCards.astro';
+
+Provider catalogs are uneven. One movie arrives with a plot, a poster and a year; the next is a
+bare filename in a list of four thousand. IPTVnator can close that gap with
+[The Movie Database](https://www.themoviedb.org/), a community-maintained film and TV database,
+and fill in what your provider left empty: the plot, the cast with photos, the director, genres,
+the rating, better artwork and a trailer.
+
+The feature is off until you turn it on, because it sends titles to a service outside your
+machine. This guide covers what it sends, what it does not, how to switch it on, and what the
+extra features it unlocks are good for.
+
+<ContentDisclaimer />
+
+## What leaves your machine, and what does not
+
+When enrichment is on and you open a movie or a series, IPTVnator asks TMDB about that one
+title. The request carries:
+
+| Sent | Not sent |
+| --- | --- |
+| The title of the item you opened | Your provider, its address or your credentials |
+| Its year, when the provider states one | Your playlist, its channels or its file |
+| Your app language, so texts come back translated | Any identifier of you or your device |
+| The API key of the build, or the one you entered | Anything about what you watch or for how long |
+
+IPTVnator has no account system, no telemetry and no analytics. It does not report your
+library, and it never uploads a playlist anywhere. TMDB sees a stream of title lookups from an
+API key, the same as any other application using their API.
+
+<Alert type="info" title="TMDB is a description, not a source">
+  The Movie Database holds information about films and shows: text, artwork, credits, trailer
+  links. It holds no streams. Nothing in this feature adds content to your library or makes a
+  title playable that your own subscription does not already carry.
+</Alert>
+
+## Switch it on
+
+<StepRail
+  title="In the desktop app"
+  steps={[
+    'Open Settings and choose Metadata in the sidebar.',
+    'Switch "Enable TMDB metadata" on. The API key field, the cache panel and the attribution appear below it.',
+    'Leave the key field empty to use the key the official builds ship with, or paste your own free key from themoviedb.org.',
+    'Save. Open any movie: the provider data shows immediately, and the TMDB fields fill in a moment later.',
+  ]}
+/>
+
+![Settings with TMDB metadata enabled, showing the API key field, the cache panel and the TMDB attribution](/iptvnator/blog/guides/screenshots/guide-tmdb-settings-dark.png)
+
+Enrichment never blocks the page. The detail view renders what the provider gave, and the extra
+fields appear when TMDB answers. If TMDB is unreachable or the title cannot be matched, the page
+simply stays as the provider delivered it.
+
+### Your own API key
+
+Keys are free: create an account on themoviedb.org and request an API key in the account
+settings. Two reasons to use your own:
+
+- **You build IPTVnator yourself.** The key of the official builds is injected during the
+  release build and is not in the public repository, so a self-compiled app has no key until you
+  enter one.
+- **You would rather have your own quota.** Requests then count against your key instead of the
+  shared one.
+
+The **Check key** button in the settings asks TMDB whether the key is valid and tells you either
+way.
+
+## What it unlocks
+
+- **Fuller detail pages.** Plot, genres, rating, runtime, director, cast with photos, better
+  artwork, and a trailer where TMDB has one.
+- **Real episode titles.** Opening a season fetches its episode names, descriptions and stills,
+  which turns "Episode 4" into something you can choose from.
+- **Similar titles.** A rail on the detail page matching TMDB's recommendations against your own
+  catalog, so it only offers what you can actually play. On the desktop app it looks across all
+  your Xtream playlists, not only the current one.
+- **Actor and director pages.** Cast and director names become links: a short biography and the
+  filmography, with the titles you own linked directly.
+- **Browse by year, genre or country.** Metadata chips on a detail page become clickable and
+  open a Discover page, again matched against your catalog.
+- **Dashboard rails.** Optional "Trending this week" and "Recommended for you" rails, both
+  matched against your libraries so nothing is offered that you cannot open.
+- **Movie recognition in M3U playlists.** A playlist entry that looks like a movie file opens in
+  the movie detail view instead of the live layout. This one has its own toggle under the main
+  switch.
+
+## The local cache
+
+Every answer is stored in the local database, so a page you opened once is instant afterwards
+and TMDB is not asked again. The settings show the number of entries and their size, with a
+**Clear cache** button.
+
+Clear it when a title matched the wrong entry, or when you switched app language and want texts
+refetched in the new one. Clearing removes only downloaded descriptions and artwork; your
+playlists, favorites and history are untouched.
+
+<Alert type="warning" title="When the match is wrong">
+  A provider's own TMDB id is trusted only when the title or the year agrees with it; otherwise
+  IPTVnator searches by title and year and gives up rather than attaching a confident-looking
+  wrong result. If a film still shows the wrong plot, clearing the cache makes it look again.
+</Alert>
+
+## If you would rather not
+
+Leave the switch off. Every plot, poster and description your provider sends keeps working
+exactly as before; you only lose the fields TMDB would have added. The setting is a single
+toggle, so you can also turn it on for an evening of browsing and off again afterwards. Turning
+it off stops all lookups; clearing the cache also removes what was already downloaded.
+
+<TmdbAttribution />
+
+## Related
+
+<LinkCards
+  links={[
+    { label: 'Add an Xtream Codes account', href: '/iptvnator/blog/xtream-codes-setup-guide/', hint: 'The source whose movie and series catalog the metadata describes.', icon: 'docs' },
+    { label: 'Load an M3U playlist and add an EPG', href: '/iptvnator/blog/m3u-playlist-epg-setup-guide/', hint: 'Where movie recognition turns playlist entries into detail pages.', icon: 'docs' },
+    { label: 'Download IPTVnator', href: '/iptvnator/download/', hint: 'The desktop app, where the cache and the cross-playlist features live.', icon: 'download' },
+  ]}
+/>
+
+<PostButton href="/iptvnator/download/" label="Get IPTVnator for your platform" external={false} />

tools/release/capture-navigation-setup-actions.ts

@@ -260,6 +260,39 @@ async function waitForRemoteControlServer(): Promise<void> {
     );
 }
 
+/**
+ * Settings › Metadata (TMDB) with the switch staged ON, which is what reveals
+ * the API-key field, the cache panel and the required TMDB attribution. The
+ * value is never saved: enrichment must stay off for the whole capture (G5),
+ * and `discardUnsavedSettings` drops the form before the next action.
+ */
+async function openSettingsTmdb(page: Page): Promise<void> {
+    await openSettings(page);
+    const sectionLink = page
+        .locator('[data-test-id="settings-section-tmdb"]')
+        .first();
+
+    await sectionLink.waitFor({ state: 'visible', timeout: 15_000 });
+    await sectionLink.click({ timeout: 10_000 });
+    await page.waitForURL(/\/workspace\/settings\/tmdb/, { timeout: 15_000 });
+
+    const section = page.locator('#tmdb');
+    await section.waitFor({ state: 'visible', timeout: 15_000 });
+
+    const toggle = section.locator(
+        '[data-test-id="tmdb-enabled"] input[type="checkbox"]'
+    );
+
+    if (!(await toggle.isChecked())) {
+        await section.locator('[data-test-id="tmdb-enabled"]').click();
+    }
+
+    await section
+        .locator('[data-test-id="tmdb-api-key"]')
+        .waitFor({ state: 'visible', timeout: 10_000 });
+    await page.waitForTimeout(500);
+}
+
 export const SETUP_ACTIONS: Readonly<Record<string, CaptureAction>> = {
     'open-settings': openSettings,
     'open-dashboard': openDashboard,
@@ -268,6 +301,7 @@ export const SETUP_ACTIONS: Readonly<Record<string, CaptureAction>> = {
     'open-add-playlist-stalker': openAddPlaylistStalker,
     'open-add-playlist-m3u-url': openAddPlaylistM3uUrl,
     'open-settings-epg': openSettingsEpg,
+    'open-settings-tmdb': openSettingsTmdb,
     'open-settings-remote-control': openSettingsRemoteControl,
     'enable-remote-control': enableRemoteControl,
 };

tools/release/screenshot-guards.mjs

@@ -63,6 +63,7 @@ export const KNOWN_ACTIONS = [
     'load-demo-epg',
     'open-m3u-channel-menu',
     'open-epg-mapping-dialog',
+    'open-settings-tmdb',
 ];
 
 /**

tools/release/screenshots.manifest.json

@@ -195,6 +195,14 @@
             "setup": [
                 "open-settings-epg-offset"
             ]
+        },
+        {
+            "slug": "guide-tmdb-settings",
+            "title": "Settings: Metadata (TMDB)",
+            "group": "guides",
+            "setup": [
+                "open-settings-tmdb"
+            ]
         }
     ]
 }

tools/testing/website-guides.test.mjs

@@ -65,6 +65,10 @@ const GUIDES = [
       'blog/guides/screenshots/guide-epg-offset-dark.png',
     ],
   },
+  {
+    slug: 'tmdb-metadata-guide',
+    screenshots: ['blog/guides/screenshots/guide-tmdb-settings-dark.png'],
+  },
 ];
 
 const readDist = (relativePath) => readFile(new URL(relativePath, distRoot), 'utf8');