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.

1. Dependency: Ensure mpv-1.dll is present in the same directory as the executable (or within the system PATH).
2. Hardware Acceleration: Freak-Flix automatically attempts to use d3d11va (Direct3D 11 Video Acceleration) for 4K and HEVC content to minimize CPU overhead.
3. 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.