Skip to main content

​
Overview

This guide walks you through setting up StreamVault for the first time, connecting Google Drive, configuring TMDB metadata, and scanning your first media library.
Before you begin: Make sure you’ve completed the installation steps and have StreamVault running on your system.

​
First launch

1

Launch StreamVault

Start the application from your applications menu or by running:
npm run tauri dev
The application window will open with a 1400×900 fixed-size interface featuring StreamVault’s signature monochrome design.
2

Complete onboarding (first launch only)

If this is your first time launching StreamVault, you’ll see the onboarding wizard. This will guide you through:
  • Connecting your Google Drive account
  • Entering your TMDB API key (optional but recommended)
  • Configuring MPV player path (if not auto-detected)
You can skip the onboarding and configure everything later in Settings, but we recommend completing it now for the best experience.
3

Verify MPV detection

StreamVault will automatically search for MPV in common installation locations. If found, you’ll see a confirmation message.If MPV is not detected:
  1. Open Settings from the sidebar
  2. Navigate to Player settings
  3. Click Browse and locate your mpv.exe file
  4. Save the configuration
Without a valid MPV path, you won’t be able to play any media. See player setup for detailed configuration.

​
Connect Google Drive

1

Open Google Drive settings

  1. Click Settings in the left sidebar
  2. Navigate to the Google Drive section
  3. Click Connect Google Drive button
This will open your default browser for OAuth authentication.
2

Authorize StreamVault

In the browser window:
  1. Sign in to your Google account (if not already signed in)
  2. Review the permissions StreamVault is requesting:
    • Read-only access to your Google Drive files
    • File metadata for indexing video files
  3. Click Allow to grant access
  4. You’ll be redirected back with a success message
StreamVault uses OAuth2 for secure authentication. Your credentials are never stored locally - only refresh tokens are saved in %APPDATA%/StreamVault/media_config.json.
3

Verify connection

Return to StreamVault. You should see:
  • Connected status with your Google account email
  • Disconnect Google Drive button (to revoke access if needed)
  • Update Library button enabled in the sidebar
Background sync will now monitor your Google Drive for changes every 5 seconds, even when the app is minimized to the system tray.

​
Set up TMDB metadata

1

Get a TMDB API key

  1. Create a free account at themoviedb.org
  2. Verify your email address
  3. Navigate to Settings → API
  4. Request an API key (choose “Developer” for personal use)
  5. Fill out the application form:
    • Type of use: Personal
    • Application name: StreamVault Personal Library
    • Application URL: Can be left blank or use GitHub repo URL
  6. Accept the terms of service
  7. Copy your API Read Access Token (v4 auth token, starts with eyJ...)
StreamVault supports both v3 API keys and v4 access tokens. The access token is recommended as it has higher rate limits.
2

Add API key to StreamVault

  1. Open Settings in StreamVault
  2. Navigate to TMDB section
  3. Paste your API key or access token into the TMDB API Key field
  4. Click Save
The key is encrypted and stored locally in %APPDATA%/StreamVault/media_config.json.
3

Verify TMDB connection (optional)

StreamVault will automatically validate your API key when you first scan media. If the key is invalid, you’ll see error messages in the scan progress.
Without a TMDB API key, StreamVault will still index your media files, but posters, backdrops, and metadata will be unavailable.

​
Scan your first library

1

Start library scan

Click the Update Library button in the left sidebar. This initiates a full Google Drive scan.StreamVault will:
  • Fetch your entire Google Drive file list
  • Filter for supported video formats (.mkv, .mp4, .avi, etc.)
  • Parse filenames to extract titles, years, and episode numbers
  • Query TMDB for metadata and images
  • Store everything in the local SQLite database
The first scan can take several minutes depending on the size of your Google Drive. Subsequent scans use incremental updates and are much faster.
2

Monitor scan progress

A progress dialog will appear showing:
  • Current file being processed
  • Files processed vs total files found
  • Percentage complete
  • Estimated time remaining
You can minimize StreamVault during scanning - it will continue in the background and show a notification when complete.
scan-progress    # Real-time progress updates
scan-complete    # Fires when scan finishes
library-updated  # Database has been updated
notification     # Windows toast notification
3

Review indexed media

Once the scan completes:
  1. Click Movies in the sidebar to view indexed movies
  2. Click TV Shows to browse series and episodes
  3. Each item shows:
    • Poster or backdrop image from TMDB
    • Title and year
    • Rating from TMDB
    • Overview on hover or click
