kithara

Open-source modular audio engine in Rust. Contributions and reviews are welcome.

Status: active development. Public APIs are intended to remain stable within a release line, while internal implementation may evolve. Pin exact versions for production use.

Modular audio engine in Rust. Streams, decodes, and plays audio from progressive HTTP and HLS sources with persistent caching and offline support. Designed as an open-source alternative to AVPlayer with DJ-grade mixing capabilities — multi-slot playback, crossfading, BPM sync, and per-channel EQ.

Components are independent crates that can be used standalone or composed into a full player.

Features

• Player engine — AVPlayer-style API with multi-slot arena, crossfading, BPM sync, and per-channel EQ (kithara-play)
• Progressive file download — stream MP3, AAC, FLAC and other formats over HTTP with disk caching and gap filling
• HLS VOD — adaptive bitrate streaming with variant switching, encrypted segments (AES-128-CBC), and offline support
• Multi-backend decoding — Symphonia (software, cross-platform) and Apple AudioToolbox (hardware, macOS/iOS)
• Audio pipeline — sample rate conversion via rubato, effects chain, OS-thread worker with backpressure
• Persistent disk cache — lease/pin semantics, LRU eviction, crash-safe writes
• Zero-allocation hot paths — sharded buffer pool for decode and I/O loops
• WASM support — browser playback bindings with shared-memory threading

Architecture

%%{init: {"flowchart": {"curve": "linear"}} }%%
flowchart LR
    apps["Apps<br/>kithara-app + kithara-ui + kithara-tui + kithara-wasm"]
    facade["Facade<br/>kithara + kithara-play"]
    pipeline["Pipeline<br/>audio + decode + events"]
    protocols["Protocols<br/>file + hls + abr + drm"]
    io["I/O<br/>stream + net"]
    storage["Storage<br/>assets + storage"]
    infra["Infra<br/>bufpool + platform + hang-detector"]
    tooling["Tooling<br/>test-macros + wasm-macros + test-utils + tests"]

    apps --> facade
    facade --> pipeline --> protocols --> io --> storage --> infra
    tooling -.-> facade
    tooling -.-> apps

    style apps fill:#4f6d7a,color:#fff
    style facade fill:#4a6fa5,color:#fff
    style pipeline fill:#6b8cae,color:#fff
    style protocols fill:#7ea87e,color:#fff
    style io fill:#c4a35a,color:#fff
    style storage fill:#8b6b8b,color:#fff
    style infra fill:#5b8f8f,color:#fff
    style tooling fill:#7f7f7f,color:#fff

Loading

Layer	Crates	Role
Facade	kithara	Unified Resource API with auto-detection (file / HLS)
Player	kithara-play	AVPlayer-style traits: Engine, Player, Mixer, DJ subsystem
Pipeline	kithara-audio kithara-decode kithara-events	Threaded decode + effects + resampling, event bus
Protocols	kithara-file kithara-hls kithara-abr kithara-drm	HTTP progressive, HLS VOD with ABR, AES-128 decryption
I/O	kithara-stream kithara-net	Async-to-sync bridge (Read + Seek), HTTP with retry
Storage	kithara-assets kithara-storage	Disk cache with eviction, mmap/mem resources
Primitives	kithara-bufpool kithara-platform	Zero-alloc buffer pool, cross-platform sync types
Runtime Safety	kithara-hang-detector	Hang watchdog and loop guard macro used by runtime crates
Applications	kithara-app kithara-ui kithara-tui kithara-wasm	Desktop/TUI/WASM demo players built on shared engine crates
Macros	kithara-test-macros kithara-wasm-macros	Proc-macro glue for tests and wasm exports/thread guards
Testing	kithara-test-utils	Shared fixtures and helpers for workspace tests

Getting Started

# Install the task runner
cargo install just --locked

# Complete the environment setup from the section below
cargo build --workspace

# Test (nextest + doctests)
just test-all

# Lint / policy checks
just lint-fast
just lint-full

The day-to-day workflow for both humans and AI agents lives in .docs/workflow/rust-ai.md. Use .docs/plans/_template.md for non-trivial tasks.

Environment Setup

Set up both the host environment and the local tooling before relying on the just workflow.

Host Dependencies

• Linux: install libasound2-dev
• macOS: install Xcode Command Line Tools

Required Tooling

• cargo-nextest for just test*
• ast-grep for just lint-fast and just lint-full
• nightly rustfmt for just fmt and just fmt-check
• prek for the configured pre-commit and pre-push hooks

One reasonable setup is:

cargo install cargo-nextest --locked
cargo install ast-grep --locked
rustup toolchain install nightly --component rustfmt

Install prek with your preferred Python toolchain manager, for example:

python3 -m pip install --user prek
prek install -f

Recommended Tooling

• cargo-deny for dependency audits
• cargo-machete for unused dependency scans
• cargo-hack for feature-powerset checks
• cargo-semver-checks for public API compatibility checks

Example installation:

cargo install cargo-deny --locked
cargo install cargo-machete --locked
cargo install cargo-hack --locked
cargo install cargo-semver-checks --locked

Optional Tooling

• worktrunk as a convenience wrapper over git worktree
• wasm-slim for wasm size checks
• critcmp for benchmark comparison
• chromedriver or another WebDriver binary for browser-based flows

Demo Players

# Desktop GUI demo
cargo run -p kithara-app --bin kithara-gui -- <TRACK_URL_1> <TRACK_URL_2>

# Terminal demo
cargo run -p kithara-app --bin kithara-tui -- <TRACK_URL_1> <TRACK_URL_2>

# WASM demo player
cd crates/kithara-wasm
RUSTUP_TOOLCHAIN=nightly trunk serve --config Trunk.toml --port 8080

Examples

# Play a file with rodio
cargo run -p kithara --example resource_rodio --features rodio -- <URL_OR_PATH>

# Play a progressive file (interactive)
cargo run -p kithara --example file_audio --features rodio -- <URL>

# Play HLS stream (interactive)
cargo run -p kithara --example hls_audio --features rodio -- <MASTER_PLAYLIST_URL>

# Play encrypted HLS
cargo run -p kithara --example hls_drm_audio --features rodio -- <MASTER_PLAYLIST_URL>

# Crossfade from file to HLS
cargo run -p kithara --example player --features file,hls -- [FILE_URL] [HLS_URL]

Contributing

See CONTRIBUTING.md for development setup and .docs/workflow/rust-ai.md for the local-first task flow.

Rules

See AGENTS.md for coding rules enforced across the workspace.

Minimum Supported Rust Version (MSRV)

The current MSRV is 1.88 (Rust edition 2024). It is tested in CI and may be bumped in minor releases.

License

Licensed under either of

• Apache License, Version 2.0
• MIT License

at your option.