Overview
StreamVault integrates with Google Drive to:- Index your entire cloud media library
- Stream videos directly without downloading
- Monitor for new content in real-time (5-second polling)
- Cache frequently watched content locally
Google Drive integration uses OAuth 2.0 authentication handled securely by the StreamVault backend server.
OAuth Flow Architecture
The authentication process uses a backend proxy to protect OAuth credentials:Why Use a Backend Server?
Fromgdrive.rs:14-17:
Connecting Google Drive
Sign In to Google
- Select or sign in to your Google account
- Review the permissions StreamVault is requesting
Grant Permissions
Click Allow to grant StreamVault:
- Read access to your Google Drive files (
drive.readonlyscope) - Basic profile information (email, name)
Automatic Redirect
After authorization:
- Production: Redirects to
https://indexer-oauth-callback.vercel.app/ - Development: Redirects to
http://localhost:8085/callback
Connection UI Implementation
FromGoogleDriveSettings.tsx:49-80:
OAuth Scopes
StreamVault requests these Google API scopes:| Scope | Purpose |
|---|---|
https://www.googleapis.com/auth/drive.readonly | Read-only access to Drive files (default) |
https://www.googleapis.com/auth/drive | Full access (required for delete operations) |
https://www.googleapis.com/auth/userinfo.email | User email address |
https://www.googleapis.com/auth/userinfo.profile | User profile information |
By default, StreamVault uses read-only scope (
drive.readonly). Full access is only requested when you use delete operations.Re-Authentication for Delete Permissions
When you delete media from StreamVault that needs to be removed from Drive:Grant Additional Permission
Google’s consent screen shows:
- ✓ See and download all your Google Drive files
- ✓ Delete files and folders in your Google Drive (new)
Token Refresh
Access tokens expire after 1 hour. StreamVault automatically refreshes them using the refresh token. Fromgdrive.rs:106-127:
Refresh Flow
Fromgdrive.rs:130-167:
Refresh tokens are long-lived (valid until revoked). StreamVault stores them securely in
%APPDATA%/StreamVault/gdrive_tokens.json.Disconnecting Google Drive
FromGoogleDriveSettings.tsx:82-103:
Account Information Display
After connecting, StreamVault displays:- Email: Google account email address
- Storage Used: Current Drive storage usage
- Storage Limit: Total Drive storage quota
- Storage Bar: Visual progress indicator
GoogleDriveSettings.tsx:150-177:
Indexing Your Drive
After connecting:Monitor Progress
Watch the progress indicator as StreamVault:
- Scans all folders recursively
- Identifies movie and TV show files
- Fetches metadata from TMDB
- Downloads posters and thumbnails
Indexing is incremental - only new files not already in the database are processed.
Real-Time Change Detection
StreamVault monitors Google Drive for changes every 5 seconds using the Changes API. Fromconfig.rs:194-208:
How It Works
- Initial Scan: Gets a
startPageTokenfrom Google Drive Changes API - Store Token: Saves token in SQLite database
- Poll for Changes: Every 5 seconds, requests changes since last token
- Process New Files: Indexes newly added videos
- Update Token: Updates stored token for next poll
Change detection runs even when minimized to system tray. You’ll receive Windows notifications when new media is added.
Environment Variables
For self-hosting or forking the backend, configure these in.env.example:66-78:
Troubleshooting
Browser Doesn't Open
Browser Doesn't Open
- Check if your default browser is set correctly
- Try copying the OAuth URL from the console and opening it manually
- Ensure firewall isn’t blocking localhost:8085 (dev mode)
Authentication Failed
Authentication Failed
- Verify backend server is online: https://streamvault-backend-server.onrender.com
- Check OAuth redirect URIs in Google Cloud Console
- Clear stored tokens: Settings → Advanced → Reset Application
Token Expired
Token Expired
StreamVault automatically refreshes tokens. If this fails:
- Disconnect and reconnect Google Drive
- Check internet connectivity
- Verify refresh token wasn’t revoked in Google Account settings
Indexing Hangs
Indexing Hangs
- Check Google Drive API quota (not exceeded)
- Ensure TMDB API key is configured
- Monitor Developer Console for errors
- Try indexing a smaller folder first
Next Steps
TMDB Setup
Configure TMDB API for metadata
Player Setup
Install MPV for playback
Cloud Streaming
Start streaming from Drive
Library Management
Organize your media library