Frequency-domain representation of a multi-channel audio signal. More...

#include <hart_spectrum.hpp>

Classes
class	ColouredNoise
	Options for `colouredNoise()` method. More...

Public Types
enum	BetaFor { whiteNoise = 0 , pinkNoise = -1 , brownNoise = -2 , blueNoise = 1 , violetNoise = 2 }
	Common values for `beta` argument in the `colouredNoise()` factory. More...

Public Member Functions
template<typename SampleType >
	Spectrum (const AudioBuffer< SampleType > &buffer)
	Constructs spectrum from an audio buffer.

size_t	getNumChannels () const
	Returns number of channels.

size_t	getNumBins () const
	Returns number of frequency bins per channel.

size_t	getFFTSize () const
	Returns FFT size.

size_t	getSizeInTimeDomainFrames () const
	Returns original audio buffer duration in frames.

double	getSampleRateHz () const
	Returns sample rate in Hz.

template<typename SampleType >
AudioBuffer< SampleType >	toAudioBuffer () const
	Converts this spectrum to a time-domain audio buffer.

template<typename SampleType >
AudioBufferSignal< SampleType >	toSignal (Loop loop=Loop::no) const
	Converts the audio represented by this Spectrum to a Signal source.

bool	equalsTo (const Spectrum &other, double toleranceLinear=1e-6) const
	Checks whether this spectrum contains approximately the same data as another spectrum.

bool	operator== (const Spectrum &other) const
	Checks whether two spectra contain approximately the same data.

bool	operator!= (const Spectrum &other) const
	Checks whether two spectra differ beyond the default comparison tolerance.

Spectrum	operator* (double gainLinear) const
	Creates a new spectrum as a multiplying each complex bin value by a provided gain value.

double	getBinFrequencyHz (size_t binIndex) const
	Returns frequency corresponding to a bin index.

double	getBinWidthHz () const

std::complex< double >	getBinValue (size_t channel, size_t binIndex) const
	Returns complex value of a frequency bin, by bin index.

std::complex< double >	getBinValue (size_t channel, double frequencyHz) const
	Returns complex value of a frequency bin, by frequency.

double	getBinMagnitude (size_t channel, size_t binIndex) const
	Returns magnitude of a frequency bin, by bin index.

double	getBinMagnitude (size_t channel, double frequencyHz) const
	Returns magnitude of a frequency bin, by frequency.

const std::complex< double > *	operator[] (size_t channel) const
	Returns pointer to read-only magnitudes of a specific channel.

std::complex< double > *	operator[] (size_t channel)
	Returns pointer to mutable magnitudes of a specific channel.

size_t	findClosestBin (double frequencyHz) const
	Finds closest FFT bin to a given frequency.

std::pair< size_t, size_t >	getBinIndices (const Slice &slice) const
	Returns a pair of indices representing a provided slice.

void	represent (std::ostream &stream) const
	Prints readable representation of the spectrum object.

Static Public Member Functions
static Spectrum	zeros (size_t numChannels=CLIConfig::getInstance().getDefaultNumInputChannels(), size_t signalDurationFrames=CLIConfig::getInstance().getDefaultRenderDurationFrames(), double sampleRateHz=CLIConfig::getInstance().getDefaultSampleRateHz())

static Spectrum	colouredNoise (ColouredNoise options)
	Creates deterministic coloured noise in the frequency domain.

Related Symbols
(Note that these are not member symbols.)
std::ostream &	operator<< (std::ostream &stream, const Spectrum &spectrum)
	Prints readable text representation of the spectrum object into the I/O stream.

Detailed Description

Frequency-domain representation of a multi-channel audio signal.

Stores complex spectra for each channel independently. Spectrum is constructed by performing FFT on the entire signal, zero-padding to the next power-of-two size if necessary.

Current implementation assumptions:

Rectangular window (no windowing)
Real-valued input signal
One-sided spectrum only (fftSize / 2 + 1 bins)
Double floating-point precision, regardless of input signal value types

Definition at line 33 of file hart_spectrum.hpp.

Member Enumeration Documentation

◆ BetaFor

enum BetaFor

Common values for beta argument in the colouredNoise() factory.

Enumerator
whiteNoise	`beta` value for white noise, for the `colouredNoise()` factory
pinkNoise	`beta` value for pink noise, for the `colouredNoise()` factory
brownNoise	`beta` value for brown (a.k.a. red, or Brownian) noise, for the `colouredNoise()` factory
blueNoise	`beta` value for blue noise, for the `colouredNoise()` factory
violetNoise	`beta` value for violet noise, for the `colouredNoise()` factory

