kithara

A streaming audio engine for Rust. Point it at a URL and it plays: .m3u8 streams adaptively over HLS, everything else downloads progressively. One Resource type gives you a unified PCM read/seek interface. The player engine underneath adds multi-deck mixing, crossfade, and parametric EQ for DJ and pro-audio apps.

• Auto-detecting — HLS for .m3u8, progressive download otherwise.
• Adaptive bitrate for HLS, with segment caching and offline playback.
• Gapless decode across MP3, AAC (incl. HE-AAC), FLAC, ALAC, WAV, Opus, Vorbis.
• Hardware or software decode — Apple AudioToolbox and Android MediaCodec backends, or the cross-platform Symphonia software decoder.
• DRM — AES-128 decryption for protected HLS.

Usage

use kithara::prelude::*;

let config = ResourceConfig::new("https://example.com/song.mp3")?;
let mut resource = Resource::new(config).await?;
resource.preload().await?;

let mut buf = [0.0f32; 1024];
loop {
    match resource.read(&mut buf)? {
        ReadOutcome::Frames { count, .. } => play(&buf[..count.get()]),
        ReadOutcome::Pending { .. } => continue, // buffering / seeking
        ReadOutcome::Eof { .. } => break,
    }
}

Resource is a type-erased Box<dyn PcmReader>: the same read() / seek() interface whether the source is HLS, a remote file, or a local path.

Architecture

%%{init: {"flowchart": {"curve": "linear"}} }%%
flowchart LR
    RC[ResourceConfig] -->|auto-detect| R[Resource]
    R -->|".m3u8"| AH["Audio‹Stream‹Hls››"]
    R -->|other| AF["Audio‹Stream‹File››"]
    AH --> PR["Box‹dyn PcmReader›"]
    AF --> PR
    PR -->|"read / seek"| APP[Your audio callback]

PCM flows straight from the decoder to your callback through read(). The optional EventBus (resource.event_bus()) is a side-channel for observability — decode progress, buffering, HLS variant switches — and never sits in the audio path.

Features

Key Types

Re-exports

Each engine layer is re-exported as a module: kithara::audio, kithara::bufpool, kithara::decode, kithara::events, kithara::platform, kithara::play, kithara::stream. The file/hls/assets/net/storage modules are feature-gated. For advanced control — multi-slot engine, crossfade, EQ — reach into kithara::play (Engine, Player, CrossfadeConfig, Equalizer). The prelude collects the everyday types.

Integration

Most consumers depend on kithara with default features and call Resource::new(ResourceConfig::new(url)?).await?. For wasm or embedded builds, disable defaults and pick a minimal feature set (e.g. file + symphonia).