Skip to main content

Crate decibri_decode

Crate decibri_decode 

Source
Expand description

Encoded audio bytes in, f32 samples out, with the sample rate and channel count travelling with them and a stated and tested sample-count guarantee.

That sentence is the crate. Codecs fill the contract in; they are not the contract. The trait boundaries, the error type and the buffer types are settled before any codec exists, because changing them afterwards is a breaking change and changing them now is free.

§The contract

  • In: encoded bytes, held whole in memory and handed to a reader, or arriving in pieces via StreamSource.
  • Out: f32 samples that always travel with the AudioSpec that describes them, so no downstream stage ever infers or assumes a rate. That is the whole reason AudioBuffer exists rather than a bare Vec<f32>: decibri has been bitten repeatedly by rate and layout travelling separately from the samples they describe, most expensively on the AEC reference path, where a wrong-rate reference is accepted silently and cancels nothing.
  • Guarantee: the number of samples produced for a given input is stated and tested, not incidental. Decoding a source of n frames yields exactly n * channels samples, and there is no rate conversion here for that count to be conditional on. A caller who goes on to resample gets the count decibri_resampler states for that rate pair and input length, which is that crate’s guarantee rather than this one’s. A codec that cannot state its output count does not go behind Decoder.
  • Failure: every rejection is a DecodeError that names the specific thing it rejected. “Unsupported” on its own tells a caller nothing they can act on.

§Choosing a reader

decode takes bytes in any carried container and gives back an AudioBuffer, AudioStreamDecoder does the same for a stream that arrives in pieces, and identify answers what an input is without decoding it. All three read the same twelve leading bytes, so a caller never writes a magic-byte check and there is one statement of what a WAV looks like rather than one per call site.

Twelve, not four, because RIFF names a container family: the form type at offset eight is what separates a WAV from an AVI, and FORM from an 8SVX. A container whose form type is not one this crate reads is DecodeError::UnsupportedContainer naming the form type found, never a reader handed a file that was never its.

Headerless linear PCM, headerless G.711 and bare FLAC frame streams have no signature and are outside this. They stay explicit, because the alternative is guessing: a FLAC frame’s 14-bit sync code and 8-bit header CRC together let about one position in 32,768 of random data parse as a frame header, so sniffing for one in bytes of unknown provenance would misfire on input that is not FLAC at all.

§Determinism

For every format this crate carries (PCM, G.711, WAV, AIFF and FLAC), decoding is bit-exact and cross-platform byte-identical. The same input produces the same bytes on every target: no floating-point reassociation, no platform-specific fast paths, no reliance on FMA contraction.

If MP3 is ever added, its decode is compliant within the ISO/IEC 11172-4 accuracy bound and is explicitly not claimed as byte-identical. MPEG never specified bit-exact decoding, and two conforming decoders legitimately differ. That exception will be stated on the MP3 decoder itself and does not weaken the guarantee above for any other format.

This is written now, while it is a true statement about an empty crate, rather than retrofitted once somebody has assumed otherwise.

Determinism is not losslessness. Determinism holds for everything here. Losslessness, a value surviving the round trip through f32 with its bits intact, holds for every format at or below 24 significant bits, all of them except i32 and f64. An f32 significand is 24 bits, so 31-bit and 53-bit values land on the nearest representable f32 instead of on themselves. That is inherent to an f32 internal representation and is the right trade for a crate feeding decibri’s f32 chain, but it is stated here rather than left to be discovered. The error is bounded by half an ulp at the value’s magnitude; nothing wraps and no sign flips.

§Rate conversion

There is none here, and there never will be. Rate conversion is decibri_resampler, the crate’s only dependency, called and never reimplemented. Its failures arrive as DecodeError::Resample. Additional instances of a resampler are expected and fine; a second implementation is a correctness hazard, because resampler choice was measured during the echo-cancellation work as moving AECMOS by up to 1.03, larger than the effect being measured.

