Skip to main content

FlacFrameReader

Struct FlacFrameReader 

Source
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>

Source

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::Truncated when the input is shorter than the smallest possible frame header.
  • DecodeError::Malformed when 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.
Source

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.

Source

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.

Source

pub const fn spec(&self) -> AudioSpec

The rate and layout the stream decodes to.

Source

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.

Source

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

Decodes every frame and appends the interleaved samples to output.

§Errors
  • DecodeError::Malformed for 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::Truncated when 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 is FlacRecovery, and is asked for explicitly.
Source

pub fn decode_to_end( &self, ) -> Result<(AudioBuffer, FlacFrameReport), DecodeError>

Decodes the whole stream, bound to the spec that describes it.

§Errors

As decode.

Trait Implementations§

Source§

impl<'a> Clone for FlacFrameReader<'a>

Source§

fn clone(&self) -> Self

Returns a duplicate of the value. Read more
1.0.0 (const: unstable) · Source§

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source. Read more
Source§

impl<'a> Copy for FlacFrameReader<'a>

Source§

impl<'a> Debug for FlacFrameReader<'a>

Source§

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter. Read more
Source§

impl<'a> Eq for FlacFrameReader<'a>

Source§

impl<'a> PartialEq for FlacFrameReader<'a>

Source§

fn eq(&self, other: &Self) -> bool

Equality operator ==. Read more
1.0.0 (const: unstable) · Source§

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=. Read more
Source§

impl<'a> StructuralPartialEq for FlacFrameReader<'a>

Auto Trait Implementations§

§

impl<'a> Freeze for FlacFrameReader<'a>

§

impl<'a> RefUnwindSafe for FlacFrameReader<'a>

§

impl<'a> Send for FlacFrameReader<'a>

§

impl<'a> Sync for FlacFrameReader<'a>

§

impl<'a> Unpin for FlacFrameReader<'a>

§

impl<'a> UnsafeUnpin for FlacFrameReader<'a>

§

impl<'a> UnwindSafe for FlacFrameReader<'a>

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> CloneToUninit for T
where T: Clone,

Source§

unsafe fn clone_to_uninit(&self, dest: *mut u8)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dest. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> ToOwned for T
where T: Clone,

Source§

type Owned = T

The resulting type after obtaining ownership.
Source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
Source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.