# thereprator/kvideo-player architecture

> Architecture diagram of the GitHub repository thereprator/kvideo-player, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-02-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/thereprator/kvideo-player
- Repository: https://github.com/thereprator/kvideo-player

## Overview

##### Project Type & Purpose
- This is a **Kotlin Multiplatform library + sample-app suite** for playing HLS, DASH, and SmoothStreaming media across Web (JS & WASM), Desktop (JVM + bundled VLC), Android (phone/tablet/Auto/TV/Wear/XR), iOS, and tvOS.
- The goal is to expose a **common playback API** (`KMP-player`), a **common Compose-based UI** (`player-ui`), plus **platform wrappers** (Android modules, Swift xcframework) and **sample applications** that consume them.

##### File Structure
- **Top-level modules**:
- `framework/KMP-player` – the core KMP playback engine
- `framework/player-ui` – a Compose-based, multiplatform UI abstraction
- `framework/AppleKMPVideoPlayer` – a Swift/xcframework wrapper around AVFoundation for iOS/tvOS
- `framework/android/*` – Android-Auto, TV, Wear modules that wire in `KMP-player` + `player-ui`
- `sample/*` – sample apps per platform consuming the published artifacts
- **Build & deployment**:
- Gradle Kotlin-DSL (`.kts`) for orchestrating MPP source sets (`commonMain`, `androidMain`, `iosMain`, `jsMain`, etc.)
- Swift Package manifest (`Package.swift`) and `xcframework` for iOS
- Pre-bundled VLC binaries under `desktopMain/resources/appResources`

##### Pull Insights from the README
- **Supported platforms**: Kotlin/WASM, JS, Desktop (JVM+VLC), Android (phone/Auto/TV/Wear/XR), iOS, Apple TV
- **External dependencies**: Video.js (web playback), Hamamas HTML-Interop (WASM), VLC binaries (desktop), AVPlayer (iOS), ExoPlayer or Android’s media APIs
- **Architectural principle**: one **common interface** + multiple **platform-specific implementations**, published as artifacts and consumed by UI and sample apps.

a. **Main Components**
- Core Playback Engine (`KMP-player/commonMain`)
- Platform Implementations (`KMP-player/androidMain`, `appleMain`, `desktopMain`, `jsMain`, `wasmJsMain`, `webMain`)
- UI Abstraction (`player-ui/commonMain`) + Platform UI Views (`androidMain`, `desktopMain`, `iosMain`, `webMain`)
- iOS Swift Wrapper (`AppleKMPVideoPlayer/xcframework`)
- Desktop VLC Binaries (`desktopMain/resources/appResources/...`)
- Sample Applications (`sample/src`, `sample/android`, `sample/ios`, `sample/AppleTVPlayer`)

b. **Interactions & Data Flow**
- **Samples ➔ UI module**: sample app invokes `VideoScreen` (Compose)
- **UI module ➔ Core engine**: calls `VideoPlayer` interface (init/play/pause/ dispose)
- **Core engine ➔ Platform impl**: dispatches to `VideoPlayerImplAndroid`, `PlaybackStateControllerImplIos`, `VideoPlayerImplWeb`, `VideoPlayerImplJvm`
- **Platform impl ➔ Native API**:
- Android: ExoPlayer/Media APIs
- iOS: AVPlayer via Swift xcframework
- Desktop: libVLC via bundled binaries
- Web: HTML5 `<video>` or Video.js via WASM-JS interop
- **Build system**: Gradle compiles each source set into artifacts, SPM bundles the xcframework, Gradle assembles sample apps.

c. **Architectural Patterns & Principles**
- **Layered design**: UI → core API → platform implementation → native media engine
- **Abstraction via Interfaces** in `commonMain`, **Implementations in platform source sets**
- **Multi-module Gradle project** with shared `settings.gradle.kts` and `libs.versions.toml`
- **Pre-bundled native binaries** for desktop to avoid external dependencies

