Struct Audio 

pub struct Audio<S> { /* private fields */ }

Generic audio pipeline running in a separate thread.

Provides a simple interface for reading decoded PCM audio, compatible with cpal and rodio audio backends.

Example

use kithara_audio::{Audio, AudioConfig};
use kithara_hls::{Hls, HlsConfig};
use kithara_stream::Stream;

let config = AudioConfig::<Hls>::new(hls_config)
    .hint("mp3");
let audio = Audio::<Stream<Hls>>::new(config).await?;

// Get audio format
let spec = audio.spec();
println!("{}Hz, {} channels", spec.sample_rate, spec.channels);

// Read PCM samples
let mut buf = [0.0f32; 1024];
loop {
    match audio.read(&mut buf)? {
        ReadOutcome::Frames { count, .. } => play_samples(&buf[..count]),
        ReadOutcome::Eof { .. } => break,
    }
}

Implementations

impl<S> Audio<S>

pub fn abr_handle(&self) -> Option<AbrHandle>

Runtime ABR handle (cloned from the stream’s source at construction). Some for adaptive sources (HLS), None for file/non-adaptive sources.

pub fn current_variant(&self) -> Option<VariantInfo>

Current variant’s metadata. Pulled live from the ABR peer on every call — no caching — so the UI never sees a stale label after an ABR switch. None for non-adaptive sources or peers that have not yet registered variants.

pub fn duration(&self) -> Option<Duration>

Get total duration of the audio stream.

Returns None for streaming sources where duration is unknown.

pub fn is_preloaded(&self) -> bool

Whether non-blocking recv is active.

Returns false after seek() until preload() is called again.

pub fn metadata(&self) -> &TrackMetadata

Get track metadata (title, artist, album, artwork).

pub fn position(&self) -> Duration

Get current playback position.

Calculated from samples read since last seek plus the seek base.

pub fn preload(&mut self) -> Result<(), DecodeError>

Enable non-blocking mode for read() and prime the first chunk.

After calling this, read() returns immediately from buffered data without blocking. Must be called after construction so that fill_buffer() calls from JS (via requestAnimationFrame) don’t hang.

Returns Err(DecodeError) if the producer channel closed during the initial fill_buffer (e.g. upstream decoder reported TrackStep::Failed before any data). Natural EOF encountered during preload is not surfaced here — the subsequent read() / next_chunk() call will report ReadOutcome::Eof.

Errors

Returns DecodeError::Io if the producer channel closed during preload.

pub fn read(&mut self, buf: &mut [f32]) -> Result<ReadOutcome, DecodeError>

Read decoded PCM samples into buffer.

Samples are interleaved f32 (e.g., LRLRLR for stereo).

Returns ReadOutcome::Frames with a non-zero count when the reader produced data, ReadOutcome::Pending with a typed PendingReason when the reader is alive but produced no frames this tick (buffering, seek-in-progress), or ReadOutcome::Eof on natural end-of-stream. Decoder / channel failures surface as DecodeError via the Err arm.

Errors

Returns DecodeError::Io when the producer channel closed / reported a failure (ConsumerPhase::Failed) before any frames could be flushed.

pub fn seek(&mut self, position: Duration) -> Result<SeekOutcome, DecodeError>

Seek to position in the audio stream.

This method never blocks. Seek coordination flows entirely through Timeline atomics (FLUSH_START/FLUSH_STOP pattern). The worker thread reads the seek target and epoch from Timeline and applies the seek.

Returns SeekOutcome::Landed when the reader is now parked at position; SeekOutcome::PastEof when the target is beyond a known duration() (the subsequent read returns ReadOutcome::Eof).

Errors

Propagated from the underlying stream (currently infallible at this layer — the worker thread surfaces errors lazily via FetchKind::Failure, which becomes Err from a subsequent read() / next_chunk()).

pub fn spec(&self) -> PcmSpec

Subscribe to audio events.

Get current audio specification.

Returns sample rate and channel count for audio output setup.

impl<T> Audio<Stream<T>>

where T: StreamType<Events = EventBus>,

Specialized impl for Stream-based audio pipelines.

Provides async constructor that creates Stream internally. Uses StreamAudioSource for automatic format change detection on ABR switch.

pub async fn new(config: AudioConfig<T>) -> Result<Self, DecodeError>

Create audio pipeline from AudioConfig.

This is the target API for Stream sources. Uses StreamAudioSource for automatic decoder recreation on format change.

Errors

Returns DecodeError if the stream cannot be created, the initial probe fails, or the decoder cannot be initialized.

Example

let config = AudioConfig::<Hls>::new(hls_config);
let audio = Audio::new(config).await?;
sink.append(audio);

pub fn event_bus(&self) -> &EventBus

Get a reference to the underlying EventBus.

Useful for passing to downstream components that also publish events.

pub fn events(&self) -> EventReceiver

Subscribe to unified events via the EventBus.

Returns a receiver for all events published to the bus.

Trait Implementations

impl<S> Drop for Audio<S>

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.

impl<S: MaybeSend> PcmReader for Audio<S>

fn abr_handle(&self) -> Option<AbrHandle>

Runtime ABR handle for the underlying stream.

fn duration(&self) -> Option<Duration>

Get total duration (if known).

fn event_bus(&self) -> &EventBus

Access the unified event bus for subscribing to all pipeline events.

fn metadata(&self) -> &TrackMetadata

Get track metadata.

fn next_chunk(&mut self) -> Result<ChunkOutcome, DecodeError>

Read the next decoded chunk with full metadata.

fn position(&self) -> Duration

Get current playback position.

fn preload(&mut self) -> Result<(), DecodeError>

Preload initial chunks into internal buffers.

fn preload_notify(&self) -> Option<Arc<Notify>>

Get notify for async preload (first chunk available).

fn read(&mut self, buf: &mut [f32]) -> Result<ReadOutcome, DecodeError>

Read interleaved PCM samples.

fn read_planar<'a>( &mut self, output: &'a mut [&'a mut [f32]], ) -> Result<ReadOutcome, DecodeError>

Read deinterleaved (planar) PCM samples.

fn seek(&mut self, position: Duration) -> Result<SeekOutcome, DecodeError>

Seek to the given position.

fn set_host_sample_rate(&self, sample_rate: NonZeroU32)

Set the target sample rate of the audio host.

fn set_playback_rate(&self, rate: f32)

Set the playback rate for timeline scaling.

fn set_service_class(&self, class: ServiceClass)

Update the scheduling priority hint for the shared worker.

fn spec(&self) -> PcmSpec

Get the current PCM specification.