Skip to main content

SampleFormat

Enum SampleFormat 

Source
#[non_exhaustive]
pub enum SampleFormat { U8, I8, I16Le, I16Be, I24Le, I24Be, I32Le, I32Be, F32Le, F32Be, F64Le, F64Be, }
Expand description

A linear PCM sample format: a width, a signedness and, above one byte, a byte order.

Little-endian covers WAV, big-endian covers AIFF, and both are needed.

Eight-bit signedness is the container’s, not a convention. WAV’s 8-bit PCM is unsigned, offset by 128; AIFF’s is signed two’s complement. Those are what the two specifications say, and they are exact inverses of each other, which is why U8 and I8 are two variants rather than one variant and a flag somebody forgets to set. A converter that reads either one as the other produces audio offset by half full scale, which sounds like severe distortion rather than like a subtle bug; see u8_to_f32 and i8_to_f32.

This enum is #[non_exhaustive]: a consumer matching on it needs a _ arm, so a later container’s format can be added without breaking source.

Variants (Non-exhaustive)§

This enum is marked as non-exhaustive
Non-exhaustive enums could have additional variants added in future. Therefore, when matching against variants of non-exhaustive enums, an extra wildcard arm must be added to account for any future variants.
§

U8

Unsigned 8-bit, offset by 128, as WAV carries. One byte, so no byte order.

§

I8

Signed 8-bit two’s complement, as AIFF carries. One byte, so no byte order.

§

I16Le

Signed 16-bit, little-endian.

§

I16Be

Signed 16-bit, big-endian.

§

I24Le

Signed 24-bit packed into three bytes, little-endian.

§

I24Be

Signed 24-bit packed into three bytes, big-endian.

§

I32Le

Signed 32-bit, little-endian.

§

I32Be

Signed 32-bit, big-endian.

§

F32Le

IEEE 754 binary32, little-endian.

§

F32Be

IEEE 754 binary32, big-endian.

§

F64Le

IEEE 754 binary64, little-endian.

§

F64Be

IEEE 754 binary64, big-endian.

Implementations§

Source§

impl SampleFormat

Source

pub const fn bytes_per_sample(self) -> usize

How many bytes one sample occupies.

Three for the 24-bit formats: they are packed, not padded into four.

Source

pub const fn bits_per_sample(self) -> u16

How many bits of resolution one sample carries.

The form a container declares, and the form DecodeError::UnsupportedSampleFormat reports.

Source

pub const fn is_float(self) -> bool

true for the IEEE 754 formats.

The distinction is not cosmetic: the float formats pass values through unclamped, and the integer formats clamp.

Source

pub fn decode(self, bytes: &[u8], output: &mut Vec<f32>) -> usize

Appends every whole sample in bytes to output as f32, and returns how many it appended.

output is appended to, never cleared, the same convention as Decoder::decode, so a decoder’s output vector feeds a resampler with no copy in between. A trailing partial sample is ignored rather than rejected; the caller owns the decision about whether running out of bytes mid-sample is an error, because on an open stream it is not. PcmDecoder makes that decision.

use decibri_decode::SampleFormat;

let mut samples = Vec::new();
// 0x8000 is i16::MIN little-endian: exactly -1.0.
let appended = SampleFormat::I16Le.decode(&[0x00, 0x80, 0x00, 0x40], &mut samples);
assert_eq!(appended, 2);
assert_eq!(samples, [-1.0, 0.5]);
Source

pub fn encode(self, samples: &[f32], output: &mut Vec<u8>) -> usize

Appends samples to output in this format, and returns how many bytes it appended.

Integer formats clamp; float formats pass the value through as it is.

use decibri_decode::SampleFormat;

let mut bytes = Vec::new();
// Beyond full scale clamps to the extreme rather than wrapping.
let appended = SampleFormat::I16Be.encode(&[1.5], &mut bytes);
assert_eq!(appended, 2);
assert_eq!(bytes, [0x7f, 0xff]);

Trait Implementations§

Source§

impl Clone for SampleFormat

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 Copy for SampleFormat

Source§

impl Debug for SampleFormat

Source§

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

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

impl Eq for SampleFormat

Source§

impl Hash for SampleFormat

Source§

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher. Read more
1.3.0 · Source§

fn hash_slice<H>(data: &[Self], state: &mut H)
where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher. Read more
Source§

impl PartialEq for SampleFormat

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 StructuralPartialEq for SampleFormat

Auto Trait Implementations§

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.