kithara

Facade crate for the kithara audio engine. Auto-detects source type from URL (.m3u8 = HLS, everything else = progressive file) and exposes a type-erased Resource with a simple read()/seek() interface. Re-exports all sub-crates as modules for convenient access to the full stack.

Usage

use kithara::prelude::*;

// Auto-detect from URL
let config = ResourceConfig::new("https://example.com/song.mp3")?;
let mut resource = Resource::new(config).await?;

let spec = resource.spec();
let mut buf = [0.0f32; 1024];
while !resource.is_eof() {
    let n = resource.read(&mut buf);
    play(&buf[..n]);
}

Architecture

%%{init: {"flowchart": {"curve": "linear"}} }%%
flowchart TD
    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[Application]

    AH -. "Event (Audio + Hls)" .-> EV[EventBus<br/>broadcast]
    AF -. "Event (Audio + File)" .-> EV
    EV -.-> APP

Resource wraps Box<dyn PcmReader> with a shared EventBus for all events (audio, stream, HLS).

Features

Key Types

Re-exports

The crate re-exports each engine sub-crate as a public 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 and only appear when the corresponding feature is enabled. A prelude module aggregates the most commonly used types from those re-exports.

Integration

Most consumers depend on kithara with the default features and call Resource::new(ResourceConfig::new(url)?).await? rather than wiring sub-crates manually. For embedded or wasm builds, disable the defaults and pick the minimal feature set.