Skip to main content

​
Introduction

StreamVault’s frontend API is built on Tauri IPC (Inter-Process Communication), enabling TypeScript code to invoke Rust backend functions seamlessly. All communication happens through the @tauri-apps/api/tauri module.

​
Architecture

​
Tauri Command Pattern

The API follows a command-based architecture:
  1. Frontend: TypeScript wrapper functions in src/services/api.ts
  2. IPC Layer: Tauri’s invoke() function serializes/deserializes data
  3. Backend: Rust #[tauri::command] functions in src-tauri/src/main.rs
// Frontend invokes backend command
import { invoke } from '@tauri-apps/api/tauri';

const items = await invoke<MediaItem[]>('get_library', {
  mediaType: 'movie',
  search: 'inception'
});

// Backend handles command
#[tauri::command]
async fn get_library(
    state: State<'_, AppState>,
    media_type: String,
    search: Option<String>,
) -> Result<Vec<database::MediaItem>, String> {
    // Implementation
}

​
Type Safety

All API functions use TypeScript interfaces that mirror Rust struct definitions: 
export interface MediaItem {
    id: number;
    title: string;
    media_type: 'movie' | 'tvshow' | 'tvepisode';
    file_path?: string;
    // ... all fields
}

​
Import Patterns

​
Standard Imports

import {
  getLibrary,
  playMedia,
  updateWatchProgress,
  MediaItem,
  ResumeInfo
} from '@/services/api';

​
Type-Only Imports

import type { MediaItem, StreamInfo } from '@/services/api';

​
Error Handling

All API functions use consistent error handling patterns:

​
Try-Catch Pattern

try {
  const items = await getLibrary('movie');
  // Success - items is MediaItem[]
} catch (error) {
  console.error('Failed to get library:', error);
  // Handle error
}

​
Graceful Fallback Pattern

export const getLibrary = async (
  type: 'movie' | 'tv',
  search: string = ''
): Promise<MediaItem[]> => {
  try {
    const items = await invoke<MediaItem[]>('get_library', {
      mediaType: type,
      search: search || null
    });
    return items;
  } catch (error) {
    console.error('Failed to get library:', error);
    return []; // Return empty array instead of throwing
  }
};

​
Error Response Type

interface ApiResponse {
  message: string;
}

interface ErrorResponse {
  error: string;
}

​
API Categories

The StreamVault API is organized into logical categories:

Media Operations

Library management, search, episodes, and metadata

Player Control

MPV playback, progress tracking, and session management

Cloud Operations

Google Drive integration and cloud library scanning

Configuration

App settings, player preferences, and API keys

​
Getting Started Example

Here’s a complete example of fetching and displaying movies: 
import { useState, useEffect } from 'react';
import { getLibrary, type MediaItem } from '@/services/api';

function MovieLibrary() {
  const [movies, setMovies] = useState<MediaItem[]>([]);
  const [loading, setLoading] = useState(true);

  useEffect(() => {
    async function fetchMovies() {
      try {
        setLoading(true);
        const items = await getLibrary('movie');
        setMovies(items);
      } catch (error) {
        console.error('Failed to fetch movies:', error);
      } finally {
        setLoading(false);
      }
    }

    fetchMovies();
  }, []);

  if (loading) return <div>Loading...</div>;

  return (
    <div>
      {movies.map(movie => (
        <div key={movie.id}>
          <h3>{movie.title}</h3>
          {movie.year && <p>({movie.year})</p>}
        </div>
      ))}
    </div>
  );
}

​
Event System

StreamVault uses Tauri events for backend-to-frontend communication: 
import { listen } from '@tauri-apps/api/event';

// Listen for library updates
const unlisten = await listen('library-updated', (event) => {
  console.log('Library was updated, refresh UI');
  refreshLibrary();
});

// Cleanup listener when component unmounts
unlisten();

​
Available Events

  • library-updated - Library content changed
  • scan-progress - Media scan in progress
  • scan-complete - Media scan finished
  • cloud-scan-complete - Cloud folder scan finished
  • mpv-playback-ended - MPV player closed
  • notification - System notification

​
Data Storage

All app data is stored in the platform-specific app data directory:
  • Windows: %APPDATA%/StreamVault/
  • macOS: ~/Library/Application Support/StreamVault/
  • Linux: ~/.StreamVault/

​
Key Files

  • media_library.db - SQLite database
  • media_config.json - User configuration
  • image_cache/ - Downloaded posters and thumbnails
  • mpv_progress/ - MPV playback progress tracking

​
Next Steps

Media Operations

Learn about library management APIs

Player Control

Explore playback and progress tracking

​
Application updates

StreamVault includes built-in auto-update functionality:

​
checkForUpdates()

Check for available updates from GitHub releases. 
export const checkForUpdates = async (): Promise<UpdateInfo>
Returns update information including version and download URL.

​
downloadUpdate()

Download an update installer. 
export const downloadUpdate = async (url: string): Promise<string>
Downloads the installer and returns the local file path.

​
installUpdate()

Install a downloaded update and restart the application. 
export const installUpdate = async (installerPath: string): Promise<void>
This will close the application and launch the installer.

​
getAppVersion()

Get the current application version. 
export const getAppVersion = async (): Promise<string>
Returns version string (e.g., “3.0.21”).

Build docs developers (and LLMs) love

Get started for freeTalk to us