# wang-bin/fvp architecture

> Architecture diagram of the GitHub repository wang-bin/fvp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-02-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/wang-bin/fvp
- Repository: https://github.com/wang-bin/fvp

## Overview

##### Main Components
- Flutter Application (Dart/Widget Layer): Represents the main app which incorporates the video player – using the plugin.
- FVP Plugin in Dart:
- Core API for playback control and video-related operations.
- Extension components that wrap or extend the official video_player functionality.
- Callback management and event handling within Dart (including ReceivePort usage for async event notifications).
- FFI and Method Channel Bridge:
- This layer connects Dart to platform-specific native code. It exposes FFI bindings and platform interface methods.
- Platform-Specific Native Implementations:
- Each supported platform (Android, iOS/darwin, Windows, Linux, macOS) provides its native code, responsible for video rendering, hardware decoding, and interfacing with native libraries (using frameworks like D3D11 for Windows, Metal for macOS/iOS, and OpenGL for Linux/Android).
- These components include C++ source files, header files and platform configuration (CMakeLists, .podspec files) for native build systems.
- Underlying Native Libraries:
- Libmdk (video decoding and rendering engine) and optionally bundled FFmpeg and libass for subtitles are integrated on the native side.

##### Relationships and Interactions
- The Dart layer invokes the plugin’s API (e.g., fvp.registerWith, player methods, or extended video_player APIs).
- The plugin internally uses the FFI layer or a MethodChannel to communicate with native platform implementations.
- Native implementations then use specific hardware decoding APIs and rendering backends, relying on platform-specific libraries.
- Asynchronous callbacks from native code (using mechanisms like ReceivePort) return events back to the Dart layer.
- For enhanced functionality, optional configuration options (e.g., selecting decoders or enabling low-latency modes) are passed down through this chain.

##### Architectural Patterns and Design Principles
- Plugin Architecture: Separates core Dart functionality and platform-specific implementations.
- Cross-Platform Abstraction: Encapsulates differences among platforms using a unified API.
- FFI Integration: A thin wrapper handles the complexity of bridging between Dart and native implementations.
- Asynchronous and Event-Driven Programming: Uses callbacks and futures to process video state, errors, and events.
- Modular Design: Each platform directory not only isolates platform dependencies but also supports independent evolution and testing.

##### Relevant Technologies, Frameworks, and Libraries
- Flutter/Dart for the application and plugin API.
- FFI & MethodChannels for bridging between the Dart and native layers.
- Native C++ code for high-performance video processing.
- Platform-specific rendering APIs:
- Direct3D 11 for Windows (including Windows 7 support).
- Metal for macOS and iOS.
- OpenGL (or Impeller support) for Linux and Android.
- External libraries such as libmdk, FFmpeg, and libass (for subtitles).

##### Final Advice to the Principal Software Engineer
- That every component is clearly labeled and that all communication flows (invocations, callbacks, error handling) are explicitly depicted.
- Don’t hesitate to further split components if they encapsulate several responsibilities (for example, separate the FFI bridge from the MethodChannel portion if both exist in your implementation).
- Accuracy is paramount: capture the essential interactions, configuration options, and the flow from the Flutter side all the way to the native rendering and decoding engines.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Flutter/Dart Layer
    subgraph "Flutter/Dart Layer"
        FlutterApp["Flutter Application (Dart/Widget Layer)"]:::dart
        FVPCore["FVP Plugin Core API (Dart Layer)"]:::dart
    end

    %% FFI/MethodChannel Bridge
    subgraph "FFI/MethodChannel Bridge"
        Bridge["FFI/MethodChannel Bridge"]:::bridge
    end

    %% Native Implementations
    subgraph "Native Implementations"
        AndroidNative["Android Native Implementation"]:::native
        iOSNative["iOS Native Implementation"]:::native
        macOSNative["macOS Native Implementation"]:::native
        LinuxNative["Linux Native Implementation"]:::native
        WindowsNative["Windows Native Implementation"]:::native
    end

    %% Underlying Native Libraries
    UnderlyingLib["Underlying Native Libraries (libmdk, FFmpeg, libass)"]:::libraries

    %% Data Flow
    FlutterApp -->|"calls"| FVPCore
    FVPCore -->|"invokes"| Bridge
    Bridge -->|"routes to"| AndroidNative
    Bridge -->|"routes to"| iOSNative
    Bridge -->|"routes to"| macOSNative
    Bridge -->|"routes to"| LinuxNative
    Bridge -->|"routes to"| WindowsNative

    %% Asynchronous callbacks from native back to Dart
    AndroidNative -.->|"callback"| FVPCore
    iOSNative -.->|"callback"| FVPCore
    macOSNative -.->|"callback"| FVPCore
    LinuxNative -.->|"callback"| FVPCore
    WindowsNative -.->|"callback"| FVPCore
    FVPCore -->|"event"| FlutterApp

    %% Configuration options flow
    FVPCore -->|"config_options"| UnderlyingLib

    %% Click Events
    click FlutterApp "https://github.com/wang-bin/fvp/blob/master/example/lib/main.dart"
    click FVPCore "https://github.com/wang-bin/fvp/blob/master/lib/fvp.dart"
    click FVPCore "https://github.com/wang-bin/fvp/blob/master/lib/src/controller.dart"
    click FVPCore "https://github.com/wang-bin/fvp/blob/master/lib/src/player.dart"
    click Bridge "https://github.com/wang-bin/fvp/blob/master/lib/src/fvp_method_channel.dart"
    click AndroidNative "https://github.com/wang-bin/fvp/blob/master/android/fvp_plugin.cpp"
    click AndroidNative "https://github.com/wang-bin/fvp/blob/master/android/src/main/java/com/mediadevkit/fvp/FvpPlugin.java"
    click iOSNative "https://github.com/wang-bin/fvp/blob/master/ios/Classes/FvpPlugin.mm"
    click macOSNative "https://github.com/wang-bin/fvp/blob/master/macos/Classes/FvpPlugin.mm"
    click LinuxNative "https://github.com/wang-bin/fvp/blob/master/linux/fvp_plugin.cc"
    click LinuxNative "https://github.com/wang-bin/fvp/blob/master/linux/include/fvp/fvp_plugin.h"
    click WindowsNative "https://github.com/wang-bin/fvp/blob/master/windows/fvp_plugin.cpp"
    click WindowsNative "https://github.com/wang-bin/fvp/blob/master/windows/include/fvp/fvp_plugin_c_api.h"

    %% Styles
    classDef dart fill:#CDEBFF,stroke:#333,stroke-width:2px;
    classDef bridge fill:#FFE0B2,stroke:#333,stroke-width:2px;
    classDef native fill:#FFCDD2,stroke:#333,stroke-width:2px;
    classDef libraries fill:#D1C4E9,stroke:#333,stroke-width:2px;
```
