Struct AudioFrame

Source

pub struct AudioFrame { /* private fields */ }

Expand description

A decoded audio frame.

This structure holds audio sample data and metadata for a segment of audio. It supports both packed (interleaved) formats where all channels are interleaved in a single buffer, and planar formats where each channel is stored in a separate buffer.

§Memory Layout

For packed (interleaved) formats (I16, F32, etc.):

Single plane containing interleaved samples: L R L R L R …
Total size: samples * channels * bytes_per_sample

For planar formats (I16p, F32p, etc.):

One plane per channel
Each plane size: samples * bytes_per_sample

§Examples

use ff_format::{AudioFrame, SampleFormat, Timestamp, Rational};

// Create a stereo F32 frame with 1024 samples at 48kHz
let frame = AudioFrame::empty(1024, 2, 48000, SampleFormat::F32).unwrap();

assert_eq!(frame.samples(), 1024);
assert_eq!(frame.channels(), 2);
assert_eq!(frame.sample_rate(), 48000);
assert_eq!(frame.format(), SampleFormat::F32);

// Duration of this frame: 1024 / 48000 ≈ 21.33ms
let duration = frame.duration();
assert!((duration.as_secs_f64() - 0.02133).abs() < 0.001);

Implementations§

Source §

impl AudioFrame

Source

pub fn new( planes: Vec<Vec<u8>>, samples: usize, channels: u32, sample_rate: u32, format: SampleFormat, timestamp: Timestamp, ) -> Result<Self, FrameError>

Creates a new audio frame with the specified parameters.

§Arguments

planes - Audio sample data (1 plane for packed, channels for planar)
samples - Number of samples per channel
channels - Number of audio channels
sample_rate - Sample rate in Hz
format - Sample format
timestamp - Presentation timestamp

§Errors

Returns FrameError::InvalidPlaneCount if the number of planes doesn’t match the format (1 for packed, channels for planar).

§Examples

use ff_format::{AudioFrame, SampleFormat, Timestamp};

// Create a mono F32 frame with 1024 samples
let samples = 1024;
let bytes_per_sample = 4; // F32
let data = vec![0u8; samples * bytes_per_sample];

let frame = AudioFrame::new(
    vec![data],
    samples,
    1,
    48000,
    SampleFormat::F32,
    Timestamp::default(),
).unwrap();

assert_eq!(frame.samples(), 1024);
assert_eq!(frame.channels(), 1);

Source

pub fn empty( samples: usize, channels: u32, sample_rate: u32, format: SampleFormat, ) -> Result<Self, FrameError>

Creates an empty audio frame with the specified parameters.

The frame will have properly sized planes filled with zeros.

§Arguments

samples - Number of samples per channel
channels - Number of audio channels
sample_rate - Sample rate in Hz
format - Sample format

§Errors

Returns FrameError::UnsupportedSampleFormat if the format is SampleFormat::Other, as the memory layout cannot be determined.

§Examples

use ff_format::{AudioFrame, SampleFormat};

// Create a stereo I16 frame
let frame = AudioFrame::empty(1024, 2, 44100, SampleFormat::I16).unwrap();
assert_eq!(frame.samples(), 1024);
assert_eq!(frame.channels(), 2);
assert_eq!(frame.num_planes(), 1); // Packed format

Source

pub const fn samples(&self) -> usize

Returns the number of samples per channel.

§Examples

use ff_format::{AudioFrame, SampleFormat};

let frame = AudioFrame::empty(1024, 2, 48000, SampleFormat::F32).unwrap();
assert_eq!(frame.samples(), 1024);

Source

pub const fn channels(&self) -> u32

Returns the number of audio channels.

§Examples

use ff_format::{AudioFrame, SampleFormat};

let frame = AudioFrame::empty(1024, 2, 48000, SampleFormat::F32).unwrap();
assert_eq!(frame.channels(), 2);

Source

pub const fn sample_rate(&self) -> u32

Returns the sample rate in Hz.

§Examples

use ff_format::{AudioFrame, SampleFormat};

let frame = AudioFrame::empty(1024, 2, 48000, SampleFormat::F32).unwrap();
assert_eq!(frame.sample_rate(), 48000);

Source

pub const fn format(&self) -> SampleFormat

Returns the sample format.

§Examples

use ff_format::{AudioFrame, SampleFormat};

let frame = AudioFrame::empty(1024, 2, 48000, SampleFormat::F32).unwrap();
assert_eq!(frame.format(), SampleFormat::F32);
assert!(frame.format().is_float());

Source

