Skip to main content

TMDb

Create and sync Plex collections from any public TMDb list. TMDb lists are a popular way to organize movies and TV shows, and homescreen-hero can pull them directly into your Plex library as collections.

Setup​

  1. Create a free account at themoviedb.org
  2. Go to Settings > API and request an API key
  3. Add it to your .env file:
HSH_TMDB_API_KEY=your-api-key
  1. If you didn't enable TMDb in the Setup Wizard, enable it on the Lists page (or directly in config.yaml):
tmdb:
  enabled: true

Adding a List​

  1. Go to the Integrations page in the dashboard
  2. Click Add Source under TMDb
  3. Enter a name for the collection (this becomes the Plex collection name)
  4. Paste the TMDb list URL (e.g., https://www.themoviedb.org/list/123456)
  5. Select which Plex library to sync to
  6. Click Save, then hit Sync to pull in the list
tip

You can also enter just the list ID (e.g., 123456) instead of the full URL.

How Syncing Works​

When you sync a TMDb list, homescreen-hero:

  1. Fetches all items from the TMDb list via the API (supports pagination for large lists)
  2. Matches each item to your Plex library using TMDb ID for direct matching, which is the most reliable method available
  3. Creates or updates the Plex collection with all matched items
  4. Removes stale items - if something is removed from the TMDb list, it gets removed from the collection on the next sync
  5. Tracks missing items - any items on the TMDb list that aren't in your Plex library are logged and viewable from the dashboard

TMDb lists can contain both movies and TV shows. homescreen-hero handles both types and routes them to the correct Plex library.

note

Syncing is non-destructive on errors. If the TMDb API returns no items (e.g., due to an outage), homescreen-hero won't wipe your existing collection.

Auto-Request Missing Items​

If you have Seerr configured, you can enable auto-request on a per-source basis. When enabled, any items from the TMDb list that are missing from your Plex library will be automatically requested through Seerr after each sync.

Toggle auto-request in the source settings on the Lists page.

Missing Items​

After a sync, you can view which items from the TMDb list weren't found in your Plex library. This is useful for identifying gaps in your library or for manually requesting content.