Skip to main content

​
Overview

Metadata commands integrate with TMDB (The Movie Database) API to fetch posters, overviews, episode details, and other enrichment data for your media library.

​
Commands

​
search_tmdb

Search TMDB for movies and TV shows by title. 
#[tauri::command]
async fn search_tmdb(
    state: State<'_, AppState>,
    query: String,
) -> Result<TmdbSearchResponse, String>
​
query
string
required
Search query (movie or TV show title)
​
TmdbSearchResponse
object

​
get_tmdb_details

Alias for get_tv_details. Fetch detailed information about a TV show. 
#[tauri::command]
async fn get_tv_details(
    state: State<'_, AppState>,
    tv_id: i64,
) -> Result<TvShowDetails, String>
​
tv_id
number
required
TMDB TV show ID
​
TvShowDetails
object

​
fix_match

Update a media item’s metadata by fetching from a specific TMDB ID. 
#[tauri::command]
async fn fix_match(
    window: Window,
    state: State<'_, AppState>,
    media_id: i64,
    tmdb_id: String,
    media_type: String,
) -> Result<ApiResponse, String>
​
media_id
number
required
Database ID of the media item to update
​
tmdb_id
string
required
Correct TMDB ID
​
media_type
'movie' | 'tv'
required
Media type
This command:
  1. Fetches metadata from TMDB (poster, overview, etc.)
  2. Downloads the poster to cache
  3. Updates the database entry
  4. Emits media-metadata-updated and library-updated events
Has a 40-second timeout to prevent hanging on slow networks. Retries automatically on connection errors.

​
download_poster

Posters are automatically downloaded during scanning and fix_match operations. No manual download command needed.
Posters are cached in %APPDATA%/StreamVault/image_cache/ and served via Tauri’s asset protocol.

​
get_cached_episode_metadata

Alias for get_tv_season_episodes. Fetch episode metadata for a specific season. 
#[tauri::command]
async fn get_tv_season_episodes(
    state: State<'_, AppState>,
    tv_id: i64,
    season_number: i32,
) -> Result<TvSeasonDetails, String>
​
tv_id
number
required
TMDB TV show ID
​
season_number
number
required
Season number (1-based)
​
TvSeasonDetails
object
Results are cached in the database. Subsequent requests for the same season return instantly from cache.

​
refresh_series_metadata

Force refresh episode metadata for a TV series (re-downloads images for owned episodes only). 
#[tauri::command]
async fn refresh_series_metadata(
    state: State<'_, AppState>,
    tv_id: i64,
    series_title: String,
) -> Result<String, String>
​
tv_id
number
required
TMDB TV show ID
​
series_title
string
required
Show title (for logging)
This command:
  • Only fetches metadata for episodes you actually have in your library
  • Clears old cached metadata before fetching
  • Downloads episode stills/thumbnails
  • Updates both the cache table and media entries

​
TMDB Image URLs

TMDB returns image paths like /abc123.jpg. Construct full URLs using: 
const posterUrl = `https://image.tmdb.org/t/p/w500${poster_path}`;
const backdropUrl = `https://image.tmdb.org/t/p/original${backdrop_path}`;
Available sizes:
  • Posters: w92, w185, w342, w500, w780, original
  • Backdrops: w300, w780, w1280, original
  • Stills (episodes): w92, w185, w300, original

​
Events

​
media-metadata-updated

Emitted when metadata is updated via fix_match. 
import { listen } from '@tauri-apps/api/event';

await listen<{
  type: 'metadata-updated';
  title: string;
  media_id: number;
  parent_id?: number;
  media_type: string;
  tmdb_id: string;
}>('media-metadata-updated', (event) => {
  console.log(`Updated: ${event.payload.title}`);
});

Build docs developers (and LLMs) love

Get started for freeTalk to us