TMDB Enrichment for IPTV VOD — Posters, Cast and Metadata

Raw IPTV movie and series libraries often look like a file dump: placeholder thumbs, truncated titles, missing years, empty detail pages. TMDB enrichment connects GridStreamr Premium to The Movie Database using your own free API key, then matches titles so Smart Collections browse more like a real catalog — posters, cast, ratings and season structure included.

What TMDB is

The Movie Database (TMDB) is a community-maintained catalog of movies, series and people with an open API. It powers metadata in much of the self-hosted ecosystem — Plex, Jellyfin, Trakt and countless scripts. A free personal API key is enough for a household IPTV library when used within TMDB's terms and rate limits.

GridStreamr does not scrape random websites for artwork. It asks TMDB for matches, then caches enriched metadata so the UI stays fast on phones and Android TV.

How GridStreamr matches titles

Once your key validates:

1. GridStreamr queues movies and series in your library / Smart Collections for enrichment
2. Matching prefers title + year, then falls back to fuzzy matching when provider metadata is messy
3. Successful matches pull posters, backdrops, synopsis, cast, ratings and series structure
4. Progress is visible as enrichment jobs run — posters appear over the following minutes
5. Prefer a TMDB metadata language in Settings → General when you want non-English synopses

Auto-enrichment for unenriched titles (Premium + key) keeps new arrivals from sitting with blank art after a provider refresh.

Step 1: Create a free TMDB API key

1. Sign up at themoviedb.org and verify email
2. Open Settings → API and request a key (v3 auth)
3. Choose Personal and describe the use as enriching a personal media / IPTV library
4. Copy the 32-character API key

Keep the key private — treat it like any other API credential.

Step 2: Paste the key into GridStreamr

1. Open Settings → General → TMDB
2. Paste the key and save
3. GridStreamr validates against TMDB
4. On success, enrichment queues start for movies and series

Video: Setting up TMDB. Blog: TMDB enrichment walkthrough.

What fields get filled

Combined with Continue Watching sync, a TMDB-backed library feels closer to a streaming service UI — still powered by your Xtream or M3U sources.

Privacy and quota

• Typical personal libraries stay within TMDB's free personal quota
• TMDB receives lookup queries (titles, years) required to return matches
• GridStreamr does not issue keys and does not proxy enrichment as a public TMDB key farm
• Follow TMDB's API terms; commercial redistribution of their data is outside personal library use

If you hit rate limits on a huge first import, let jobs finish overnight and avoid hammering refresh.

TMDB vs AI live enrichment vs OpenSubtitles

These Premium polish layers solve different problems:

Use all three when you want live TV that looks curated and VOD that looks catalogued and dialogue you can read.

Free vs Premium

Tips for better match rates

• Prefer sources that include years in titles when possible
• After a messy import, fix the worst title strings in the Smart Collection before bulk enrichment
• Re-run enrichment after you rename a mislabeled movie
• Check language preference if synopses arrive in the wrong locale
• Remember: TMDB cannot invent a match for completely garbage filenames — cleanup first, enrich second

For live rows with UK| MOVIE BOX FHD-style chaos, run AI enrichment on channels; keep TMDB for true VOD catalog entries.

How TMDB fits Smart Collections

Smart Collections are where enrichment pays off:

• Merge movie categories from multiple Xtream accounts into one Movies collection
• Enrich once; browse the same posters on phone and Android TV
• Share a curated VOD slice via secure sharing — recipients still play your authorized streams through virtual credentials
• Pair with Jellyfin when some titles live on your NAS instead of the IPTV VOD panel

TMDB does not replace Jellyfin metadata for Jellyfin-native libraries; Jellyfin already carries its own artwork. TMDB shines for Xtream/M3U VOD that arrived thin.

After enrichment: browsing that actually works

Once posters land, change how you navigate VOD:

• Prefer grid views on tablets and Android TV — artwork carries recognition faster than text rows
• Use genres and ratings from TMDB to build "weekend watch" shortlists inside a Smart Collection
• Open detail pages for cast — useful when someone remembers an actor but not the title
• Rely on Continue Watching sync so a movie started on the commute finishes on the sofa with the same metadata everywhere

If a title still shows a blank or wrong poster, check whether the provider string is too corrupted for a match. Rename toward the canonical title + year, then re-queue enrichment for that item.

Common match failures and fixes

Enrichment quality tracks title hygiene. Five minutes of renaming beats twenty minutes of wondering why TMDB "is broken."

Getting started

1. Confirm Premium (or start the trial)
2. Create a TMDB personal API key
3. Paste it under Settings → General → TMDB
4. Open a Movies Smart Collection and wait for posters to populate
5. Set TMDB language if you need localized text

Related reading

• TMDB blog guide
• AI IPTV enrichment
• OpenSubtitles / subtitles
• Smart Collections
• IPTV player
• Pricing