Definition at line 106 of file hart_spectrum.hpp.

Constructor & Destructor Documentation

◆ Spectrum()

template<typename SampleType >

Spectrum ( const AudioBuffer< SampleType > & buffer )

inline

Constructs spectrum from an audio buffer.

Parameters

buffer Audio buffer to perform FFT on

Exceptions

hart::SampleRateError if the audio buffer has no sample rate metadata

Definition at line 40 of file hart_spectrum.hpp.

Member Function Documentation

◆ zeros()

static Spectrum zeros	(	size_t	numChannels = `CLIConfig::getInstance().getDefaultNumInputChannels()`,
		size_t	signalDurationFrames = `CLIConfig::getInstance().getDefaultRenderDurationFrames()`,
		double	sampleRateHz = `CLIConfig::getInstance().getDefaultSampleRateHz()`
	)

inlinestatic

Definition at line 74 of file hart_spectrum.hpp.

◆ colouredNoise()

static Spectrum colouredNoise ( ColouredNoise options )

inlinestatic

Creates deterministic coloured noise in the frequency domain.

beta is interpreted as a power-spectrum exponent, so the stored bin magnitudes follow:

\[ |X(f)| \propto {f_{rel}}^ \frac{\beta}{2} \]

(|X(f)| ~ f_rel ** (beta / 2)),

where f_rel = frequency / lowCutoffHz.

Parameters

options ColouredNoise containing

Definition at line 277 of file hart_spectrum.hpp.

◆ getNumChannels()

size_t getNumChannels ( ) const

inline

Returns number of channels.

Definition at line 318 of file hart_spectrum.hpp.

◆ getNumBins()

size_t getNumBins ( ) const

inline

Returns number of frequency bins per channel.

Definition at line 324 of file hart_spectrum.hpp.

◆ getFFTSize()

size_t getFFTSize ( ) const

inline

Returns FFT size.

Definition at line 330 of file hart_spectrum.hpp.

◆ getSizeInTimeDomainFrames()

size_t getSizeInTimeDomainFrames ( ) const

inline

Returns original audio buffer duration in frames.

Definition at line 336 of file hart_spectrum.hpp.

◆ getSampleRateHz()

double getSampleRateHz ( ) const

inline

Returns sample rate in Hz.

Definition at line 342 of file hart_spectrum.hpp.

◆ toAudioBuffer()

template<typename SampleType >

AudioBuffer< SampleType > toAudioBuffer ( ) const

inline

Converts this spectrum to a time-domain audio buffer.

Reconstructs the omitted negative-frequency bins from Hermitian symmetry, performs an inverse FFT, and trims the result to the original signal length.

Template Parameters

SampleType Type of samples for the resulting buffer, typically float or double

Definition at line 354 of file hart_spectrum.hpp.

◆ toSignal()

template<typename SampleType >

AudioBufferSignal< SampleType > toSignal ( Loop loop = Loop::no ) const

inline

Converts the audio represented by this Spectrum to a Signal source.

Parameters

loop	Whether the signal should loop after the data represented by this Spectrum's implied diration runs out

Template Parameters

SampleType Type of sample sata generated by the signal, typically float or double

Returns: AudioBufferSignal instance, playing the signal with the spectrum identical to this one

Definition at line 386 of file hart_spectrum.hpp.

◆ equalsTo()

bool equalsTo	(	const Spectrum &	other,
		double	toleranceLinear = `1e-6`
	)		const

inline

Checks whether this spectrum contains approximately the same data as another spectrum.

The comparison is relaxed - each pair of corresponding complex bins must differ by no more than toleranceLinear. Both spectra must have the same dimensions, FFT size, time-domain size, and sample rate.

Parameters

other	Spectrum to compare against
toleranceLinear	Absolute complex-bin tolerance in linear domain, for both real and imaginary parts.

Returns: true if the spectra are equal within the specified tolerance, false otherwise

Definition at line 399 of file hart_spectrum.hpp.

◆ operator==()

bool operator== ( const Spectrum & other ) const

inline

Checks whether two spectra contain approximately the same data.

Equivalent to calling Spectrum::equalsTo (other) with the default tolerance

Parameters

other Spectrum to compare against

Returns: true if the spectra are equal within the default tolerance, false otherwise

Definition at line 429 of file hart_spectrum.hpp.

◆ operator!=()

bool operator!= ( const Spectrum & other ) const

inline

Checks whether two spectra differ beyond the default comparison tolerance.

Equivalent to ! Spectrum::equalsTo (other)