§Sample conversion

SampleFormat carries every linear PCM format the crate reads: u8 and i8 (WAV’s 8-bit is unsigned and AIFF’s is signed, and those are the two specifications’ rules rather than a choice here), and 16-, 24- and 32-bit integer and 32- and 64-bit float in both byte orders. It converts each to and from f32. The numerical conventions are not this crate’s to choose: the scale factor, the rounding and clamping rule and the downmix formula were all read out of decibri so that the same input decoded through either crate gives the same samples. They are recorded, with the file and line each came from, on the sample module.

There is no dither, no feature flag for one and no plan for one. It needs a random source, which would either break the byte-identical claim above or make a generator seed part of the public contract.

§G.711

G711Law carries both ITU-T companding laws, mu-law and A-law, in both directions, and G711Decoder decodes a headerless stream in either. The tables are derived from the recommendation’s own segment geometry rather than transcribed from a third-party implementation, because the crate is published under Apache-2.0 and reference data with an unestablished licence is a real constraint.

G.711 is a sample format, not a rate. It is overwhelmingly carried at 8 kHz in telephony and nothing in the recommendation says so, so the rate comes from the AudioSpec the caller states and nothing here defaults to 8000.

Decoding is a code to i16 through the table, then i16 to f32 through sample; encoding is the reverse. There is no direct code-to-f32 path, so the crate has one scaling rule rather than two.

§WAV

WavReader reads a RIFF/WAVE or RF64 file held whole in memory and WavStreamDecoder reads one that arrives in pieces; WavWriter writes every encoding either of them reads. WavCodec is the set of encodings a WAV file can carry and this crate can decode: four widths of linear PCM, two of IEEE float, and both G.711 laws.

Dispatch is on the (wFormatTag, wBitsPerSample) pair, never on the tag alone. Tag 1 covers four widths, and a reader that picked one would decode the others at the wrong stride and produce noise rather than an error. It is never, at any point, on a file name. WAVE_FORMAT_EXTENSIBLE resolves through its SubFormat GUID.

Malformed input is a typed DecodeError rather than a panic, and no allocation anywhere is proportional to a size the file declared: a data chunk announcing four gigabytes inside a two-kilobyte file is rejected before a byte is reserved for it. All chunk arithmetic is 64-bit and checked, which is what makes that true on a 32-bit target as well.

§AIFF and AIFF-C

AiffReader reads an AIFF or AIFF-C file held whole in memory, AiffStreamDecoder reads one that arrives in pieces, and AiffWriter writes every encoding either of them reads: plain AIFF where big-endian PCM makes that form legal, AIFC with its FVER chunk and compression field where the encoding requires it. AiffCodec is the set of encodings this crate carries in the container: linear PCM at four widths (big-endian under NONE/twos, little-endian under sowt, and signed at 8 bits where WAV is unsigned), unsigned 8-bit under AIFF-C’s raw , IEEE float under fl32/fl64, and both G.711 laws under alaw/ulaw. Every other compression type is DecodeError::UnsupportedCodec.

Dispatch is on the form type and the compression four-CC (paired with sampleSize for the linear widths), never on a file name. The 80-bit extended-precision sample rate is parsed by hand, and COMM’s numSampleFrames is required to agree exactly with the SSND chunk’s length. Disagreement is a typed error, never a silent preference for either source.

§FLAC

FlacReader reads a FLAC stream held whole in memory and FlacStreamDecoder reads one that arrives in pieces; FlacStreamInfo is what the streaminfo metadata block declared. Both readers are always built: this crate has no Cargo features, so a FLAC stream decodes in every build of it.

Decoding is written from RFC 9639 and covers the whole format this crate claims: every bit depth from 4 to 32, every channel count from 1 to 8, the three stereo decorrelations, constant, verbatim, fixed and linear predictor subframes, both Rice parameter widths and the escaped partitions, fixed and variable block size streams, and the uncommon block sizes and sample rates that live outside the streamable subset.

