How to Add Posters and Metadata to Your IPTV Library with TMDB
TMDB enrichment upgrades your IPTV Movies and Series from a file dump to a catalog with posters, cast, ratings, and backdrops. Here's how to turn it on.
Responsible Use
Use GridStreamr only with content sources, playlists, metadata services, subtitle services, and AI providers you are authorized to use. You are responsible for complying with applicable terms, licenses, and local law.
Raw IPTV Movies and Series libraries can be hard to browse: thousands of titles, placeholder thumbnails, and missing synopses. TMDB enrichment solves this by looking up every title in The Movie Database and pulling posters, backdrops, cast, ratings, release year, and plot summaries, turning your library into something far easier to browse.
What TMDB is
The Movie Database (TMDB) is a community-maintained catalog of movies, series, and people, with an open API. It backs Plex, Jellyfin, Trakt, and most of the self-hosted media ecosystem. Free accounts get a generous API quota that is more than enough for a home IPTV library.
How GridStreamr uses TMDB
Once enabled, GridStreamr matches each Movie and Series in your library to a TMDB entry by title and year, falls back to fuzzy matching when the source metadata is messy, and caches the enriched metadata locally so the UI stays fast. You get movie grids with proper posters, series pages with season and episode lists, and a richer detail page per title.
Step 1: Create a free TMDB account
- Open themoviedb.org and sign up for a free account.
- Verify your email.
- Under Settings → API, request an API key (v3 auth). Pick 'Personal' and describe the use as 'Enriching a personal IPTV library'.
- Copy the resulting API key (32 characters).
Step 2: Paste it into GridStreamr
Open GridStreamr → Settings → General → TMDB → paste the API key and press Save. The app validates the key against TMDB, and if valid it immediately queues every Movie and Series for enrichment. You'll see posters pop in over the next few minutes while the background job runs.
What gets enriched
- Poster and backdrop images.
- Plot synopsis, runtime, and release year.
- Cast and crew lists with character names.
- User ratings and content genres.
- Season and episode structure for series, with per-episode stills.
Privacy and quota
The TMDB key stays on your device. TMDB sees metadata requests such as title and year so it can return matches, but GridStreamr does not provide TMDB keys for you. Typical personal libraries stay well within TMDB's free quota.
What to try next
With TMDB flowing, add AI Live Channels Enrichment (Premium, hosted AI with in-app credit packs on current versions) to standardize channel names in Smart Collections, detect language and stream quality, classify content type, and discover missing logos. Combined, TMDB and AI enrichment turn a raw playlist library into a more polished, searchable experience across your devices. See the AI enrichment article on this blog for how credits work.
Keep reading
How to Clean Up Messy IPTV Channel Names with AI Enrichment
How GridStreamr uses hosted AI to clean up live channel names, detect quality and content type, find logos, and what Premium and in-app AI credits mean in 2026.
How to Catch Up on Live TV with TimeShift in GridStreamr
TimeShift lets you browse and watch past live TV programmes, no recording needed. Here's how it works in GridStreamr and what your provider needs to support.
GridStreamr: The IPTV Control Plane for Perfect Playlists in Any App
GridStreamr is the IPTV control plane for enthusiasts: curate Smart Collections once, then open them in TiviMate, IPTV Smarters Pro, IBO Player, Kodi, or VLC via Xtream or M3U share links—and in Jellyfin or Plex via M3U (home-server setup).