Parameters

other Spectrum to compare against

Returns: true if the spectra are not equal within the default tolerance, false otherwise

Definition at line 438 of file hart_spectrum.hpp.

◆ operator*()

Spectrum operator* ( double gainLinear ) const

inline

Creates a new spectrum as a multiplying each complex bin value by a provided gain value.

Parameters

other gainLinear Gain to multiply each complex bin by

Returns: A new Spectrum that is a result of multiplication

Definition at line 446 of file hart_spectrum.hpp.

◆ getBinFrequencyHz()

double getBinFrequencyHz ( size_t binIndex ) const

inline

Returns frequency corresponding to a bin index.

Definition at line 462 of file hart_spectrum.hpp.

◆ getBinWidthHz()

double getBinWidthHz ( ) const

inline

Definition at line 470 of file hart_spectrum.hpp.

◆ getBinValue() [1/2]

std::complex< double > getBinValue	(	size_t	channel,
		size_t	binIndex
	)		const

inline

Returns complex value of a frequency bin, by bin index.

Definition at line 476 of file hart_spectrum.hpp.

◆ getBinValue() [2/2]

std::complex< double > getBinValue	(	size_t	channel,
		double	frequencyHz
	)		const

inline

Returns complex value of a frequency bin, by frequency.

Definition at line 488 of file hart_spectrum.hpp.

◆ getBinMagnitude() [1/2]

double getBinMagnitude	(	size_t	channel,
		size_t	binIndex
	)		const

inline

Returns magnitude of a frequency bin, by bin index.

Definition at line 494 of file hart_spectrum.hpp.

◆ getBinMagnitude() [2/2]

double getBinMagnitude	(	size_t	channel,
		double	frequencyHz
	)		const

inline

Returns magnitude of a frequency bin, by frequency.

Definition at line 500 of file hart_spectrum.hpp.

◆ operator[]() [1/2]

const std::complex< double > * operator[] ( size_t channel ) const

inline

Returns pointer to read-only magnitudes of a specific channel.

Definition at line 506 of file hart_spectrum.hpp.

◆ operator[]() [2/2]

std::complex< double > * operator[] ( size_t channel )

inline

Returns pointer to mutable magnitudes of a specific channel.

Definition at line 515 of file hart_spectrum.hpp.

◆ findClosestBin()

size_t findClosestBin ( double frequencyHz ) const

inline

Finds closest FFT bin to a given frequency.

Definition at line 524 of file hart_spectrum.hpp.

◆ getBinIndices()

std::pair< size_t, size_t > getBinIndices ( const Slice & slice ) const

inline

Returns a pair of indices representing a provided slice.

Parameters

slice A Slice instance. Valid slice types are Slice::Type::whole Slice::Type::bins and Slice::Type::freq

Return values

first	Index representing the beginning of the range, inclusive
second	Index representing the end of the range, non-inclusive

Definition at line 538 of file hart_spectrum.hpp.

◆ represent()

void represent ( std::ostream & stream ) const

inline

Prints readable representation of the spectrum object.

Parameters

stream String stream to append the representation to

Definition at line 580 of file hart_spectrum.hpp.

Friends And Related Symbol Documentation

◆ operator<<

std::ostream & operator<<	(	std::ostream &	stream,
		const Spectrum &	spectrum
	)

friend

Prints readable text representation of the spectrum object into the I/O stream.

Definition at line 587 of file hart_spectrum.hpp.

The documentation for this class was generated from the following file:

include/hart_spectrum.hpp

Classes

Public Types

Public Member Functions

Static Public Member Functions

Related Symbols

Detailed Description

Member Enumeration Documentation

◆ BetaFor

Constructor & Destructor Documentation

◆ Spectrum()

Member Function Documentation

◆ zeros()

◆ colouredNoise()

◆ getNumChannels()

◆ getNumBins()

◆ getFFTSize()

◆ getSizeInTimeDomainFrames()

◆ getSampleRateHz()

◆ toAudioBuffer()

◆ toSignal()

◆ equalsTo()

◆ operator==()

◆ operator!=()

◆ operator*()

◆ getBinFrequencyHz()

◆ getBinWidthHz()

◆ getBinValue() [1/2]

◆ getBinValue() [2/2]

◆ getBinMagnitude() [1/2]

◆ getBinMagnitude() [2/2]

◆ operator[]() [1/2]

◆ operator[]() [2/2]

◆ findClosestBin()

◆ getBinIndices()

◆ represent()

Friends And Related Symbol Documentation

◆ operator<<