# zvuk/kithara architecture

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

- Interactive diagram: https://gitdiagram.com/zvuk/kithara
- Repository: https://github.com/zvuk/kithara

## Overview

#### Purpose and entry points
Kithara is a Rust workspace for modular audio playback: progressive HTTP and HLS VOD ingestion, cache-backed decoding, real-time playback/mixing, DRM, and platform bindings. The primary library facade is `crates/kithara/src/lib.rs`. Runnable entry points are the native DJ studio in `crates/kithara-app/src/main.rs` and the browser/WASM surface in `crates/kithara-ffi/src/web/mod.rs`; Android and Apple SDK wrappers live under `android/lib/src/main/kotlin/com/kithara/Kithara.kt` and `apple/Sources/Kithara/KitharaPlayer.swift`.

#### Public playback orchestration
`kithara-play` owns the AVPlayer-like control plane: player state, playlist/item transitions, resource construction, policy enforcement, and command bridging into real-time processing. Its engine/session boundary separates asynchronous orchestration from the RT renderer. Core paths: `crates/kithara-play/src/player/core.rs`, `crates/kithara-play/src/engine/core.rs`, `crates/kithara-play/src/rt/processor.rs`.

#### Source acquisition and adaptive streaming
Progressive sources use pull-driven download sessions; HLS parses master/variant playlists, resolves and fetches segments, supports seeking and variant lifecycle. ABR estimates bandwidth and publishes switching decisions. Data crosses from network streams into readers/resources consumed by decoding. Core paths: `crates/kithara-file/src/session/mod.rs`, `crates/kithara-hls/src/stream/hls.rs`, `crates/kithara-hls/src/variant/core.rs`, `crates/kithara-abr/src/abr.rs`.

#### Network, DRM, and persistent assets
`kithara-net` abstracts HTTP across native, Apple URLSession, and browser Fetch, including retries/timeouts/metrics. `kithara-drm` provides cipher contexts and decryption; HLS has a decrypt processor. `kithara-assets` provides the persistent cache contract: disk/memory backends, leases/pins, LRU eviction, and crash-safe index persistence. Core paths: `crates/kithara-net/src/client.rs`, `crates/kithara-drm/src/decrypt.rs`, `crates/kithara-hls/src/decrypt_processor.rs`, `crates/kithara-assets/src/store/builder.rs`, `crates/kithara-assets/src/index/persistence/atomic.rs`.

#### Decode and audio pipeline
Readers feed decoder factories that select software Symphonia or native Android/Apple/WebCodecs backends. Decoded PCM flows through track state machines, resampling, time-stretch/EQ/limiter effects, and fixed-buffer renderer/runtime components. Buffer pooling is a dedicated subsystem to avoid allocation in hot paths. Core paths: `crates/kithara-decode/src/factory/mod.rs`, `crates/kithara-audio/src/pipeline/decode/core.rs`, `crates/kithara-audio/src/renderer/node.rs`, `crates/kithara-resampler/src/factory.rs`, `crates/kithara-bufpool/src/pool/core.rs`.

#### Application and UI layer
The native app composes catalog, decks, mixing/crossfade, waveform/analysis, and a declarative UI. `kithara-ui` compiles RON layout/module/skin documents into render trees and interactive widgets; it is a separate UI system rather than a web frontend. Core paths: `crates/kithara-app/src/frontend.rs`, `crates/kithara-app/src/gui/app.rs`, `crates/kithara-ui/src/compile.rs`, `crates/kithara-ui/src/render/tree/mod.rs`.

#### Platform and delivery boundaries
Rust targets native, Android, Apple, and WASM. Platform primitives centralize cancellation, synchronization, time, task/runtime selection, and deterministic/loom-like modes rather than allowing direct runtime use throughout the workspace. Native decoding uses AudioToolbox and MediaCodec; networking uses URLSession, Reqwest/native backends, or Fetch. FFI exposes the engine to Swift/Kotlin and browser JS. Core paths: `crates/kithara-platform/src/lib.rs`, `crates/kithara-decode/src/apple/mod.rs`, `crates/kithara-decode/src/android/mod.rs`, `crates/kithara-ffi/src/player/facade.rs`.

Main entry points: [`crates/kithara-hls/src/stream/hls.rs`](https://github.com/zvuk/kithara/blob/main/crates/kithara-hls/src/stream/hls.rs) (HLS stream), [`crates/kithara-play/src/player/core.rs`](https://github.com/zvuk/kithara/blob/main/crates/kithara-play/src/player/core.rs) (Player control), [`crates/kithara-file/src/session/mod.rs`](https://github.com/zvuk/kithara/blob/main/crates/kithara-file/src/session/mod.rs) (Progressive session), [`crates/kithara-decode/src/factory/mod.rs`](https://github.com/zvuk/kithara/blob/main/crates/kithara-decode/src/factory/mod.rs) (Decoder factory)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry surfaces"]
  node_facade["Kithara facade<br/>Rust library<br/>[lib.rs]"]
  node_native_app["Native DJ studio<br/>native app<br/>[main.rs]"]
  node_web["Browser/WASM API<br/>WASM surface<br/>[mod.rs]"]
  node_android_sdk["Android SDK<br/>Kotlin wrapper<br/>[Kithara.kt]"]
  node_apple_sdk["Apple SDK<br/>Swift wrapper"]
end

subgraph group_control["Playback control"]
  node_player["Player control<br/>playback orchestration<br/>[core.rs]"]
  node_engine["Engine session<br/>async/RT boundary<br/>[core.rs]"]
  node_rt_processor["RT processor<br/>real-time renderer<br/>[processor.rs]"]
end

subgraph group_ingest["Ingestion and assets"]
  node_file_session["Progressive session<br/>pull downloader<br/>[mod.rs]"]
  node_hls_stream["HLS stream<br/>playlist ingestion<br/>[hls.rs]"]
  node_variant["HLS variant lifecycle<br/>adaptive variant<br/>[core.rs]"]
  node_abr["ABR controller<br/>bandwidth adaptation<br/>[abr.rs]"]
  node_net["HTTP client<br/>cross-platform HTTP<br/>[client.rs]"]
  node_assets[("Asset store<br/>persistent cache<br/>[builder.rs]")]
  node_hls_decrypt["HLS decrypt<br/>stream processor"]
  node_drm["DRM decryptor<br/>cipher contexts<br/>[decrypt.rs]"]
end

subgraph group_audio["Decode and real-time audio"]
  node_decoder["Decoder factory<br/>decoder selection<br/>[mod.rs]"]
  node_audio_pipeline["Audio pipeline<br/>PCM track pipeline<br/>[core.rs]"]
  node_renderer["Audio renderer<br/>fixed-buffer runtime<br/>[node.rs]"]
  node_bufpool["Buffer pool<br/>real-time memory<br/>[core.rs]"]
end

subgraph group_platform["Platform and delivery"]
  node_platform["Platform primitives<br/>runtime abstraction<br/>[lib.rs]"]
  node_ffi["Player FFI facade<br/>native bindings<br/>[facade.rs]"]
end

subgraph group_app["Studio UI"]
  node_studio["Studio frontend<br/>DJ application<br/>[frontend.rs]"]
  node_ui_compile["UI compiler<br/>[compile.rs]"]
  node_ui_tree["UI render tree<br/>interactive UI<br/>[mod.rs]"]
end

node_facade -->|"public playback API"| node_player
node_native_app -->|"starts"| node_studio
node_studio -->|"deck controls"| node_player
node_studio -->|"builds UI"| node_ui_compile
node_ui_compile -->|"renders as"| node_ui_tree
node_web -->|"browser calls"| node_ffi
node_android_sdk -->|"Kotlin calls"| node_ffi
node_apple_sdk -->|"Swift calls"| node_ffi
node_ffi -->|"controls"| node_player
node_player -->|"creates session"| node_engine
node_engine -->|"commands"| node_rt_processor
node_player -->|"progressive resource"| node_file_session
node_player -->|"HLS resource"| node_hls_stream
node_hls_stream -->|"manages"| node_variant
node_variant -->|"switch decisions"| node_abr
node_file_session -->|"HTTP reads"| node_net
node_hls_stream -->|"playlist and segments"| node_net
node_file_session -->|"cached bytes"| node_assets
node_hls_stream -->|"cached segments"| node_assets
node_hls_stream -->|"encrypted segments"| node_hls_decrypt
node_hls_decrypt -->|"cipher context"| node_drm
node_file_session -->|"reader"| node_decoder
node_hls_stream -->|"reader"| node_decoder
node_decoder -->|"PCM"| node_audio_pipeline
node_audio_pipeline -->|"tracks"| node_rt_processor
node_rt_processor -->|"render buffers"| node_renderer
node_bufpool -->|"pooled buffers"| node_audio_pipeline
node_platform -.->|"runtime primitives"| node_net
node_platform -.->|"tasks and sync"| node_engine
node_platform -.->|"platform backends"| node_decoder

click node_facade "https://github.com/zvuk/kithara/blob/main/crates/kithara/src/lib.rs"
click node_native_app "https://github.com/zvuk/kithara/blob/main/crates/kithara-app/src/main.rs"
click node_web "https://github.com/zvuk/kithara/blob/main/crates/kithara-ffi/src/web/mod.rs"
click node_android_sdk "https://github.com/zvuk/kithara/blob/main/android/lib/src/main/kotlin/com/kithara/Kithara.kt"
click node_apple_sdk "https://github.com/zvuk/kithara/blob/main/apple/Sources/Kithara/KitharaPlayer.swift"
click node_player "https://github.com/zvuk/kithara/blob/main/crates/kithara-play/src/player/core.rs"
click node_engine "https://github.com/zvuk/kithara/blob/main/crates/kithara-play/src/engine/core.rs"
click node_rt_processor "https://github.com/zvuk/kithara/blob/main/crates/kithara-play/src/rt/processor.rs"
click node_file_session "https://github.com/zvuk/kithara/blob/main/crates/kithara-file/src/session/mod.rs"
click node_hls_stream "https://github.com/zvuk/kithara/blob/main/crates/kithara-hls/src/stream/hls.rs"
click node_variant "https://github.com/zvuk/kithara/blob/main/crates/kithara-hls/src/variant/core.rs"
click node_abr "https://github.com/zvuk/kithara/blob/main/crates/kithara-abr/src/abr.rs"
click node_net "https://github.com/zvuk/kithara/blob/main/crates/kithara-net/src/client.rs"
click node_assets "https://github.com/zvuk/kithara/blob/main/crates/kithara-assets/src/store/builder.rs"
click node_hls_decrypt "https://github.com/zvuk/kithara/blob/main/crates/kithara-hls/src/decrypt_processor.rs"
click node_drm "https://github.com/zvuk/kithara/blob/main/crates/kithara-drm/src/decrypt.rs"
click node_decoder "https://github.com/zvuk/kithara/blob/main/crates/kithara-decode/src/factory/mod.rs"
click node_audio_pipeline "https://github.com/zvuk/kithara/blob/main/crates/kithara-audio/src/pipeline/decode/core.rs"
click node_renderer "https://github.com/zvuk/kithara/blob/main/crates/kithara-audio/src/renderer/node.rs"
click node_bufpool "https://github.com/zvuk/kithara/blob/main/crates/kithara-bufpool/src/pool/core.rs"
click node_platform "https://github.com/zvuk/kithara/blob/main/crates/kithara-platform/src/lib.rs"
click node_ffi "https://github.com/zvuk/kithara/blob/main/crates/kithara-ffi/src/player/facade.rs"
click node_studio "https://github.com/zvuk/kithara/blob/main/crates/kithara-app/src/frontend.rs"
click node_ui_compile "https://github.com/zvuk/kithara/blob/main/crates/kithara-ui/src/compile.rs"
click node_ui_tree "https://github.com/zvuk/kithara/blob/main/crates/kithara-ui/src/render/tree/mod.rs"

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_facade,node_native_app,node_web,node_android_sdk,node_apple_sdk toneBlue
class node_player,node_engine,node_rt_processor toneAmber
class node_file_session,node_hls_stream,node_variant,node_abr,node_net,node_assets,node_hls_decrypt,node_drm toneMint
class node_decoder,node_audio_pipeline,node_renderer,node_bufpool toneRose
class node_platform,node_ffi toneIndigo
class node_studio,node_ui_compile,node_ui_tree toneTeal
```

## Components

### Entry surfaces

- [Kithara facade](https://github.com/zvuk/kithara/blob/main/crates/kithara/src/lib.rs): Rust library · Primary public library surface. · `crates/kithara/src/lib.rs`
- [Native DJ studio](https://github.com/zvuk/kithara/blob/main/crates/kithara-app/src/main.rs): native app · `crates/kithara-app/src/main.rs`
- [Browser/WASM API](https://github.com/zvuk/kithara/blob/main/crates/kithara-ffi/src/web/mod.rs): WASM surface · `crates/kithara-ffi/src/web/mod.rs`
- [Android SDK](https://github.com/zvuk/kithara/blob/main/android/lib/src/main/kotlin/com/kithara/Kithara.kt): Kotlin wrapper · `android/lib/src/main/kotlin/com/kithara/Kithara.kt`
- [Apple SDK](https://github.com/zvuk/kithara/blob/main/apple/Sources/Kithara/KitharaPlayer.swift): Swift wrapper · `apple/Sources/Kithara/KitharaPlayer.swift`

### Playback control

- [Player control](https://github.com/zvuk/kithara/blob/main/crates/kithara-play/src/player/core.rs): playback orchestration · Owns state, playlists, policies, and resource construction. · `crates/kithara-play/src/player/core.rs`
- [Engine session](https://github.com/zvuk/kithara/blob/main/crates/kithara-play/src/engine/core.rs): async/RT boundary · Bridges control commands into the renderer. · `crates/kithara-play/src/engine/core.rs`
- [RT processor](https://github.com/zvuk/kithara/blob/main/crates/kithara-play/src/rt/processor.rs): real-time renderer · `crates/kithara-play/src/rt/processor.rs`

### Ingestion and assets

- [Progressive session](https://github.com/zvuk/kithara/blob/main/crates/kithara-file/src/session/mod.rs): pull downloader · `crates/kithara-file/src/session/mod.rs`
- [HLS stream](https://github.com/zvuk/kithara/blob/main/crates/kithara-hls/src/stream/hls.rs): playlist ingestion · Parses playlists and resolves segment reads. · `crates/kithara-hls/src/stream/hls.rs`
- [HLS variant lifecycle](https://github.com/zvuk/kithara/blob/main/crates/kithara-hls/src/variant/core.rs): adaptive variant · `crates/kithara-hls/src/variant/core.rs`
- [ABR controller](https://github.com/zvuk/kithara/blob/main/crates/kithara-abr/src/abr.rs): bandwidth adaptation · `crates/kithara-abr/src/abr.rs`
- [HTTP client](https://github.com/zvuk/kithara/blob/main/crates/kithara-net/src/client.rs): cross-platform HTTP · Provides retries, timeouts, and metrics. · `crates/kithara-net/src/client.rs`
- [Asset store](https://github.com/zvuk/kithara/blob/main/crates/kithara-assets/src/store/builder.rs): persistent cache · Cache contract with leases, eviction, and durable index. · `crates/kithara-assets/src/store/builder.rs`
- [HLS decrypt](https://github.com/zvuk/kithara/blob/main/crates/kithara-hls/src/decrypt_processor.rs): stream processor · `crates/kithara-hls/src/decrypt_processor.rs`
- [DRM decryptor](https://github.com/zvuk/kithara/blob/main/crates/kithara-drm/src/decrypt.rs): cipher contexts · `crates/kithara-drm/src/decrypt.rs`

### Decode and real-time audio

- [Decoder factory](https://github.com/zvuk/kithara/blob/main/crates/kithara-decode/src/factory/mod.rs): decoder selection · Selects software and platform decoder backends. · `crates/kithara-decode/src/factory/mod.rs`
- [Audio pipeline](https://github.com/zvuk/kithara/blob/main/crates/kithara-audio/src/pipeline/decode/core.rs): PCM track pipeline · Track state, resampling, and effects processing. · `crates/kithara-audio/src/pipeline/decode/core.rs`
- [Audio renderer](https://github.com/zvuk/kithara/blob/main/crates/kithara-audio/src/renderer/node.rs): fixed-buffer runtime · `crates/kithara-audio/src/renderer/node.rs`
- [Buffer pool](https://github.com/zvuk/kithara/blob/main/crates/kithara-bufpool/src/pool/core.rs): real-time memory · Avoids hot-path allocations. · `crates/kithara-bufpool/src/pool/core.rs`

### Platform and delivery

- [Platform primitives](https://github.com/zvuk/kithara/blob/main/crates/kithara-platform/src/lib.rs): runtime abstraction · Centralizes tasks, cancellation, synchronization, and time. · `crates/kithara-platform/src/lib.rs`
- [Player FFI facade](https://github.com/zvuk/kithara/blob/main/crates/kithara-ffi/src/player/facade.rs): native bindings · `crates/kithara-ffi/src/player/facade.rs`

### Studio UI

- [Studio frontend](https://github.com/zvuk/kithara/blob/main/crates/kithara-app/src/frontend.rs): DJ application · Composes catalog, decks, mixing, and analysis. · `crates/kithara-app/src/frontend.rs`
- [UI compiler](https://github.com/zvuk/kithara/blob/main/crates/kithara-ui/src/compile.rs): RON UI compiler · Compiles layout, module, and skin documents. · `crates/kithara-ui/src/compile.rs`
- [UI render tree](https://github.com/zvuk/kithara/blob/main/crates/kithara-ui/src/render/tree/mod.rs): interactive UI · `crates/kithara-ui/src/render/tree/mod.rs`

## Connections

- Kithara facade → Player control: public playback API
- Native DJ studio → Studio frontend: starts
- Studio frontend → Player control: deck controls
- Studio frontend → UI compiler: builds UI
- UI compiler → UI render tree: renders as
- Browser/WASM API → Player FFI facade: browser calls
- Android SDK → Player FFI facade: Kotlin calls
- Apple SDK → Player FFI facade: Swift calls
- Player FFI facade → Player control: controls
- Player control → Engine session: creates session
- Engine session → RT processor: commands
- Player control → Progressive session: progressive resource
- Player control → HLS stream: HLS resource
- HLS stream → HLS variant lifecycle: manages
- HLS variant lifecycle → ABR controller: switch decisions
- Progressive session → HTTP client: HTTP reads
- HLS stream → HTTP client: playlist and segments
- Progressive session → Asset store: cached bytes
- HLS stream → Asset store: cached segments
- HLS stream → HLS decrypt: encrypted segments
- HLS decrypt → DRM decryptor: cipher context
- Progressive session → Decoder factory: reader
- HLS stream → Decoder factory: reader
- Decoder factory → Audio pipeline: PCM
- Audio pipeline → RT processor: tracks
- RT processor → Audio renderer: render buffers
- Buffer pool → Audio pipeline: pooled buffers
- Platform primitives → HTTP client: runtime primitives
- Platform primitives → Engine session: tasks and sync
- Platform primitives → Decoder factory: platform backends