OneDrive Cloud Streaming

☁️ OneDrive Cloud Streaming

Freak-Flix enables high-performance video streaming directly from your OneDrive storage without requiring local file synchronization. This is achieved by integrating with the Microsoft Graph API, allowing the app to browse your cloud directory, fetch metadata, and stream raw video data to the internal player.

🏗️ Architecture Overview

To ensure cross-platform compatibility and bypass CORS limitations (especially on Web), Freak-Flix utilizes a proxy architecture:

1. Authentication: The client initiates an OAuth2 flow with Microsoft.
2. Proxy Layer: Token exchanges and API calls are routed through a backend proxy (/microsoft/proxy/* or a Netlify Function). This prevents exposing client secrets and handles the required headers for Microsoft’s servers.
3. Scanning: The backend recursively traverses the selected OneDrive folder, identifying video files and matching them against metadata providers (TMDB/AniList).
4. Streaming: The app retrieves a temporary @microsoft.graph.downloadUrl. This direct link is passed to the media engine (powered by media_kit and mpv) for low-latency playback.

🔑 Developer Setup: Azure App Registration

To enable OneDrive support in your own build, you must register an application in the Azure Portal.

1. Register an App: Go to App Registrations > New Registration.
2. Supported Account Types: Select "Accounts in any organizational directory and personal Microsoft accounts".
3. Redirect URI:
   • Desktop: http://localhost:8080 (or the port specified in your local environment).
   • Web: Your deployed frontend URL.
4. API Permissions: Ensure the following permissions are granted under Microsoft Graph:
   • Files.Read (Access to read user files)
   • Files.Read.All (Access to all files the user can access)
   • User.Read (Required for authentication)
   • offline_access (Required to maintain the session via refresh tokens)

⚙️ Configuration

Once your Azure App is registered, configure Freak-Flix to use your credentials.

1. Environment Variables

If you are running the backend service (Hono/Cloudflare Workers), ensure your environment is configured:

# Backend Proxy Secret (Optional)
JWT_SECRET=your_secure_secret
# The proxy endpoint allows the frontend to communicate with login.microsoftonline.com

2. App Settings

Within the Freak-Flix UI, navigate to Settings > Cloud Providers > OneDrive:

• Client ID: Your Azure Application (client) ID.
• Scopes: Files.Read User.Read offline_access.
• Proxy URL: If using a custom deployment, point this to your backend (e.g., https://api.yourdomain.com/microsoft/proxy/).

🚀 Usage: Adding Cloud Content

1. Login: Click the OneDrive icon in the Library Source selector and sign in with your Microsoft account.
2. Select Folder: Browse your OneDrive directory and select the folder containing your media.
3. Scan: Click Scan Library.
   • The app sends the folderId and accessToken to the backend.
   • The backend performs a recursive scan and populates your local database with file pointers and metadata.
4. Play: Selecting a movie from the UI will instantly request a streamable URL.

🛠️ Internal Proxy Interface

The proxy handles requests for token refreshing and directory listing. While internal, the endpoint structure follows this pattern:

| Endpoint | Method | Description | | :--- | :--- | :--- | | /microsoft/proxy/common/oauth2/v2.0/token | POST | Exchanges authorization codes for access tokens. | | /library/scan | POST | Triggers the background recursive scanner for a specific OneDrive path. |

Example Scan Request:

{
  "provider": "onedrive",
  "folderId": "YOUR_ONEDRIVE_FOLDER_ID",
  "accessToken": "YOUR_MS_GRAPH_TOKEN",
  "path": "/Videos/Movies"
}

Note: Because Freak-Flix uses direct download URLs, seek times are nearly identical to local files, depending on your internet bandwidth. No intermediate server downloads or re-encodes the video data.