# umbrella22/vesper architecture

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

- Interactive diagram: https://gitdiagram.com/umbrella22/vesper
- Repository: https://github.com/umbrella22/vesper

## Overview

Vesper is a native-first cross-platform playback SDK. An app integrates a platform host, supplies media, and controls playback; native mobile stacks or the desktop Rust pipeline perform playback while shared Rust modules align runtime semantics. The repository also provides offline downloads, playlists, preload, plugin extension, rendering, and Android external playback. Edges reflect README-documented relationships and the sampled iOS native-frame command flow; unsampled subsystem wiring is intentionally not inferred.

Main entry points: [`crates/core/player-runtime/src/lib.rs`](https://github.com/umbrella22/vesper/blob/main/crates/core/player-runtime/src/lib.rs) (Playback runtime), [`crates/platform/mobile/player-platform-android/src/lib.rs`](https://github.com/umbrella22/vesper/blob/main/crates/platform/mobile/player-platform-android/src/lib.rs) (Android host kit), [`crates/platform/mobile/player-platform-ios/src/lib.rs`](https://github.com/umbrella22/vesper/blob/main/crates/platform/mobile/player-platform-ios/src/lib.rs) (iOS host kit), [`crates/platform/desktop/player-host-desktop/src/lib.rs`](https://github.com/umbrella22/vesper/blob/main/crates/platform/desktop/player-host-desktop/src/lib.rs) (Desktop host)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_hosts["Host integrations"]
  node_android["Android host kit<br/>[lib.rs]"]
  node_ios["iOS host kit<br/>[lib.rs]"]
  node_desktop["Desktop host<br/>[lib.rs]"]
  node_ffi["C ABI<br/>[lib.rs]"]
end

subgraph group_playback["Playback runtime"]
  node_runtime["Playback runtime<br/>[lib.rs]"]
  node_model["Session model<br/>[lib.rs]"]
  node_native["Native media stacks"]
  node_backend["FFmpeg backend<br/>[lib.rs]"]
  node_audio["CPAL audio output<br/>[lib.rs]"]
  node_render["WGPU renderer<br/>[lib.rs]"]
end

subgraph group_media["Media workflows"]
  node_playlist["Playlist coordination<br/>[lib.rs]"]
  node_preload["Preload policy<br/>[lib.rs]"]
  node_download["Offline downloads<br/>[lib.rs]"]
  node_dashhls["DASH HLS bridge<br/>[lib.rs]"]
end

subgraph group_extensions["Extensions"]
  node_plugins["Plugin contracts<br/>[lib.rs]"]
  node_loader["Plugin loader<br/>[lib.rs]"]
  node_decoder["Decoder plugins<br/>[lib.rs]"]
  node_plugincli["Plugin CLI<br/>[main.rs]"]
end

subgraph group_external["External playback"]
  node_externalctl["External playback"]
  node_cast["Cast and DLNA"]
  node_relay["Local HTTP relay"]
end

node_app(("Host application"))
node_source["Media source"]

node_app -->|"integrates"| node_android
node_app -->|"integrates"| node_ios
node_app -->|"integrates"| node_desktop
node_app -->|"calls"| node_ffi
node_android -->|"uses Media3"| node_native
node_ios -->|"uses AVPlayer"| node_native
node_desktop -->|"hosts"| node_runtime
node_android -->|"shares semantics"| node_runtime
node_ios -->|"shares semantics"| node_runtime
node_ffi -->|"exposes"| node_runtime
node_runtime -->|"tracks sessions"| node_model
node_desktop -->|"uses"| node_backend
node_backend -.->|"outputs audio"| node_audio
node_backend -.->|"renders video"| node_render
node_source -->|"provides media"| node_android
node_source -->|"provides media"| node_ios
node_source -->|"provides media"| node_desktop
node_runtime -->|"coordinates"| node_playlist
node_runtime -->|"applies policy"| node_preload
node_app -->|"requests download"| node_download
node_download -->|"fetches media"| node_source
node_download -->|"bridges manifests"| node_dashhls
node_plugins -->|"defines loadable contracts"| node_loader
node_loader -->|"loads plugin"| node_decoder
node_app -->|"manages plugins"| node_plugincli
node_app -.->|"requests routing"| node_externalctl
node_externalctl -.->|"discovers and controls"| node_cast
node_externalctl -.->|"serves adapted source"| node_relay

click node_android "https://github.com/umbrella22/vesper/blob/main/crates/platform/mobile/player-platform-android/src/lib.rs"
click node_ios "https://github.com/umbrella22/vesper/blob/main/crates/platform/mobile/player-platform-ios/src/lib.rs"
click node_desktop "https://github.com/umbrella22/vesper/blob/main/crates/platform/desktop/player-host-desktop/src/lib.rs"
click node_ffi "https://github.com/umbrella22/vesper/blob/main/crates/ffi/player-ffi/src/lib.rs"
click node_runtime "https://github.com/umbrella22/vesper/blob/main/crates/core/player-runtime/src/lib.rs"
click node_model "https://github.com/umbrella22/vesper/blob/main/crates/model/player-model/src/lib.rs"
click node_backend "https://github.com/umbrella22/vesper/blob/main/crates/backend/player-backend-ffmpeg/src/lib.rs"
click node_audio "https://github.com/umbrella22/vesper/blob/main/crates/audio/player-audio-cpal/src/lib.rs"
click node_render "https://github.com/umbrella22/vesper/blob/main/crates/render/player-render-wgpu/src/lib.rs"
click node_playlist "https://github.com/umbrella22/vesper/blob/main/crates/core/player-playlist/src/lib.rs"
click node_preload "https://github.com/umbrella22/vesper/blob/main/crates/core/player-preload/src/lib.rs"
click node_download "https://github.com/umbrella22/vesper/blob/main/crates/core/player-download/src/lib.rs"
click node_dashhls "https://github.com/umbrella22/vesper/blob/main/crates/core/player-dash-hls-bridge/src/lib.rs"
click node_plugins "https://github.com/umbrella22/vesper/blob/main/crates/plugin/player-plugin/src/lib.rs"
click node_loader "https://github.com/umbrella22/vesper/blob/main/crates/plugin/player-plugin-loader/src/lib.rs"
click node_decoder "https://github.com/umbrella22/vesper/blob/main/crates/plugin-decoder/player-decoder-mediacodec/src/lib.rs"
click node_plugincli "https://github.com/umbrella22/vesper/blob/main/crates/tools/player-cli/src/main.rs"
click node_externalctl "https://github.com/umbrella22/vesper/blob/main/lib/android/vesper-player-kit-external-playback/src/main/java/io/github/umbrella22/vesper/player/android/external/VesperExternalPlaybackController.kt"
click node_relay "https://github.com/umbrella22/vesper/blob/main/lib/android/vesper-player-kit-external-playback/src/main/java/io/github/umbrella22/vesper/player/android/external/internal/relay/VesperRelayServer.kt"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_android,node_ios,node_desktop,node_ffi toneBlue
class node_runtime,node_model,node_native,node_backend,node_audio,node_render toneAmber
class node_playlist,node_preload,node_download,node_dashhls toneMint
class node_plugins,node_loader,node_decoder,node_plugincli toneRose
class node_externalctl,node_cast,node_relay,node_app,node_source toneIndigo
```

## Components

### Host integrations

- [Android host kit](https://github.com/umbrella22/vesper/blob/main/crates/platform/mobile/player-platform-android/src/lib.rs): `crates/platform/mobile/player-platform-android/src/lib.rs`
- [iOS host kit](https://github.com/umbrella22/vesper/blob/main/crates/platform/mobile/player-platform-ios/src/lib.rs): `crates/platform/mobile/player-platform-ios/src/lib.rs`
- [Desktop host](https://github.com/umbrella22/vesper/blob/main/crates/platform/desktop/player-host-desktop/src/lib.rs): `crates/platform/desktop/player-host-desktop/src/lib.rs`
- [C ABI](https://github.com/umbrella22/vesper/blob/main/crates/ffi/player-ffi/src/lib.rs): `crates/ffi/player-ffi/src/lib.rs`

### Playback runtime

- [Playback runtime](https://github.com/umbrella22/vesper/blob/main/crates/core/player-runtime/src/lib.rs): `crates/core/player-runtime/src/lib.rs`
- [Session model](https://github.com/umbrella22/vesper/blob/main/crates/model/player-model/src/lib.rs): `crates/model/player-model/src/lib.rs`
- **Native media stacks**
- [FFmpeg backend](https://github.com/umbrella22/vesper/blob/main/crates/backend/player-backend-ffmpeg/src/lib.rs): `crates/backend/player-backend-ffmpeg/src/lib.rs`
- [CPAL audio output](https://github.com/umbrella22/vesper/blob/main/crates/audio/player-audio-cpal/src/lib.rs): `crates/audio/player-audio-cpal/src/lib.rs`
- [WGPU renderer](https://github.com/umbrella22/vesper/blob/main/crates/render/player-render-wgpu/src/lib.rs): `crates/render/player-render-wgpu/src/lib.rs`

### Media workflows

- [Playlist coordination](https://github.com/umbrella22/vesper/blob/main/crates/core/player-playlist/src/lib.rs): `crates/core/player-playlist/src/lib.rs`
- [Preload policy](https://github.com/umbrella22/vesper/blob/main/crates/core/player-preload/src/lib.rs): `crates/core/player-preload/src/lib.rs`
- [Offline downloads](https://github.com/umbrella22/vesper/blob/main/crates/core/player-download/src/lib.rs): `crates/core/player-download/src/lib.rs`
- [DASH HLS bridge](https://github.com/umbrella22/vesper/blob/main/crates/core/player-dash-hls-bridge/src/lib.rs): `crates/core/player-dash-hls-bridge/src/lib.rs`

### Extensions

- [Plugin contracts](https://github.com/umbrella22/vesper/blob/main/crates/plugin/player-plugin/src/lib.rs): `crates/plugin/player-plugin/src/lib.rs`
- [Plugin loader](https://github.com/umbrella22/vesper/blob/main/crates/plugin/player-plugin-loader/src/lib.rs): `crates/plugin/player-plugin-loader/src/lib.rs`
- [Decoder plugins](https://github.com/umbrella22/vesper/blob/main/crates/plugin-decoder/player-decoder-mediacodec/src/lib.rs): `crates/plugin-decoder/player-decoder-mediacodec/src/lib.rs`
- [Plugin CLI](https://github.com/umbrella22/vesper/blob/main/crates/tools/player-cli/src/main.rs): `crates/tools/player-cli/src/main.rs`

### External playback

- [External playback](https://github.com/umbrella22/vesper/blob/main/lib/android/vesper-player-kit-external-playback/src/main/java/io/github/umbrella22/vesper/player/android/external/VesperExternalPlaybackController.kt): `lib/android/vesper-player-kit-external-playback/src/main/java/io/github/umbrella22/vesper/player/android/external/VesperExternalPlaybackController.kt`
- **Cast and DLNA**
- [Local HTTP relay](https://github.com/umbrella22/vesper/blob/main/lib/android/vesper-player-kit-external-playback/src/main/java/io/github/umbrella22/vesper/player/android/external/internal/relay/VesperRelayServer.kt): `lib/android/vesper-player-kit-external-playback/src/main/java/io/github/umbrella22/vesper/player/android/external/internal/relay/VesperRelayServer.kt`

### Other components

- **Host application**
- **Media source**

## Connections

- Host application → Android host kit: integrates
- Host application → iOS host kit: integrates
- Host application → Desktop host: integrates
- Host application → C ABI: calls
- Android host kit → Native media stacks: uses Media3
- iOS host kit → Native media stacks: uses AVPlayer
- Desktop host → Playback runtime: hosts
- Android host kit → Playback runtime: shares semantics
- iOS host kit → Playback runtime: shares semantics
- C ABI → Playback runtime: exposes
- Playback runtime → Session model: tracks sessions
- Desktop host → FFmpeg backend: uses
- FFmpeg backend → CPAL audio output: outputs audio
- FFmpeg backend → WGPU renderer: renders video
- Media source → Android host kit: provides media
- Media source → iOS host kit: provides media
- Media source → Desktop host: provides media
- Playback runtime → Playlist coordination: coordinates
- Playback runtime → Preload policy: applies policy
- Host application → Offline downloads: requests download
- Offline downloads → Media source: fetches media
- Offline downloads → DASH HLS bridge: bridges manifests
- Plugin contracts → Plugin loader: defines loadable contracts
- Plugin loader → Decoder plugins: loads plugin
- Host application → Plugin CLI: manages plugins
- Host application → External playback: requests routing
- External playback → Cast and DLNA: discovers and controls
- External playback → Local HTTP relay: serves adapted source