pub const fn timestamp(&self) -> Timestamp

Returns the presentation timestamp.

§Examples

use ff_format::{AudioFrame, SampleFormat, Timestamp, Rational};

let ts = Timestamp::new(48000, Rational::new(1, 48000));
let mut frame = AudioFrame::empty(1024, 2, 48000, SampleFormat::F32).unwrap();
frame.set_timestamp(ts);
assert_eq!(frame.timestamp(), ts);

Source

pub fn set_timestamp(&mut self, timestamp: Timestamp)

Sets the presentation timestamp.

§Examples

use ff_format::{AudioFrame, SampleFormat, Timestamp, Rational};

let mut frame = AudioFrame::empty(1024, 2, 48000, SampleFormat::F32).unwrap();
let ts = Timestamp::new(48000, Rational::new(1, 48000));
frame.set_timestamp(ts);
assert_eq!(frame.timestamp(), ts);

Source

pub fn duration(&self) -> Duration

Returns the duration of this audio frame.

The duration is calculated as samples / sample_rate.

§Examples

use ff_format::{AudioFrame, SampleFormat};

// 1024 samples at 48kHz = ~21.33ms
let frame = AudioFrame::empty(1024, 2, 48000, SampleFormat::F32).unwrap();
let duration = frame.duration();
assert!((duration.as_secs_f64() - 0.02133).abs() < 0.001);

// 48000 samples at 48kHz = 1 second
let frame = AudioFrame::empty(48000, 2, 48000, SampleFormat::F32).unwrap();
assert_eq!(frame.duration().as_secs(), 1);

Source

pub fn num_planes(&self) -> usize

Returns the number of planes in this frame.

Packed formats: 1 plane (interleaved channels)
Planar formats: 1 plane per channel

§Examples

use ff_format::{AudioFrame, SampleFormat};

// Packed format - 1 plane
let packed = AudioFrame::empty(1024, 2, 48000, SampleFormat::F32).unwrap();
assert_eq!(packed.num_planes(), 1);

// Planar format - 1 plane per channel
let planar = AudioFrame::empty(1024, 2, 48000, SampleFormat::F32p).unwrap();
assert_eq!(planar.num_planes(), 2);

Source

pub fn planes(&self) -> &[Vec<u8>]

Returns a slice of all plane data.

§Examples

use ff_format::{AudioFrame, SampleFormat};

let frame = AudioFrame::empty(1024, 2, 48000, SampleFormat::F32p).unwrap();
let planes = frame.planes();
assert_eq!(planes.len(), 2);

Source

pub fn plane(&self, index: usize) -> Option<&[u8]>

Returns the data for a specific plane, or None if the index is out of bounds.

For packed formats, use plane(0). For planar formats, use plane(channel_index).

§Arguments

index - The plane index (0 for packed, channel index for planar)

§Examples

use ff_format::{AudioFrame, SampleFormat};

let frame = AudioFrame::empty(1024, 2, 48000, SampleFormat::F32p).unwrap();

// Access left channel (plane 0)
assert!(frame.plane(0).is_some());

// Access right channel (plane 1)
assert!(frame.plane(1).is_some());

// No third channel
assert!(frame.plane(2).is_none());

Source

pub fn plane_mut(&mut self, index: usize) -> Option<&mut [u8]>

Returns mutable access to a specific plane’s data.

§Arguments

index - The plane index

§Examples

use ff_format::{AudioFrame, SampleFormat};

let mut frame = AudioFrame::empty(1024, 2, 48000, SampleFormat::F32p).unwrap();
if let Some(data) = frame.plane_mut(0) {
    // Modify left channel
    data[0] = 128;
}

Source

pub fn channel(&self, channel: usize) -> Option<&[u8]>

Returns the channel data for planar formats.

This is an alias for plane() that’s more semantically meaningful for audio data.

§Arguments

channel - The channel index (0 = left, 1 = right, etc.)

§Examples

use ff_format::{AudioFrame, SampleFormat};

let frame = AudioFrame::empty(1024, 2, 48000, SampleFormat::F32p).unwrap();

// Get left channel data
let left = frame.channel(0).unwrap();
assert_eq!(left.len(), 1024 * 4); // 1024 samples * 4 bytes

Source

pub fn channel_mut(&mut self, channel: usize) -> Option<&mut [u8]>

Returns mutable access to channel data for planar formats.

§Arguments

channel - The channel index

Source

pub fn data(&self) -> Option<&[u8]>

Returns the raw sample data as a contiguous byte slice.

For packed formats, this returns a reference to the single plane. For planar formats, this returns None (use channel() instead).

