Pull poster art, ratings, cast, episode details, and trailers from The Movie Database. Your ɳTV library gets rich metadata automatically — no manual data entry.
Requires a free TMDB API key. Get one at themoviedb.org/settings/api.
nself license set nself_pro_...
nself plugin install tmdb
nself build
nself startnself-tmdb connects to The Movie Database API to enrich your ɳTV media library with structured metadata. When nself-file-processing ingests a new media file, it calls this plugin to match the filename against TMDB and fetch the full record: poster, backdrop, synopsis, genres, ratings, release year, cast, and crew.
TV episode files are matched by series name + season/episode number using standard naming conventions (S01E03, 1x03, etc.). Season artwork and episode thumbnails are fetched and cached in object storage. The nself-epg integration uses TMDB IDs from EPG program data to attach poster art to the channel guide automatically.
Metadata is cached in Postgres to reduce API calls. A background refresh job updates stale entries (older than 7 days by default) and fetches newly added content metadata during off-peak hours.
| Variable | Required | Description |
|---|---|---|
DATABASE_URL | Yes | Postgres connection string (auto-set by nself) |
TMDB_API_KEY | Yes | TMDB v3 API key (free tier is sufficient) |
TMDB_LANGUAGE | No | Metadata language code. Default: en-US |
TMDB_IMAGE_BUCKET | No | Object storage bucket to cache poster/backdrop images. Defaults to media bucket |
TMDB_CACHE_REFRESH_DAYS | No | Days before re-fetching cached metadata. Default: 7 |
| Endpoint | Method | Description |
|---|---|---|
/tmdb/search | GET | Search TMDB by title. Returns ranked matches with TMDB IDs |
/tmdb/movie/:id | GET | Full movie metadata by TMDB ID (cached) |
/tmdb/tv/:id | GET | TV series metadata including seasons and episode list |
/tmdb/tv/:id/season/:n/episode/:e | GET | Episode-level metadata with thumbnail URL |
/tmdb/enrich/:media_id | POST | Force-enrich a media file in the ɳTV library with TMDB data |
/health | GET | Plugin health and TMDB API connectivity |
| Table | Purpose |
|---|---|
np_tmdb_movies | Cached movie metadata keyed by TMDB ID |
np_tmdb_series | Cached TV series metadata with season structure |
np_tmdb_episodes | Episode-level data: title, synopsis, air date, thumbnail |
np_tmdb_images | Cached image paths in object storage (posters, backdrops, thumbnails) |
| Event | Payload |
|---|---|
tmdb.enriched | Media ID, TMDB ID, type (movie/tv), match confidence |
tmdb.match.failed | Media ID, title attempted, top TMDB candidates |
nself-tmdb runs automatically in the ɳTV ingest pipeline: nself-file-processing ingests → triggers TMDB match → nself-tmdb enriches → nself-streaming serves the enriched asset with metadata. You can also call /tmdb/enrich/:media_id manually for files that failed automatic matching.
Match not found: TMDB matching uses the filename without extension. Rename files to standard Plex/Kodi naming: Movie Title (2024).mkv or Show Name S01E03.mkv. Run GET /tmdb/search?q=title to preview what TMDB returns for a title.
API rate limit: The TMDB free tier allows 40 requests per 10 seconds. The plugin batches enrichment during off-peak hours. If you have a large initial library import, it will auto-pace.
Port: 3513 (moved from 3122) | Bundle: ɳTV ($0.99/mo) or ɳSelf+ ($3.99/mo) | Last Updated: May 2026 | Plugin Version 1.0.13