Struct SpectrogramPlanner

Source

#[non_exhaustive]
pub struct SpectrogramPlanner;

Expand description

A planner is an object that can build spectrogram plans.

In your design, this is where:

FFT plans are created
mapping matrices are compiled
axes are computed

This allows you to keep plan building separate from the output types.

Implementations§

Source §

impl SpectrogramPlanner

Source

pub const fn new() -> Self

Create a new spectrogram planner.

§Returns

A new SpectrogramPlanner instance.

Source

pub fn compute_stft<T: Sample>( &self, samples: &NonEmptySlice<T>, params: &SpectrogramParams, ) -> SpectrogramResult<StftResult<T>>

Compute the Short-Time Fourier Transform (STFT) of a signal.

This returns the raw complex STFT matrix before any frequency mapping or amplitude scaling. Useful for applications that need the full complex spectrum or custom processing.

§Arguments

samples - Audio samples (any type that can be converted to a slice)
params - STFT computation parameters

§Returns

An StftResult containing the complex STFT matrix and metadata.

§Errors

Returns an error if STFT computation fails.

§Examples

use spectrograms::*;
use non_empty_slice::non_empty_vec;

let samples = non_empty_vec![0.0; nzu!(16000)];
let stft = StftParams::new(nzu!(512), nzu!(256), WindowType::Hanning, true)?;
let params = SpectrogramParams::new(stft, 16000.0)?;

let planner = SpectrogramPlanner::new();
let stft_result = planner.compute_stft(&samples, &params)?;

println!("STFT: {} bins x {} frames", stft_result.n_bins(), stft_result.n_frames());

§Performance Note

This method creates a new FFT plan each time. For processing multiple signals, create a reusable plan with StftPlan::new() instead.

§Examples

use spectrograms::*;
use non_empty_slice::non_empty_vec;

let stft = StftParams::new(nzu!(512), nzu!(256), WindowType::Hanning, true)?;
let params = SpectrogramParams::new(stft, 16000.0)?;

// One-shot (convenient)
let planner = SpectrogramPlanner::new();
let stft_result = planner.compute_stft(&non_empty_vec![0.0; nzu!(16000)], &params)?;

// Reusable plan (efficient for batch)
let mut plan = StftPlan::new(&params)?;
for signal in &[non_empty_vec![0.0; nzu!(16000)], non_empty_vec![1.0; nzu!(16000)]] {
    let stft = plan.compute(&signal, &params)?;
}

Source

pub fn compute_power_spectrum( &self, samples: &NonEmptySlice<f64>, n_fft: NonZeroUsize, window: WindowType, ) -> SpectrogramResult<NonEmptyVec<f64>>

Compute the power spectrum of a single audio frame.

This is useful for real-time processing or analyzing individual frames.

§Arguments

samples - Audio frame (length ≤ n_fft, will be zero-padded if shorter)
n_fft - FFT size
window - Window type to apply

§Returns

A vector of power values (|X|²) with length n_fft/2 + 1.

§Automatic Zero-Padding

If the input signal is shorter than n_fft, it will be automatically zero-padded to the required length.

§Errors

Returns InvalidInput error if the input length exceeds n_fft.

§Examples

use spectrograms::*;
use non_empty_slice::non_empty_vec;

let frame = non_empty_vec![0.0; nzu!(512)];

let planner = SpectrogramPlanner::new();
let power = planner.compute_power_spectrum(frame.as_ref(), nzu!(512), WindowType::Hanning)?;

assert_eq!(power.len(), nzu!(257)); // 512/2 + 1

Source

pub fn compute_magnitude_spectrum( &self, samples: &NonEmptySlice<f64>, n_fft: NonZeroUsize, window: WindowType, ) -> SpectrogramResult<NonEmptyVec<f64>>

Compute the magnitude spectrum of a single audio frame.

This is useful for real-time processing or analyzing individual frames.

§Arguments

samples - Audio frame (length ≤ n_fft, will be zero-padded if shorter)
n_fft - FFT size
window - Window type to apply

§Returns

A vector of magnitude values (|X|) with length n_fft/2 + 1.

§Automatic Zero-Padding

If the input signal is shorter than n_fft, it will be automatically zero-padded to the required length.

§Errors

Returns InvalidInput error if the input length exceeds n_fft.

§Examples

use spectrograms::*;
use non_empty_slice::non_empty_vec;

let frame = non_empty_vec![0.0; nzu!(512)];

let planner = SpectrogramPlanner::new();
let magnitude = planner.compute_magnitude_spectrum(frame.as_ref(), nzu!(512), WindowType::Hanning)?;

assert_eq!(magnitude.len(), nzu!(257)); // 512/2 + 1