Crate spectrum_analyzer

Expand description

An easy to use and fast no_std library (with alloc) to get the frequency spectrum of a digital signal (e.g. audio) using FFT.

§Getting started

If you are unsure what to pick, start here. The samples_fft_to_spectrum() function is the entry into the library. The following configuration works for most cases: take a block of samples, apply a Hann window, and divide the result by the number of samples.

use spectrum_analyzer::scaling::divide_by_N;
use spectrum_analyzer::windows::hann_window;
use spectrum_analyzer::{FrequencyLimit, samples_fft_to_spectrum};

// your samples; the length must be a power of two
let samples = vec![0.0; 2048];

let windowed = hann_window(&samples);
let spectrum = samples_fft_to_spectrum(
    &windowed,
    44100,
    FrequencyLimit::All,
    Some(&divide_by_N),
)
.unwrap();

// the loudest frequency in the block
let (frequency, value) = spectrum.max();

§How many samples?

More samples mean a finer frequency resolution (sample_rate / N), but they also cover a longer time span, so the spectrum reacts more slowly to changes. At 44100 Hz, 2048 samples (~46 ms, ~22 Hz per bin) are a good starting point, 4096 if you need to tell close frequencies apart.

§What next?

windows: which window function to apply
scaling: which scaling to apply
samples_fft_to_spectrum: what the resulting values mean
FrequencySpectrum: what you can read from the result, e.g. FrequencySpectrum::max for the loudest frequency, FrequencySpectrum::freq_val_closest for one specific frequency, or FrequencySpectrum::data to iterate over all of them

§Examples

§Scaling via dynamic closure

use spectrum_analyzer::{samples_fft_to_spectrum, FrequencyLimit};
// get data from audio source, ideally in range `-1.0..=1.0`
let samples = vec![0.0, 1.1, 5.5, -5.5];
let res = samples_fft_to_spectrum(
        &samples,
        44100,
        FrequencyLimit::All,
        // Create your scaling function as closure on the fly as needed.
        Some(&|val, info| val - info.min),
);

§Scaling via static function

use spectrum_analyzer::{samples_fft_to_spectrum, FrequencyLimit};
use spectrum_analyzer::scaling::divide_by_N;
// get data from audio source, ideally in range `-1.0..=1.0`
let samples = vec![0.0, 1.1, 5.5, -5.5];
let res = samples_fft_to_spectrum(
        &samples,
        44100,
        FrequencyLimit::All,
        // Use one of the provided scaling functions. Here, we make the
        // values independent of the number of samples.
        Some(&divide_by_N),
);

Modules§

error: Errors related to the spectrum analysis via FFT. Most probably, the errors will result in wrong input data, before the actual calculation has begun.
scaling: This module contains convenient public transform functions that you can use as parameters in samples_fft_to_spectrum for scaling the frequency value (the FFT result).
windows: Several window functions which you can apply before doing the FFT. For more information:

Structs§

FiniteF32: Wrapper around f32 that guarantees a finite number, i.e., neither NaN nor infinite. This makes the number orderable and sortable.
FrequencySpectrum: Convenient wrapper around the processed FFT result.
NonNegF32: Wrapper around FiniteF32 that additionally guarantees a number that is not negative, so 0.0 or higher.

Enums§

FrequencyLimit: Can be used to specify a desired frequency limit.
FrequencyLimitError: Possible errors when creating a FrequencyLimit-object.

Functions§

samples_fft_to_spectrum: Takes an array of samples (length must be a power of 2, such as 2048), applies an FFT, and returns all frequencies with their magnitude.

Type Aliases§

Frequency: A frequency in Hertz, which is never negative.
FrequencyValue: The value of a Frequency in a frequency spectrum.