Metadata Providers

Dubby enriches your media with artwork, descriptions, cast & crew, and genre information from external metadata providers.

TMDB (The Movie Database)

TMDB is the primary metadata provider. It supplies:

• Posters — Portrait artwork (2:3 ratio)
• Backdrops — Landscape artwork (16:9 ratio)
• Logos — Transparent title treatments
• Descriptions — Plot overviews in multiple languages
• Cast & crew — Actors, directors, writers with profile photos
• Genres — Genre classifications
• Ratings — Content ratings and audience scores
• Release dates — Per-country release information

Getting a TMDB API key

1. Create a free account at themoviedb.org
2. Go to Settings > API in your TMDB account
3. Request an API key (select “Developer” for personal use)
4. Copy the API Key (v3 auth) value

Configuration

Set the API key via environment variable:

TMDB_API_KEY=your-api-key-here

Or configure it in the Dubby admin UI under Settings > Metadata. The UI-configured value is stored in the database and takes effect immediately without restarting.

How matching works

During a library scan, each media item goes through a matching process:

1. Parse the filename to extract title and year
2. Search TMDB for the title (with year as a filter when available)
3. Select the best match based on title similarity and year proximity
4. Download artwork, descriptions, and metadata

Match statuses

Status	Meaning
matched	Successfully matched to a TMDB entry
pending	Waiting to be matched (queued)
pending_retry	Match failed temporarily, will retry
unmatched	No match found — requires manual matching
manual	Manually matched by an admin

Unmatched items appear in the admin dashboard for manual resolution. You can search TMDB and select the correct match.

Image handling

Image proxy

TMDB images are downloaded and cached locally on the server. This means:

• Fast loading for all clients (no external CDN dependency)
• Images survive if TMDB is temporarily unavailable
• Consistent URLs for all clients

Images are cached in DUBBY_METADATA_CACHE_DIR (defaults to DUBBY_DATA_DIR/images).

Image sizes

The server provides multiple sizes for each image type:

Size	Use case
small	Thumbnails, list views
medium	Grid cards, search results
large	Detail pages, hero sections
original	Full resolution source

Clients request the appropriate size for their display context.

Custom image selection

Admins can select alternative artwork for any media item:

1. Open the media item’s detail page
2. Click the artwork to open the image picker
3. Browse available images from TMDB
4. Select your preferred poster, backdrop, or logo
5. Reset to the provider default at any time

Metadata editing

Admins can manually edit metadata fields for any media item:

• Title and sort title
• Overview/description
• Year
• Genres
• Content rating

Manual edits are preserved across library rescans. A full scan refreshes provider data but won’t overwrite manual edits.

Refreshing metadata

To update metadata from providers:

• Single item — Use the “Refresh metadata” option on the item’s detail page
• Full library scan — Triggers a metadata refresh for all items in the library

Metadata refresh is rate-limited to respect TMDB’s API limits.