§Examples

use ff_format::{AudioFrame, SampleFormat};

// Packed format - returns data
let packed = AudioFrame::empty(1024, 2, 48000, SampleFormat::F32).unwrap();
assert!(packed.data().is_some());
assert_eq!(packed.data().unwrap().len(), 1024 * 2 * 4);

// Planar format - returns None
let planar = AudioFrame::empty(1024, 2, 48000, SampleFormat::F32p).unwrap();
assert!(planar.data().is_none());

Source

pub fn data_mut(&mut self) -> Option<&mut [u8]>

Returns mutable access to the raw sample data.

Only available for packed formats.

§Examples

use ff_format::{AudioFrame, SampleFormat};

let mut frame = AudioFrame::empty(1024, 2, 48000, SampleFormat::F32).unwrap();
if let Some(data) = frame.data_mut() {
    data[0] = 128;
}

Source

pub fn as_f32(&self) -> Option<&[f32]>

Returns the sample data as an f32 slice.

This only works if the format is SampleFormat::F32 (packed). For planar F32p format, use channel_as_f32().

§Safety Note

This method reinterprets the raw bytes as f32 values. It requires proper alignment and format matching.

§Examples

use ff_format::{AudioFrame, SampleFormat};

let frame = AudioFrame::empty(1024, 2, 48000, SampleFormat::F32).unwrap();
if let Some(samples) = frame.as_f32() {
    assert_eq!(samples.len(), 1024 * 2); // samples * channels
}

Source

pub fn as_f32_mut(&mut self) -> Option<&mut [f32]>

Returns mutable access to sample data as an f32 slice.

Only works for SampleFormat::F32 (packed).

Source

pub fn as_i16(&self) -> Option<&[i16]>

Returns the sample data as an i16 slice.

This only works if the format is SampleFormat::I16 (packed). For planar I16p format, use channel_as_i16().

§Examples

use ff_format::{AudioFrame, SampleFormat};

let frame = AudioFrame::empty(1024, 2, 48000, SampleFormat::I16).unwrap();
if let Some(samples) = frame.as_i16() {
    assert_eq!(samples.len(), 1024 * 2);
}

Source

pub fn as_i16_mut(&mut self) -> Option<&mut [i16]>

Returns mutable access to sample data as an i16 slice.

Only works for SampleFormat::I16 (packed).

Source

pub fn channel_as_f32(&self, channel: usize) -> Option<&[f32]>

Returns a specific channel’s data as an f32 slice.

Works for planar F32p format.

§Arguments

channel - The channel index

§Examples

use ff_format::{AudioFrame, SampleFormat};

let frame = AudioFrame::empty(1024, 2, 48000, SampleFormat::F32p).unwrap();
if let Some(left) = frame.channel_as_f32(0) {
    assert_eq!(left.len(), 1024);
}

Source

pub fn channel_as_f32_mut(&mut self, channel: usize) -> Option<&mut [f32]>

Returns mutable access to a channel’s data as an f32 slice.

Works for planar F32p format.

Source

pub fn channel_as_i16(&self, channel: usize) -> Option<&[i16]>

Returns a specific channel’s data as an i16 slice.

Works for planar I16p format.

§Arguments

channel - The channel index

§Examples

use ff_format::{AudioFrame, SampleFormat};

let frame = AudioFrame::empty(1024, 2, 48000, SampleFormat::I16p).unwrap();
if let Some(left) = frame.channel_as_i16(0) {
    assert_eq!(left.len(), 1024);
}

Source

pub fn channel_as_i16_mut(&mut self, channel: usize) -> Option<&mut [i16]>

Returns mutable access to a channel’s data as an i16 slice.

Works for planar I16p format.

Source

pub fn total_size(&self) -> usize

Returns the total size in bytes of all sample data.

§Examples

use ff_format::{AudioFrame, SampleFormat};

let frame = AudioFrame::empty(1024, 2, 48000, SampleFormat::F32).unwrap();
assert_eq!(frame.total_size(), 1024 * 2 * 4);

Source

pub fn bytes_per_sample(&self) -> usize

Returns the size in bytes of a single sample (one channel).

§Examples

use ff_format::{AudioFrame, SampleFormat};

let frame = AudioFrame::empty(1024, 2, 48000, SampleFormat::F32).unwrap();
assert_eq!(frame.bytes_per_sample(), 4);

let frame = AudioFrame::empty(1024, 2, 48000, SampleFormat::I16).unwrap();
assert_eq!(frame.bytes_per_sample(), 2);