Skip to content
Blockbusterr

TMDB Integration

import { Aside } from ‘@astrojs/starlight/components’;

TMDB (The Movie Database) integration provides high-quality poster images for the job preview feature. The TMDB API key is completely optional - without it, you’ll see a clean list view instead.

Display Modes

Section titled “Display Modes”

Without TMDB (List View)

Section titled “Without TMDB (List View)”

When no TMDB API key is configured, the preview shows a simple, clean list with:

  • Title, year, and rating
  • Popularity metrics
  • Genre information
  • Status badges (NEW/EXISTS/FILTERED)

With TMDB (Poster Grid View)

Section titled “With TMDB (Poster Grid View)”

When TMDB is configured, you get beautiful poster images:

  • High-quality movie and TV show posters (500px width)
  • Visual grid layout
  • Hover effects and details
  • Automatic fallback to styled placeholders if a poster is unavailable

Getting a TMDB API Key

Section titled “Getting a TMDB API Key”

Step 1: Create a TMDB Account

Section titled “Step 1: Create a TMDB Account”
  1. Go to themoviedb.org/signup
  2. Sign up for a free account
  3. Verify your email address

Step 2: Request an API Key

Section titled “Step 2: Request an API Key”
  1. Once logged in, go to themoviedb.org/settings/api
  2. Click “Request an API Key”
  3. Select “Developer” when asked for the type of API key
  4. Fill out the application form:
    • Application Name: Blockbusterr (or your preferred name)
    • Application URL: Can use http://localhost:9090 or your deployment URL
    • Application Summary: Brief description (e.g., “Personal media automation tool”)
  5. Accept the terms and submit

Step 3: Copy Your API Key

Section titled “Step 3: Copy Your API Key”
  1. Once approved, you’ll receive an API Key (v3 auth)
  2. Copy this key - you’ll need it for configuration

Step 4: Add to Configuration

Section titled “Step 4: Add to Configuration”

Add the API key to your Blockbusterr configuration:

Via Configuration File:

Edit config/config.yaml:

tmdb:
  api_key: "your_api_key_here"

Via Web UI:

  1. Open http://localhost:9090
  2. Go to Configuration tab
  3. Find the TMDB section
  4. Paste your API key
  5. Click Save

Via Environment Variable:

Terminal window
TMDB_API_KEY=your_api_key_here

Step 5: Restart Blockbusterr

Section titled “Step 5: Restart Blockbusterr”

Restart the application to apply the changes:

Terminal window
docker restart blockbusterr

Verifying TMDB Integration

Section titled “Verifying TMDB Integration”

Test the Preview

Section titled “Test the Preview”
  1. Go to the Jobs tab
  2. Click Preview on any job
  3. If configured correctly, you’ll see poster images
  4. If not configured, you’ll see a clean list view (both work fine!)

Check Logs

Section titled “Check Logs”

Look for TMDB initialization messages:

Terminal window
docker logs blockbusterr | grep -i tmdb

You should see:

INFO TMDB API key configured - poster images enabled

Features

Section titled “Features”

With TMDB integration enabled:

  • High-Quality Posters: 500px width images from TMDB
  • Visual Grid: Clean poster grid layout with hover effects
  • Automatic Caching: Poster URLs cached for faster loading
  • Graceful Fallback: Styled placeholders if poster unavailable
  • No Performance Impact: Fetched asynchronously, doesn’t slow down jobs

Troubleshooting

Section titled “Troubleshooting”

Posters Not Loading?

Section titled “Posters Not Loading?”

Check API Key:

  • Verify it’s correctly entered in configuration
  • Ensure no extra spaces or quotes
  • Try copying the key again from TMDB

Check Network Access:

Terminal window
docker exec blockbusterr curl -s "https://api.themoviedb.org/3/configuration?api_key=YOUR_KEY"

Should return JSON configuration data.

Check Logs:

Terminal window
docker logs blockbusterr | grep -i tmdb

Look for error messages like:

  • “Invalid API key”
  • “TMDB API request failed”
  • “Rate limit exceeded”

Rate Limiting

Section titled “Rate Limiting”

TMDB has rate limits:

  • 40 requests per 10 seconds
  • 1000 requests per day (for free accounts)

Blockbusterr respects these limits and caches aggressively to minimize API calls.

If you hit rate limits:

  • Reduce preview frequency
  • Consider upgrading to TMDB paid tier (not usually necessary)

Prefer List View?

Section titled “Prefer List View?”

If you prefer the list view over posters:

  1. Remove the API key from configuration
  2. Or set it to an empty string:
tmdb:
  api_key: ""

The application automatically switches to list view mode when TMDB is not configured.

Configuration Options

Section titled “Configuration Options”
tmdb:
  api_key: "your_api_key_here"  # TMDB API key (optional)

Privacy & Data

Section titled “Privacy & Data”

What Data is Sent?

Section titled “What Data is Sent?”

When TMDB is configured, Blockbusterr sends:

  • TMDB IDs (for movies)
  • TVDB IDs (for TV shows)
  • Your API key (authentication)

What Data is Received?

Section titled “What Data is Received?”

Blockbusterr receives:

  • Poster image URLs
  • Backdrop image URLs (not currently used)

Data Storage

Section titled “Data Storage”
  • Poster URLs are cached in the local database
  • No personal data is sent to TMDB
  • TMDB cannot see what you’re adding to your library

Alternative: No TMDB

Section titled “Alternative: No TMDB”

You don’t need TMDB to use Blockbusterr. The list view provides all the same functionality:

List View Includes:

  • ✅ Title and year
  • ✅ Rating and votes
  • ✅ Popularity metrics
  • ✅ Genres
  • ✅ Runtime
  • ✅ Overview/description
  • ✅ Status badges (Will Add / Exists / Filtered)
  • ✅ Filter reasons

The only difference is visual - no poster images.

TMDB API Documentation

Section titled “TMDB API Documentation”

For more information about TMDB API:

Next Steps

Section titled “Next Steps”