Right-click any media item to access context menu options like Play, Fix Match, Mark as Watched, or View Details.

​
Play your first video

1

Select media to play

Browse your library and click on any movie or episode card. A details view will appear showing:
  • Full metadata (title, year, overview, cast, rating)
  • Backdrop image
  • Play button (or Resume if you’ve watched part of it)
  • Episode list (for TV shows)
2

Start playback

Click the Play or Resume button. StreamVault will:
  1. Generate a temporary Google Drive download URL
  2. Launch MPV player with the video stream
  3. Restore your previous playback position (if resuming)
  4. Begin tracking progress via MPV IPC
Progress tracking    # Auto-saves every few seconds
Resume position      # Stored in SQLite database
Playback events      # mpv-playback-ended event
Watch history        # Records completion status
3

Control playback

Use MPV’s built-in controls:
  • Space: Pause/play
  • Left/Right arrows: Seek backward/forward 5 seconds
  • Up/Down arrows: Volume control
  • F: Toggle fullscreen
  • S: Take screenshot
  • Q: Quit player
Your progress is automatically saved. When you quit MPV, StreamVault records your position and watch status.
See keyboard shortcuts for a complete list of MPV hotkeys.

​
Enable background sync

StreamVault continuously monitors your Google Drive for new files:
1

Verify background sync is enabled

  1. Open Settings
  2. Navigate to Google Drive section
  3. Ensure Background Sync is enabled
  4. Set Scan Interval (default: 5 minutes)
Background sync uses Google Drive’s Changes API to detect new files without re-scanning your entire Drive. This is very efficient and uses minimal API quota.
2

Minimize to system tray

Click the minimize button or close the window. StreamVault will:
  • Minimize to the system tray (Windows notification area)
  • Continue background sync polling every 5 seconds
  • Show a toast notification when new media is detected
  • Automatically index new files without user intervention
Right-click the system tray icon to access quick actions like Show Window, Update Library, or Quit.

​
What’s next?

Explore core features

Learn about real-time change detection, incremental updates, and cloud caching

Configure settings

Customize player paths, cache limits, scan intervals, and more

Fix mismatched media

Manually correct TMDB matches using the Fix Match feature

Browse TV episodes

Navigate seasons and episodes with full metadata and thumbnails

Social features

Watch media together with friends using synchronized playback

Self-host backend

Deploy your own StreamVault backend for complete control

​
Troubleshooting

Problem: OAuth flow fails or connection times outSolutions:
  • Ensure you’re using a supported browser (Chrome, Firefox, Edge)
  • Check your internet connection
  • Verify the backend server is accessible
  • Try disconnecting and reconnecting in Settings
  • Clear browser cookies for Google accounts and retry
Check backend status:
curl https://streamvault-backend-server.onrender.com/health
Problem: Media is indexed but has no posters or metadataSolutions:
  • Verify your TMDB API key is valid (check Settings → TMDB)
  • Ensure your API key has not exceeded rate limits
  • Try manually fixing the match using Fix Match in the context menu
  • Check console logs for specific TMDB API errors
Rate limits:
  • Free tier: 40 requests per 10 seconds
  • Access token (v4): Higher limits, recommended
Problem: Video doesn’t start or MPV crashesSolutions:
  • Verify MPV is installed and in your PATH
  • Check MPV path in Settings → Player
  • Try playing the file directly with MPV to rule out format issues
  • Update MPV to the latest version
  • Check if the Google Drive file is accessible (not deleted or moved)
Test MPV manually:
mpv --version
mpv "https://test-videos.co.uk/vids/bigbuckbunny/mp4/h264/360/Big_Buck_Bunny_360_10s_1MB.mp4"
Problem: First scan takes a very long timeThis is normal for first scans:
  • Google Drive API has rate limits
  • TMDB lookups are done sequentially to avoid rate limiting
  • Large libraries (1000+ files) can take 30+ minutes
Speed up future scans:
  • Enable incremental updates (default behavior)
  • Use background sync instead of manual “Update Library”
  • Ensure TMDB API key is configured (falls back to slower proxy without it)
For more issues, see the troubleshooting guide or report bugs on GitHub Issues.

Build docs developers (and LLMs) love

Get started for freeTalk to us