Skip to main content

Crate audioadapter_sample

Crate audioadapter_sample 

Source
Expand description

§audioadapter-sample

A crate that helps with handling audio samples in various formats.

This crate is part of the audioadapter family.

The audioadapter family has three core crates:

  • audioadapter: The core audioadapter traits.
  • audioadapter-sample: This crate, a companion crate that provides sample format conversions as well as extensions to the standard Read and Write traits.
  • audioadapter-buffers: A companion crate that provides wrappers for various common data structures.

In addition to these, the audioadapter-compat-* crates implement the traits for buffer types from other audio crates. See the core crate documentation for the current list.

§Introduction

Audio data is stored and exchanged in various numerical formats, for example 16 or 24 bit integers, or 32-bit floating point. When data is exchanged via files or APIs, the sample values have to be stored in some binary format. This crate is intended to help with both conversions between the various numerical formats, as well as handling reading and writing these samples as raw bytes.

§Sample formats

This crate supports signed and unsigned integer samples with 8, 16, 24, 32 and 64 bits. Floating point samples are also supported, with 32 and 64 bits. For all multi-byte formats, both little-endian and big-endian representations are supported. The 8-bit formats are a single byte and therefore have no byte order.

The two companded telephony formats from ITU-T G.711, A-law and mu-law, are also supported. These store a single byte per sample, and decode to the closest numeric type, i16. That type is wider than the format itself, which has some consequences, see the note below.

When converting between integers and floating point, the value range of the integer is mapped to the floating point range of -1.0 to +1.0. If a floating point value outside this range is converted to integer, the value will be clamped at the minimum or maximum value of the integer.

§This crate

The main functionality of this crate is provided by two main traits:

In addition to the traits, it also defines a number of wrappers for bytes. For example, four bytes might be a signed or unsigned 32-bit integer, a 32-bit float, or a 24-bit integer with a padding byte. By using the appropriate wrapper, for example sample::I32_LE, it becomes clear that these bytes store a signed 32-bit integer in little-endian byte order.

§Special note on 24-bit audio formats

While 16-bit (i16) and 32-bit (i32) audio samples align with standard integer types, 24-bit samples do not have a direct native equivalent.

To preserve full precision when working with 24-bit data, this crate uses the next larger integer type, i32 or u32, for conversions.

§Storage formats for 24-bit samples

24-bit audio samples are typically stored in one of two formats:

  • Packed: Each sample uses exactly 3 bytes.
  • Padded: An additional byte is added, making each sample 4 bytes.
§Packed format

Packed samples are space-efficient, using only the necessary 3 bytes per sample. Since all bytes contain data, there’s no ambiguity about byte placement. However, the 3-byte alignment can be inconvenient to work with, and certain hardware may not support it.

§Padded format

Padded samples align to 4 bytes, which simplifies memory access and may be required by some devices or APIs. The padding byte can be placed in two ways:

  • Left-justified: Padding is added as the least significant byte, so the actual data occupies the three most significant bytes.

    • Used in .wav files and the Windows Wasapi API.

  • Right-justified: Padding is added as the most significant byte, placing the data in the three least significant bytes.

    • Used in the ALSA API on Linux, such as the SND_PCM_FORMAT_S24_LE format.

§Example: read 24-bit integers from raw bytes

use audioadapter_sample::sample::I24_LE;
use audioadapter_sample::sample::BytesSample;

// Make a vector with some dummy data.
// 9 bytes corresponding to 3 samples.
let bytes = vec![1, 2, 3, 4, 5, 6, 7, 8, 9];

for sample in bytes.chunks_exact(3) {
  let new_value: i32 = I24_LE::from_slice(sample).to_number();
  println!("{}", new_value);
}

§Special note on the G.711 companded formats

A-law and mu-law, defined by ITU-T G.711, are the sample formats of the telephone network. They are still the baseline of SIP and the PSTN, and also appear in .wav files as WAVE_FORMAT_ALAW and WAVE_FORMAT_MULAW.

