TMDB Media Discovery

TMDB Integration Overview

The TMDB (The Movie Database) service is the primary engine for metadata enrichment within Freak-Flix. It transforms raw file names into a cinematic experience by fetching high-resolution posters, backdrops, plot summaries, and cast information for Movies and TV Shows.

Prerequisites

To enable media discovery, you must obtain a TMDB API Key (v3 auth).

1. Sign up for an account at The Movie Database.
2. Navigate to Settings > API to generate your API key.
3. Ensure the key is active before adding it to the application.

Configuration

Once you have your API key, integrate it into Freak-Flix via the UI or the configuration layer:

1. Launch the application and navigate to Settings.
2. Locate the API Keys section.
3. Paste your key into the TMDB API Key field.
4. The application validates the key upon the next library scan or search request.

Key Features

🎬 Automated Movie & TV Identification

During the library scanning process (/library/scan), Freak-Flix parses file names to extract titles and release years. These identifiers are queried against TMDB to retrieve:

• Visual Assets: High-definition posters and fan-art backdrops.
• Metadata: Genres, release dates, runtime, and official trailers.
• Ratings: Real-time user ratings from the TMDB community.

👥 Actor Profiles & Discovery

The integration extends beyond title metadata to provide comprehensive "Deep Dive" actor profiles:

• Biographies: Detailed life stories and career overviews.
• Known For: A randomized, curated list of the actor's most prominent work.
• Dynamic Links: Clicking an actor allows you to explore other titles in your library featuring the same person.

🏷️ Intelligent Categorization

Freak-Flix uses TMDB genre IDs to automatically categorize your content into rows (e.g., Action, Sci-Fi, Documentary), mimicking the Netflix-style browsing experience.

Usage Example (API Interaction)

While metadata fetching is typically handled automatically by the internal scanner, the underlying logic follows a standard identification pattern. If you are extending the backend or utilizing the proxy, the data flow resembles the following structure:

// Example of the enriched metadata object returned to the UI
{
  "tmdb_id": 550,
  "title": "Fight Club",
  "overview": "A ticking-time-bomb insomniac and a slippery soap salesman...",
  "poster_path": "/pB8BM79v9GaNAoZ2NooCUfMDpWH.jpg",
  "backdrop_path": "/hZk93cy3uUuS2S3uUuS2S3uUuS2.jpg",
  "release_date": "1999-10-15",
  "genres": ["Drama"],
  "cast": [
    {
      "name": "Edward Norton",
      "character": "The Narrator",
      "profile_path": "/59SAnunvSscq967PSe79O7K06iG.jpg"
    }
  ]
}

Troubleshooting

• Missing Metadata: Ensure your folders are named clearly (e.g., Movie Title (Year)). Obfuscated file names may fail the matching algorithm.
• Connection Issues: If you are using the web version or a restricted network, ensure your environment can reach api.themoviedb.org.
• Rate Limiting: TMDB enforces rate limits. Freak-Flix handles this via internal request queuing, but ensure your API key is not being shared across multiple high-volume instances.