pub struct FlacFrameReader<'a> { /* private fields */ }Expand description
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.
§Why this is decodable at all
A FLAC frame is self-describing. Its header restates the block size, sample rate, channel assignment and bit depth, carries a CRC-8 over itself and is followed by a CRC-16 over the whole frame. So a run of frames with nothing in front of it is a complete stream description, and the corpus carries two files that are exactly that.
§Where it sits
This is the third headerless decoder in the crate, beside
PcmDecoder and G711Decoder,
and it takes the same position they do: what the container would have said
arrives out of band, or not at all. The difference is that PCM and G.711
bytes carry no claim, so their new takes an
AudioSpec the caller asserts, whereas FLAC frames do
carry one, so new reads the properties rather than being
told them, and with_stream_info is for the
caller who has a real streaminfo block from somewhere else.
§The two escape codes
Sample rate code 0b0000 and bit depth code 0b000 mean “take this field
from the streaminfo block”. new has no streaminfo block, so
a frame using either is DecodeError::Malformed naming which of the two
could not be resolved. Nothing is defaulted and nothing is carried over
from a neighbouring frame. with_stream_info
resolves both.
§Example
use decibri_decode::{FlacFrameReader, Md5Check};
// RFC 9639 appendix D.3's worked example with its 42-byte header removed,
// which is what a container handing over bare frames would deliver.
let frames = &file[42..];
let reader = FlacFrameReader::new(frames)?;
assert_eq!(reader.spec().sample_rate, 32_000);
assert_eq!(reader.stream_info().bits_per_sample, 8);
// Nothing declares a length, so there is none to report.
assert_eq!(reader.frames(), None);
let mut samples = Vec::new();
let report = reader.decode(&mut samples)?;
assert_eq!(report.samples, 24);
// No streaminfo block came with the frames, so nothing verified them.
assert_eq!(report.md5, Md5Check::NoStreamInfo);
assert!(!report.md5.is_verified());Implementations§
Source§impl<'a> FlacFrameReader<'a>
impl<'a> FlacFrameReader<'a>
Sourcepub fn new(bytes: &'a [u8]) -> Result<Self, DecodeError>
pub fn new(bytes: &'a [u8]) -> Result<Self, DecodeError>
Reads a bare frame stream, taking the stream’s properties from its first frame header.
Only the first header is parsed here, so this is cheap on a large input and a reader that exists is a stream whose first frame header is valid.
§Errors
DecodeError::Truncatedwhen the input is shorter than the smallest possible frame header.DecodeError::Malformedwhen the input does not begin with a frame sync code, when the header’s CRC-8 does not match, when a reserved value is used, and, as the case this path adds, when the header defers its sample rate or bit depth to a streaminfo block that does not exist, which the error names.
Sourcepub const fn with_stream_info(bytes: &'a [u8], info: FlacStreamInfo) -> Self
pub const fn with_stream_info(bytes: &'a [u8], info: FlacStreamInfo) -> Self
Reads a bare frame stream described by a streaminfo block the caller obtained elsewhere.
This is the shape Ogg and Matroska use: the streaminfo block travels
in the container’s own codec-private header and the packets that
follow are bare frames. The block’s bytes become an info through
FlacStreamInfo::from_block. Supplying it resolves the two escape
codes, restores the declared sample count as a check, and, when the
block carries one, restores the MD5 that a bare stream otherwise has
no way to be checked against.
Nothing is parsed here, so nothing can fail; a stream whose frames
disagree with info is rejected by decode, naming
the field that disagreed.
Sourcepub const fn stream_info(&self) -> &FlacStreamInfo
pub const fn stream_info(&self) -> &FlacStreamInfo
The stream’s properties: supplied by the caller, or read out of the first frame header.
A derived description is not a streaminfo block and does not pretend
to be one. Its max_block_size is the format’s own 65,535 rather than
a promise this stream made, and total_samples, md5,
min_frame_size and max_frame_size are all None.
Sourcepub const fn frames(&self) -> Option<u64>
pub const fn frames(&self) -> Option<u64>
How many interchannel samples the stream declares, which for a derived
description is always None because nothing declared anything.
Sourcepub fn decode(
&self,
output: &mut Vec<f32>,
) -> Result<FlacFrameReport, DecodeError>
pub fn decode( &self, output: &mut Vec<f32>, ) -> Result<FlacFrameReport, DecodeError>
Decodes every frame and appends the interleaved samples to output.
§Errors
DecodeError::Malformedfor a frame whose CRC-8 or CRC-16 does not match, a reserved or forbidden field value, a frame whose properties disagree with the stream’s, a frame deferring a field to a streaminfo block that is not there, and, when a checksum was supplied, decoded audio that does not match it.DecodeError::Truncatedwhen the input ends inside a frame. A partial trailing frame is an error here, exactly as it is everywhere else in this crate; recovering what can be read from a damaged run isFlacRecovery, and is asked for explicitly.