The integrity check is a runtime feature, not a test. Every FLAC file carries an MD5 of its own unencoded audio, so unlike every other format here the decoder can check its own output on every file it ever sees. It does: a whole-file decode hashes as it goes, a streaming decode hashes incrementally, and both verify at the end. A mismatch is a typed error rather than audio. An all-zero checksum means “not known”, which the format permits and which is not a failure. The frame header CRC-8 and the whole-frame CRC-16 are verified as well, before any sample from that frame is delivered.

Properties may not change mid-stream. A FLAC frame header restates the sample rate, channel count and bit depth, and the format allows them to differ between frames. This crate rejects that with a typed error, because AudioBuffer carries one AudioSpec for the samples it holds and there is no honest way to describe a buffer whose rate changed half way through.

FlacWriter writes native FLAC streams at compression levels 0 through 8, computing residuals through the same integer prediction functions the decoder reconstructs with, so the two cannot disagree about the arithmetic. The Ogg and Matroska mappings are not here.

§Bare frames, out-of-band streaminfo, and recovery

A FLAC frame is self-describing, so a run of frames with no fLaC signature and no metadata in front of it is still decodable. FlacFrameReader reads one held whole in memory and FlacStreamDecoder::frames reads one that arrives in pieces, the third headerless decoder in the crate, beside PcmDecoder and G711Decoder. The two frame header codes that mean “take this field from streaminfo”, sample rate 0b0000 and bit depth 0b000, have nothing to be taken from on that path and are a typed error naming which field was unresolved, never a default.

Both readers accept a streaminfo block from out of band, which is what Ogg and Matroska do: the block travels in the container’s codec-private header and the packets carry bare frames. The block’s 34-byte body parses through FlacStreamInfo::from_block, and supplying the result resolves those two codes and restores the MD5 check to a path that otherwise has none. Whether that check actually ran is reported, as Md5Check, because a caller cannot tell from the samples and a decode that quietly verified nothing is how a guarantee gets claimed that was never provided.

FlacRecovery finds frame boundaries in a byte run that may begin mid-frame, hold garbage or be damaged. It is a separate type rather than a flag, because everywhere else here a damaged frame is an error rather than quietly shortened audio: recovery has to be asked for, and every decode through it reports the byte ranges that produced nothing and the sample positions lost. A sync point is accepted only when the frame at it passes its CRC-16 and another frame header parses where that frame ends. The 14-bit sync code and 8-bit header CRC together let about one position in 32,768 of random data look like a frame, so a single validating header is not evidence.

Recovery is whole-buffer only. FlacRecovery takes a slice, and there is no streaming form of it: a live stream that meets corruption part-way through is a typed error from FlacStreamDecoder, not a resync. Accepting a sync point requires the bytes after the candidate frame, so a streaming resync would have to buffer forward without a bound or accept weaker evidence than the standard above. Recovering a damaged live stream means collecting its bytes and handing them to FlacRecovery.

§Layout

§Status

Linear PCM, G.711, the RIFF/WAVE and RF64 container, the AIFF and AIFF-C container, and FLAC. PcmDecoder decodes headerless streams in any SampleFormat and G711Decoder decodes headerless mu-law and A-law; WavReader and WavStreamDecoder read WAV whole or in pieces and WavWriter writes it; AiffReader, AiffStreamDecoder and AiffWriter do the same three things for AIFF; FlacReader and FlacStreamDecoder read FLAC whole or in pieces, FlacWriter writes it at compression levels 0 through 8, FlacFrameReader reads a bare frame stream and FlacRecovery recovers what a damaged byte run holds. The Ogg and Matroska mappings of FLAC are not here; the codec they would build on is. decode and AudioStreamDecoder pick between the three containers by content. WavStreamDecoder, AiffStreamDecoder, FlacStreamDecoder and AudioStreamDecoder are the StreamSources.

