Skip to main content

​
Overview

StreamVault uses The Movie Database (TMDB) API to fetch:
  • Movie and TV show metadata (titles, overviews, ratings)
  • High-quality posters and backdrops
  • Episode thumbnails and descriptions
  • Streaming search results
You can use either the built-in shared API key (free, subject to rate limits) or your own API key (recommended for unlimited requests).

​
API Key vs Access Token

TMDB provides two authentication methods:
MethodUse CaseFormat
API Key (v3)Basic authenticationa1b2c3d4e5f6... (32 chars)
Access Token (v4)Bearer token authenticationeyJhbGc... (JWT format)
StreamVault accepts both formats. The app automatically detects which type you’re using and applies the correct authentication header.

​
Getting Your TMDB API Key

1

Create a TMDB Account

Go to themoviedb.org and sign up for a free account
2

Navigate to API Settings

After logging in, go to:Settings → API → https://www.themoviedb.org/settings/api
3

Request API Access

Click Request an API Key and fill out the form:
  • Type of Use: Personal / Educational
  • Application Name: StreamVault (or your preferred name)
  • Application URL: You can use http://localhost for personal use
  • Application Summary: Briefly describe you’re using it for a personal media library
4

Accept Terms

Read and accept the TMDB API Terms of Use
5

Copy Your Credentials

You’ll receive two credentials:
  • API Key (v3 auth): 32-character hex string
  • API Read Access Token (v4 auth): JWT bearer token
Either one works! The Access Token is newer and recommended.

​
Entering API Key in StreamVault

1

Open Settings

Click the Settings gear icon in the top-right corner
2

Navigate to API Keys Section

Select API Keys from the sidebar
3

Choose API Key Mode

You’ll see two options:

​
Use Built-in API Key (Default)

  • No setup required
  • Shared across all users
  • May hit rate limits during peak usage (40 requests per 10 seconds)
  • Unlimited requests
  • No rate limits
  • Free for personal use
4

Enter Your Key

If using your own key:
  1. Select “Use Your Own API Key”
  2. Paste your API Key or Access Token into the input field
  3. Click Save

​
Settings UI Implementation

From SettingsModal.tsx:862-969: 
{/* TMDB API Key Mode Selection */}
<div className="p-4 rounded-xl bg-card border border-border space-y-4">
  <div className="flex items-center gap-3">
    <Label>TMDB API Key</Label>
    <p>Used for metadata, posters, and streaming search</p>
  </div>

  {/* Option: Use Built-in */}
  <button onClick={() => setUseOwnApiKey(false)}>
    <span>Use Built-in API Key</span>
    <span className="badge">FREE</span>
    <p>No setup needed. Shared, may hit rate limits.</p>
  </button>

  {/* Option: Use Your Own */}
  <button onClick={() => setUseOwnApiKey(true)}>
    <span>Use Your Own API Key</span>
    <span className="badge">RECOMMENDED</span>
    <p>Free key for unlimited requests.</p>
  </button>

  {/* Custom API Key Input */}
  {useOwnApiKey && (
    <Input
      type="password"
      value={config.tmdb_api_key}
      placeholder="Enter your TMDB API key or Access Token"
    />
  )}
</div>

​
Default Token Fallback

When no custom API key is configured, StreamVault uses a built-in token via the backend proxy (from .env.example:104-106): 
# Optional TMDB proxy override:
STREAMVAULT_TMDB_PROXY_URL=http://localhost:3001/api/tmdb
# If unset, uses localhost in debug and production backend URL in release
The built-in token is routed through the backend server to protect the shared API key from client-side exposure.

​
Testing Metadata Fetch

After configuring your API key:
1

Trigger Library Scan

Click Update Library in the sidebar to scan your Google Drive
2

Monitor Metadata Fetching

You should see:
  • Movie/TV show titles populating
  • Posters downloading to %APPDATA%/StreamVault/image_cache/
  • Episode metadata appearing in the UI
3

Check for Errors

If metadata fails to load:
  • Open Developer Console (Ctrl+Shift+I in dev mode)
  • Look for TMDB API errors
  • Verify your API key is correct
  • Check TMDB API status at status.themoviedb.org

​
Rate Limits

​
Built-in Shared Key

  • 40 requests per 10 seconds (shared across all users)
  • May cause delays during large library scans

​
Personal API Key

  • 40 requests per 10 seconds (per account)
  • Sufficient for most personal libraries
  • No concurrent user sharing
If you exceed rate limits, TMDB returns 429 Too Many Requests. StreamVault automatically retries with exponential backoff.

​
Configuration Storage

Your API key is stored in media_config.json (from config.rs:183): 
{
  "tmdb_api_key": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
Security: The config file is stored in plain text. Keep your %APPDATA%/StreamVault/ directory private and never commit it to version control.

​
Auto-Detection Logic

From SettingsModal.tsx:226-228: 
// If user already has a custom API key saved, show the custom input
setUseOwnApiKey(!!data.tmdb_api_key)
The UI automatically switches to “Use Your Own API Key” mode when a custom key is detected in the config.

​
API Usage in Code

StreamVault’s TMDB client (tmdb.rs) handles both authentication methods: 
// Supports both v3 API keys and v4 Bearer tokens
if api_key.starts_with("eyJ") {
    // v4 Bearer token
    request = request.header("Authorization", format!("Bearer {}", api_key));
} else {
    // v3 API key
    request = request.query(&[("api_key", api_key)]);
}

​
Troubleshooting

  • Verify your API key is entered correctly
  • Check TMDB API status
  • Ensure you have internet connectivity
  • Look for errors in %APPDATA%/StreamVault/logs/
  • Switch to using your own API key (unlimited personal use)
  • Reduce concurrent library scans
  • Wait 10 seconds before retrying
  • Ensure you copied the full key (no truncation)
  • Try using the Access Token instead of API Key
  • Regenerate your API key from TMDB settings
  • Use Fix Match to manually correct misidentified titles
  • Clear image cache: Settings → Advanced → Clean Up Missing Titles
  • Force refresh by removing and re-adding media

​
Next Steps

Google Drive Setup

Connect cloud storage for streaming

Player Setup

Install MPV for video playback

Library Management

Start organizing your media

Metadata Fetching

Learn about automatic metadata

Build docs developers (and LLMs) love

Get started for freeTalk to us