Video Playback Engine
Core Architecture
Freak-Flix utilizes media_kit as its primary playback engine. This choice provides a high-performance, cross-platform video experience by leveraging the power of libmpv.
The engine is architected to handle local file system playback and high-bitrate cloud streaming (via OneDrive) with hardware-accelerated decoding across all supported platforms.
Platform Requirements & Setup
Windows
To achieve high-performance rendering on Windows, the application requires the mpv shared library.
- Dependency: Ensure
mpv-1.dllis present in the same directory as the executable (or within the system PATH). - Hardware Acceleration: Freak-Flix automatically attempts to use
d3d11va(Direct3D 11 Video Acceleration) for 4K and HEVC content to minimize CPU overhead. - Initialization:
// Ensure media_kit is initialized before running the app MediaKit.ensureInitialized();
Android
The Android implementation uses a native JNI-based libmpv binding. It supports high-efficiency video coding (HEVC) and standard subtitles (ASS/SRT). No manual DLL management is required for Android builds as the libraries are bundled via the Gradle build process.
Media Kit Configuration
The playback engine is initialized globally to manage resources efficiently. Below is the standard configuration pattern used within Freak-Flix:
Player Initialization
final player = Player();
final controller = VideoController(player);
// Configuration for high-performance streaming
await player.open(
Media('https://your-cloud-provider.com/stream/video.mp4'),
play: true,
);
Video Controller Features
The VideoController interface provides access to premium playback features:
| Feature | Description |
| :--- | :--- |
| Hardware Decoding | Automatically toggles based on platform capabilities (D3D11, VA-API, or MediaCodec). |
| Subtitle Management | Supports embedded and external .srt, .ass, and .vtt tracks. |
| Audio Track Switching | Allows dynamic switching between multi-language audio streams. |
| Buffering Strategy | Optimized for cloud streaming via the Microsoft Graph API/OneDrive. |
Cloud Streaming Integration
Freak-Flix handles cloud-based content by transforming OneDrive file identifiers into direct-access stream URLs.
The backend proxy (built with Hono/Cloudflare Workers) manages the authentication handshake, providing the Playback Engine with a Bearer token-authenticated URL. The engine handles these as standard HTTP streams, utilizing libmpv's advanced caching mechanism to prevent stuttering during network fluctuations.
Configuring Buffer Limits
For users with slower connections, the playback engine can be configured via the internal settings to increase the cache size:
- Default Cache: 32MB
- High-Bitrate (4K): 128MB+ (Recommended for Cloud content)
Troubleshooting Playback
Windows: DLL Not Found
If the player fails to initialize on Windows, verify that mpv-1.dll is correctly placed. During development, this file should be in build\windows\runner\Debug\.
Unsupported Formats
While libmpv supports virtually all modern containers (MKV, MP4, AVI, WebM), hardware acceleration availability depends on your specific GPU drivers. On Windows, ensure your graphics drivers are up to date to support 10-bit HEVC/VP9 decoding.