d. **Key Technologies & Libraries**
- Kotlin Multiplatform (common/Android/iOS/JS/Native source sets)
- Jetpack Compose Multiplatform (`player-ui`)
- Swift Package Manager + xcframework (`AppleKMPVideoPlayer`)
- Video.js & Kotlin-WASM-HTML-Interop (web)
- VLC (desktop)
- Android Auto/TV/Wear/XR UI modules

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph "Sample Apps"
        MultiPlatformSample["Multi-platform Sample\n(shared code)"]:::sample
        AndroidSample["Android Sample App"]:::sample
        iOSSample["iOS Sample App"]:::sample
        DesktopSample["Desktop Sample App"]:::sample
        WebSample["Web Sample App"]:::sample
    end

    subgraph "UI Module (player-ui)"
        UICommon["VideoScreen\n(commonMain)"]:::common
        AndroidUIView["PlatformVideoView.android\n(androidMain)"]:::platform
        iOSUIView["PlatformVideoView.ios\n(iosMain)"]:::platform
        DesktopUIView["PlatformVideoView.desktop\n(desktopMain)"]:::platform
        WebUIView["PlatformVideoView.web\n(webMain)"]:::platform
    end

    subgraph "Core Playback Engine (KMP-player)"
        CoreCommon["VideoPlayer Interface\n(commonMain)"]:::common
        AndroidImpl["VideoPlayerImplAndroid\n(androidMain)"]:::platform
        iOSImpl["VideoPlayerImplIos\n(appleMain)"]:::platform
        JVMImpl["VideoPlayerImplJvm\n(desktopMain)"]:::platform
        WebImpl["VideoPlayerImplWeb\n(webMain)"]:::platform
        JSExternal["VideoExternal.js\n(jsMain)"]:::platform
        WASMExternal["VideoExternal.wasmJs\n(wasmJsMain)"]:::platform
    end

    subgraph "Native Engines / External Libs"
        Exo["ExoPlayer / Android Media APIs"]:::native
        AVP["AVPlayer / xcframework"]:::native
        VLC["libVLC (bundled)"]:::native
        HTML5["HTML5 Video / Video.js"]:::native
    end

    %% Relationships
    MultiPlatformSample -->|"calls VideoScreen"| UICommon
    AndroidSample -->|"calls VideoScreen"| UICommon
    iOSSample -->|"calls VideoScreen"| UICommon
    DesktopSample -->|"calls VideoScreen"| UICommon
    WebSample -->|"calls VideoScreen"| UICommon

    UICommon -->|"VideoPlayer.init()/play()"| CoreCommon

    CoreCommon -->|"dispatch to AndroidImpl"| AndroidImpl
    CoreCommon -->|"dispatch to iOSImpl"| iOSImpl
    CoreCommon -->|"dispatch to JVMImpl"| JVMImpl
    CoreCommon -->|"dispatch to WebImpl"| WebImpl
    CoreCommon -->|"dispatch to JSExternal"| JSExternal
    CoreCommon -->|"dispatch to WASMExternal"| WASMExternal

    AndroidImpl -->|"uses ExoPlayer API"| Exo
    iOSImpl -->|"uses AVPlayer"| AVP
    JVMImpl -->|"uses libVLC"| VLC
    WebImpl -->|"uses HTML5 video"| HTML5
    JSExternal -->|"interop Video.js"| HTML5
    WASMExternal -->|"interop HTML video"| HTML5

    %% Click Events - Core
    click CoreCommon "https://github.com/thereprator/kvideo-player/tree/main/framework/KMP-player/src/commonMain/kotlin/dev/reprator/kmp/video"
    click AndroidImpl "https://github.com/thereprator/kvideo-player/blob/main/framework/KMP-player/src/androidMain/kotlin/dev/reprator/kmp/video/platform/impl/VideoPlayerImplAndroid.kt"
    click iOSImpl "https://github.com/thereprator/kvideo-player/blob/main/framework/KMP-player/src/appleMain/kotlin/dev/reprator/kmp/video/platform/impl/VideoPlayerImplIos.kt"
    click JVMImpl "https://github.com/thereprator/kvideo-player/blob/main/framework/KMP-player/src/desktopMain/kotlin/dev/reprator/kmp/video/platform/impl/VideoPlayerImplJvm.kt"
    click JSExternal "https://github.com/thereprator/kvideo-player/blob/main/framework/KMP-player/src/jsMain/kotlin/dev/reprator/kmp/video/platform/external/VideoExternal.js.kt"
    click WASMExternal "https://github.com/thereprator/kvideo-player/blob/main/framework/KMP-player/src/wasmJsMain/kotlin/dev/reprator/kmp/video/platform/external/VideoExternal.wasmJs.kt"
    click WebImpl "https://github.com/thereprator/kvideo-player/blob/main/framework/KMP-player/src/webMain/kotlin/dev/reprator/kmp/video/platform/impl/VideoPlayerImplWeb.kt"

    %% Click Events - UI
    click UICommon "https://github.com/thereprator/kvideo-player/blob/main/framework/player-ui/src/commonMain/kotlin/dev/reprator/video/ui/VideoScreen.kt"
    click AndroidUIView "https://github.com/thereprator/kvideo-player/blob/main/framework/player-ui/src/androidMain/kotlin/dev/reprator/video/platform/PlatformVideoView.android.kt"
    click iOSUIView "https://github.com/thereprator/kvideo-player/blob/main/framework/player-ui/src/iosMain/kotlin/dev/reprator/video/platform/PlatformVideoView.ios.kt"
    click DesktopUIView "https://github.com/thereprator/kvideo-player/blob/main/framework/player-ui/src/desktopMain/kotlin/dev/reprator/video/platform/PlatformVideoView.desktop.kt"
    click WebUIView "https://github.com/thereprator/kvideo-player/blob/main/framework/player-ui/src/webMain/kotlin/dev/reprator/video/platform/PlatformVideoView.web.kt"

    %% Click Events - Native Wrapper
    click AVP "https://github.com/thereprator/kvideo-player/blob/main/framework/AppleKMPVideoPlayer/Framework/VideoFrameWorkKMP.xcframework"

    %% Click Events - Sample Apps
    click MultiPlatformSample "https://github.com/thereprator/kvideo-player/blob/main/sample/src/commonMain/kotlin/dev.reprator.video.demo/VideoScreen.kt"
    click AndroidSample "https://github.com/thereprator/kvideo-player/blob/main/sample/src/androidMain/kotlin/dev/reprator/video/demo/MainActivity.kt"
    click DesktopSample "https://github.com/thereprator/kvideo-player/blob/main/sample/src/desktopMain/kotlin/dev/reprator/video/demo/Main.kt"
    click iOSSample "https://github.com/thereprator/kvideo-player/blob/main/sample/src/iosMain/kotlin/com/example/myapplication/MainViewController.kt"
    click WebSample "https://github.com/thereprator/kvideo-player/blob/main/sample/src/webMain/kotlin/main.kt"

    %% Styles
    classDef common fill:#D0E8FF,stroke:#005B96,color:#003F63
    classDef platform fill:#DFF5D0,stroke:#4B8B3B,color:#2F5D2A
    classDef native fill:#FFE7C0,stroke:#D28C00,color:#8C5E00
    classDef sample fill:#E0E0E0,stroke:#888888,color:#333333
```
