Trait Decoder 

pub trait Decoder: Send + 'static {
    // Required methods
    fn duration(&self) -> Option<Duration>;
    fn next_chunk(&mut self) -> DecodeResult<DecoderChunkOutcome>;
    fn seek(&mut self, pos: Duration) -> DecodeResult<DecoderSeekOutcome>;
    fn spec(&self) -> PcmSpec;
    fn update_byte_len(&self, len: u64);

    // Provided methods
    fn default_priming_frames(&self, codec: AudioCodec) -> u64 { ... }
    fn metadata(&self) -> TrackMetadata { ... }
    fn track_info(&self) -> DecoderTrackInfo { ... }
}

Trait for runtime-polymorphic audio decoders.

This trait is used by kithara-audio for dynamic dispatch when the decoder type is determined at runtime (e.g., based on media info).

Required Methods

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

Get total duration from track metadata.

Returns None if duration cannot be determined.

fn next_chunk(&mut self) -> DecodeResult<DecoderChunkOutcome>

Decode the next chunk of PCM data.

Returns DecoderChunkOutcome::Chunk with PCM data, DecoderChunkOutcome::Pending with a typed PendingReason when the underlying source aborted (seek pending, transient backpressure), or DecoderChunkOutcome::Eof at natural end of stream. Real decoder/codec failures surface as crate::error::DecodeError via the Err arm.

Errors

Returns crate::error::DecodeError if decoding fails.

fn seek(&mut self, pos: Duration) -> DecodeResult<DecoderSeekOutcome>

Seek to a time position.

On success returns DecoderSeekOutcome::Landed with the authoritative landed position (often a granule boundary near the requested target — never assume landed_at == pos), or DecoderSeekOutcome::PastEof when the target is beyond the decoder’s known duration.

Errors

Returns crate::error::DecodeError::SeekFailed if seeking is not supported or the position is invalid for reasons other than past-EOF.

fn spec(&self) -> PcmSpec

Get the PCM output specification.

fn update_byte_len(&self, len: u64)

Update the byte length reported to the underlying media source.

For HLS streams, the total length becomes known after metadata calculation. Call this before seeking so the decoder can compute correct seek deltas.

Provided Methods

fn default_priming_frames(&self, codec: AudioCodec) -> u64

Default leading-silence frame count for codec when no container-/encoder-level gapless metadata is available.

Default implementation returns the codec’s encoder-side priming (AudioCodec::encoder_priming_frames) — every decoder inherits it for free. Concrete decoders override only when they add their own algorithmic delay on top ([crate::codec::FrameCodec::decoder_algo_delay] — currently Symphonia mpa adds 529 for MP3).

Used by kithara_audio::pipeline::gapless::resolve_codec_priming for the crate::GaplessMode::CodecPriming fallback path.

fn metadata(&self) -> TrackMetadata

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

Returns default metadata if not available.

fn track_info(&self) -> DecoderTrackInfo

Decoder-owned playback contract — currently the captured crate::GaplessInfo (encoder priming + trailing padding in PCM frames) when DecoderConfig.gapless = true and the codec reports it. Default implementation returns the empty contract, so most decoders inherit the no-trim behaviour.

The audio-pipeline gapless stage reads this once per track and constructs a crate::GaplessTrimmer when the contract is non-empty. Returned by-value (clone) so callers don’t pin a borrow on &self across next_chunk/seek.

Dyn Compatibility

This trait is dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors