#[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
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
impl SampleFormat
Sourcepub const fn bytes_per_sample(self) -> usize
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.
Sourcepub const fn bits_per_sample(self) -> u16
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.
Sourcepub const fn is_float(self) -> bool
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.
Sourcepub fn decode(self, bytes: &[u8], output: &mut Vec<f32>) -> usize
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]);Sourcepub fn encode(self, samples: &[f32], output: &mut Vec<u8>) -> usize
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]);