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:
- Authentication: The client initiates an OAuth2 flow with Microsoft.
- 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. - Scanning: The backend recursively traverses the selected OneDrive folder, identifying video files and matching them against metadata providers (TMDB/AniList).
- Streaming: The app retrieves a temporary
@microsoft.graph.downloadUrl. This direct link is passed to the media engine (powered bymedia_kitandmpv) 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.
- Register an App: Go to App Registrations > New Registration.
- Supported Account Types: Select "Accounts in any organizational directory and personal Microsoft accounts".
- Redirect URI:
- Desktop:
http://localhost:8080(or the port specified in your local environment). - Web: Your deployed frontend URL.
- Desktop:
- 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
- Login: Click the OneDrive icon in the Library Source selector and sign in with your Microsoft account.
- Select Folder: Browse your OneDrive directory and select the folder containing your media.
- Scan: Click Scan Library.
- The app sends the
folderIdandaccessTokento the backend. - The backend performs a recursive scan and populates your local database with file pointers and metadata.
- The app sends the
- 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.