Both fit a wide dynamic range into a single byte by spacing the quantization steps logarithmically, finely near silence and coarsely near full scale. This keeps the relative error roughly constant across the range, which is what makes one byte per sample usable at all. A-law carries about 13 bits worth of range and mu-law about 14. For comparison, the linear U8 format also uses one byte, but spaces its steps evenly, so it covers 8 bits of range and its quiet passages are far coarser.

§The numeric type is wider than the format

Every other format in this crate has a NumericType that holds exactly what the bytes hold. U8 and u8 carry the same information, so from_number followed by to_number returns the original value. Any loss happens later, when converting between numeric types.

For A-law and mu-law the numeric type is i16, which is wider than the 256 values the format can represent, so from_number itself quantizes. Converting a number to one of these formats and back does not return the original value. Converting the result a second time changes nothing further, so the quantization is at least stable.

§An all-zero byte is not silence

In A-law a zero byte decodes to -5504, and in mu-law to -32124, which is full scale negative. The code for silence is 0xD5 in A-law, which decodes to +8 rather than 0 since A-law has no code for exact zero, and 0xFF in mu-law. Note also that the sign bit has opposite meanings in the two formats.

§Example: read mu-law samples from raw bytes

use audioadapter_sample::sample::MULAW;
use audioadapter_sample::sample::{BytesSample, RawSample};

// Four mu-law samples: silence, full scale positive,
// full scale negative, and silence again.
let bytes = vec![0xff, 0x80, 0x00, 0xff];

for sample in bytes.iter() {
  let value: f32 = MULAW::from_slice(&[*sample]).to_scaled_float();
  println!("{}", value);
}

§Converting between numerical formats

A very common sample format is 16-bit signed integer. But when doing any kind of processing of audio data, such as filtering or mixing, it is often desirable to work with floating point values. An application may therefore need to convert input data from 16-bit integers to floating point, perform the needed processing, and convert back to 16-bit integers before returning the data.

§Example, converting i16 to and from f32

use audioadapter_sample::sample::RawSample;

// make a vector with some dummy data.
let indata: Vec<i16> = vec![1, 2, 3, 4];
let mut outdata: Vec<i16> = Vec::new();

for sample in indata.iter() {
  // convert to f32
  let float_sample: f32 = sample.to_scaled_float();
  // do some processing
  let processed_sample = 0.99 * float_sample;
  // convert back to 16-bit integer
  let processed_int = i16::from_scaled_float(processed_sample);
  if processed_int.clipped {
    println!("The value was clipped during conversion to integer");
  }
  outdata.push(processed_int.value);
}

§Example, converting 16-bit integers from raw bytes to f32

use audioadapter_sample::sample::I16_LE;
use audioadapter_sample::sample::BytesSample;
use audioadapter_sample::sample::RawSample;

// Make a vector with some dummy data.
// 6 bytes corresponding to 3 samples.
let bytes = vec![1, 2, 3, 4, 5, 6];

for sample in bytes.chunks_exact(2) {
  let new_value: f32 = I16_LE::from_slice(sample).to_scaled_float();
  println!("{}", new_value);
}

§Reading and writing samples from types implementing Read and Write

The std::io::Read and std::io::Write traits are useful for reading and writing raw bytes to and from for example files. The readwrite module extends these traits by providing methods for reading and writing samples, with on-the-fly conversion between bytes and the numerical values. This functionality depends on the standard library and is gated by the std Cargo feature.

Example

use audioadapter_sample::sample::I16_LE;
use audioadapter_sample::readwrite::ReadSamples;

// make a vector with some dummy data.
let data: Vec<u8> = vec![1, 2, 3, 4];
// slices implement Read.
let mut slice = &data[..];
// read the first value as 16 bit integer, convert to f32.
let float_value = slice.read_converted::<I16_LE, f32>();

§Cargo features

This crate has the following features:

  • std - enables the standard library (Enabled by default)

§Use without the standard library

This crate can be used in no_std environments if the std Cargo feature is disabled.

§Changelog

See the changelog.

§License

Licensed under either of

at your option.

Modules§

readwrite
Extensions to the standard std::io::Read and std::io::Write traits.
sample
Type conversion of samples values.