Re-exports§

pub use sample::deinterleave;
pub use sample::downmix_to_mono;
pub use sample::f32_to_i16;
pub use sample::f32_to_i24;
pub use sample::f32_to_i32;
pub use sample::f32_to_i8;
pub use sample::f32_to_u8;
pub use sample::i16_to_f32;
pub use sample::i24_to_f32;
pub use sample::i32_to_f32;
pub use sample::i8_to_f32;
pub use sample::interleave;
pub use sample::u8_to_f32;
pub use sample::SampleFormat;
pub use sample::I24_MAX;
pub use sample::I24_MIN;
pub use sample::MAX_BYTES_PER_SAMPLE;
pub use decibri_resampler;

Modules§

sample
Linear PCM sample formats, and the conversions between them and the f32 this crate works in.

Structs§

AiffFormat
A resolved COMM chunk: what the file declared, and what it resolved to.
AiffReader
An AIFF or AIFF-C file held whole in memory.
AiffStreamDecoder
Reads an AIFF or AIFF-C file that arrives in pieces.
AiffWriter
Writes AIFF and AIFF-C files.
AudioBuffer
Decoded audio together with the AudioSpec that describes it.
AudioSpec
The sample rate and channel count of a block of audio.
AudioStreamDecoder
Reads a stream that arrives in pieces, in whatever of the carried formats its leading bytes turn out to name.
FlacFrameReader
A bare FLAC frame stream held whole in memory: no fLaC signature, no metadata, the first byte is the first byte of a frame header.
FlacFrameReport
What a bare frame stream decode did.
FlacReader
A FLAC file held whole in memory.
FlacRecovery
Recovers whatever audio a run of bytes holds, which may begin part-way through a frame, hold garbage, or be damaged in the middle.
FlacRecoveryReport
What a recovering decode found and what it did not.
FlacSkip
One range of input that produced no audio.
FlacStreamDecoder
Reads a FLAC stream that arrives in pieces.
FlacStreamInfo
What a FLAC stream’s streaminfo metadata block declares.
FlacWriter
Writes native FLAC streams: a fLaC signature, one streaminfo block, and Rice-coded audio frames.
FourCc
A four-character code, as used by RIFF, AIFF, ISO base media and friends to name a chunk, a container or a codec.
G711Decoder
Decodes a headerless G.711 stream: one byte per sample in the law given at construction, samples out at an AudioSpec the caller states.
PcmDecoder
Decodes a headerless linear PCM stream: bytes in one of the SampleFormats, samples out at a AudioSpec the caller states.
WavFormat
A resolved fmt chunk: what the file declared, and what it resolved to.
WavReader
A WAV file held whole in memory.
WavStreamDecoder
Reads a WAV file that arrives in pieces.
WavWriter
Writes RIFF/WAVE and RF64 files.

Enums§

AiffCodec
An encoding an AIFF or AIFF-C file can carry and this crate can decode.
AiffForm
Which of the two form types the file declared.
CodecId
How a container named the codec or sample format of its payload.
Container
What the leading bytes of an input turned out to be.
DecodeError
Every way decoding can fail.
FlacSkipReason
Why a range of input produced no audio.
G711Law
One of the two G.711 companding laws.
Md5Check
Whether a decode checked its output against a streaminfo MD5, and why not when it did not.
RiffFlavour
Which RIFF flavour a written file uses.
WavCodec
An encoding a WAV file can carry and this crate can decode.
WavHeaderStyle
How a written file names its format.

Traits§

Decoder
Turns encoded frames into f32 samples.
StreamSource
A stream that arrives in pieces: bytes are pushed in, samples are pulled out, and an incomplete frame waits inside for the rest of itself.

Functions§

decode
Decodes a whole input, whatever of the carried formats it is.
identify
Says what bytes are, without decoding any of them.