Skip to main content

Decoder

Trait Decoder 

Source
pub trait Decoder: Send {
    // Required methods
    fn output_spec(&self) -> AudioSpec;
    fn feed(&mut self, input: &[u8]) -> Result<usize, DecodeError>;
    fn decode(&mut self, output: &mut Vec<f32>) -> Result<usize, DecodeError>;
    fn flush(&mut self, output: &mut Vec<f32>) -> Result<usize, DecodeError>;
    fn reset(&mut self);
}
Expand description

Turns encoded frames into f32 samples.

§Why this shape

The trait is a pull model, feed bytes and then pull whatever samples are ready, rather than a chunk-in-chunk-out function. Nothing in the pure-PCM codecs needs that: they are stateless and a byte slice maps to a sample slice. MP3 does. Its bit reservoir lets a frame borrow bits from earlier frames, so a decoder must be able to accept bytes that produce nothing yet and produce samples from bytes it accepted earlier. Establishing that here costs almost nothing; establishing it once four codecs are written above a chunk-in-chunk-out API means rewriting all of them.

The trait is object safe, because the decoder for a given input is chosen at run time from what the container turned out to declare, and because platform decoders, AudioToolbox on iOS, MediaCodec on Android, both hardware-accelerated and already licensed by the platform vendor, must be able to sit behind the same dyn Decoder as the crate’s own. That is the single most expensive property here to retrofit.

Implementations are Send, so an instance can be constructed on one thread and driven on another.

§Contract

  • output_spec is fixed for the life of the instance and known at construction, because a decoder is built by whatever parsed the header. A stream whose header has not arrived has no decoder yet; see StreamSource::spec.
  • feed may consume less than it is offered and may produce nothing. decode may produce samples from bytes fed in earlier calls. Neither is one-in-one-out and neither assumes the caller holds the whole input.
  • Where a byte lands in the feed sequence makes no difference to the output. Feeding a file in one slice, in 4096-byte slices, or one byte at a time produces the same samples in the same order.
  • After flush, the decoder is at end of stream: feed consumes nothing and decode produces nothing until reset. This mirrors decibri_resampler::Resampler, except that it is a quiet no-op rather than an error, because DecodeError has no variant for driving a decoder wrongly and is not going to grow one.

§Sample-count guarantee

For an input the container describes as n frames, the totals across a full feed/decode/flush sequence come to exactly n * channels samples. Not approximately, and not “plus whatever the last partial frame yields”. A codec that cannot state its output count for a given input does not belong behind this trait.

Required Methods§

Source

fn output_spec(&self) -> AudioSpec

The rate and layout of the samples this decoder produces.

Fixed for the life of the instance. This is the authority for the rate of everything decode and flush append; pair the two with AudioBuffer::from_samples at the point where the samples travel any further.

Source

fn feed(&mut self, input: &[u8]) -> Result<usize, DecodeError>

Hands input to the decoder and returns how many of its bytes were taken.

A short return means the decoder’s internal buffer is full: drain it with decode and offer the remainder again. A return of input.len() does not mean any samples are ready, and a return of 0 does not mean the input is bad.

A partial frame at the end of input is held, not rejected. It is only an error if the stream then ends; see flush.

§Errors

Returns DecodeError::Malformed when the accepted bytes cannot be a valid continuation of the stream at all. Running out of bytes is not an error here.

Source

fn decode(&mut self, output: &mut Vec<f32>) -> Result<usize, DecodeError>

Appends every sample the decoder can produce from what it has been fed, and returns how many it appended.

output is appended to, never cleared, and the caller owns it, the same convention as decibri_resampler::Resampler::process, so a decoder’s output vector feeds a resampler with no copy in between.

A return of 0 means “starved, feed me more”, not “end of stream”. Callers loop decode until it returns 0, then feed again.

§Errors

Returns DecodeError::Malformed when a buffered frame turns out to be invalid once enough of it has arrived to judge.

Source

fn flush(&mut self, output: &mut Vec<f32>) -> Result<usize, DecodeError>

Declares end of input, appends any remaining samples and returns how many were appended.

Call it once the last byte has been fed. Codecs with a decode tail emit it here; codecs without one append nothing and return 0. It is idempotent.

§Errors

Returns DecodeError::Truncated when bytes of an incomplete frame are still held. That is the one place a partial frame becomes an error: while the stream is open it is simply data that has not arrived yet.

Source

fn reset(&mut self)

Returns the decoder to its just-constructed state.

Buffered bytes, undelivered samples and any end-of-stream condition set by flush are dropped. The output spec is unchanged. Use it to decode a second stream on the same instance, or to resume after a seek.

Dyn Compatibility§

This trait is dyn compatible.

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

Implementors§