zvuk/kithara

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.