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_specis 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; seeStreamSource::spec.feedmay consume less than it is offered and may produce nothing.decodemay 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:feedconsumes nothing anddecodeproduces nothing untilreset. This mirrorsdecibri_resampler::Resampler, except that it is a quiet no-op rather than an error, becauseDecodeErrorhas 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§
Sourcefn output_spec(&self) -> AudioSpec
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.
Sourcefn feed(&mut self, input: &[u8]) -> Result<usize, DecodeError>
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.
Sourcefn decode(&mut self, output: &mut Vec<f32>) -> Result<usize, DecodeError>
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.
Sourcefn flush(&mut self, output: &mut Vec<f32>) -> Result<usize, DecodeError>
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.
Dyn Compatibility§
This trait is dyn compatible.
In older versions of Rust, dyn compatibility was called "object safety".