A stereo generator that preserves the delayed original mid signal. More...

#include <StereoGenerator.h>

Classes
struct	Options
	Configuration applied by prepare(), never by the audio callback. More...

Public Types
enum class	Status { Ok , NotPrepared , InvalidInput , ClockOverflow , NumericalFailure }
	Result of the last processing call (also readable by a UI). More...

Public Member Functions
	StereoGenerator ()=default

	StereoGenerator (const StereoGenerator &)=delete

StereoGenerator &	operator= (const StereoGenerator &)=delete

bool	prepare (const AudioSpec &spec)
	Prepares pending options for stereo at 8 to 384 kHz. Invalid settings return false, leaving the previous prepared state intact. Allocation failure propagates with the same strong state guarantee.

bool	prepare (const AudioSpec &spec, Options options)
	Prepares explicit options; on success clears all stream history.

bool	setWidth (float width) noexcept
	Publishes width in [0,1]. Invalid values return false unchanged.

float	getWidth () const noexcept
	Returns the published target, not the instantaneous ramp value.

Options	getOptions () const noexcept
	Returns options for the next prepare (including restored presets).

int	getLatency () const noexcept
	Exact active delay in source frames, including the optional FIR.

Status	getStatus () const noexcept
	Returns the last processing status. Numerical failure latches until reset.

std::uint64_t	getSourceFrame () const noexcept
	Returns the next input frame on this stream's source clock.

void	reset () noexcept
	Clears history and restarts modulation at source frame zero.

void	resetAtFrame (std::uint64_t frame) noexcept
	Clears history and aligns modulation to an absolute source frame. This is not a seek restore: replay the preceding audio to recover filter history. The 64-frame modulation grid stays anchored to source frame zero. The clock is 64-bit; LFO time/phase is evaluated in double precision.

bool	processBlock (AudioBufferView< T > buffer) noexcept
	Processes writable, nonoverlapping stereo channels in place. Returns false without changing input or advancing state for invalid layout, nonfinite input, oversized blocks or clock overflow. A numerical DSP failure returns false and replaces the affected internal chunk and subsequent audio with aligned dry input until reset; earlier chunks remain processed. Inspect getStatus() and handle the failure in the host. No finite-value clamp occurs.

bool	processBlock (AudioBufferView< T > buffer, std::span< double > generatedDelta) noexcept
	Also captures the generated mono delta before rounded L/R add-back. An empty span disables capture. Otherwise its length must match the block and its storage must not overlap either audio channel. The delta includes width and low cut, with the same alignment delay as output. A numerical failure writes zero delta for each affected chunk. No subtraction of large original samples is needed to recover a small generated component.

std::vector< std::uint8_t >	getState () const
	Serializes parameters only; filter history and source clock are excluded.

bool	setState (const std::uint8_t *data, std::size_t size)
	Restores a validated preset. Factor/low cut apply at the next prepare. Missing keys retain their settings; malformed/duplicate known keys reject the entire preset unchanged. Unknown keys are ignored for forward compatibility.

Static Public Member Functions
static std::size_t	getPrepareMemoryBound (const AudioSpec &spec, Options options) noexcept
	Conservative cumulative setup allocation bound, or zero for invalid settings. Includes state, temporary filter designs and supported vector/FFT overhead; excludes caller buffers and allocator bookkeeping. This query allocates nothing.

Detailed Description

template<typename T>
class dspark::StereoGenerator< T >

A stereo generator that preserves the delayed original mid signal.

A parallel copy passes through twenty moving bands and asymmetric/symmetric rational color. Its stereo delta is added to the original: L += delta, R -= delta. Width does not scale the original side. There is no limiter or automatic gain trim. Only the generated delta receives the optional low cut.

The color branch uses an explicit 0.45 Fs to 0.50 Fs FIR transition. The default factor is 1: continuous polynomial reconstruction, shared nonlinear integration and FIR moment projection all run at the source sample rate. Factors 2, 4, 8 and 16 select the oversampled color implementation at prepare time; factor 2 has lower measured antialias rejection than the 1x path. The source-clock DC response is retained at every factor. At 1x the alignment delay is 256 samples before an optional low cut. This is a mathematical source-topology model, not a claim of physical-device equivalence.

Width defaults to zero (exact delayed identity). Automation ramps for 5 ms using Core SmoothedValue and keeps latency constant. Input must be stereo; to generate stereo from mono, the caller duplicates mono into two channels. Feed zero input to flush a tail; getLatency() is alignment delay, not tail length. Reset clears history and snaps width to its current target.

Threading: prepare(), getOptions(), getState() and setState() require exclusive setup access. processBlock(), reset(), resetAtFrame() and getSourceFrame() belong to one audio stream. Only setWidth(), getWidth(), getStatus() and getLatency() may run concurrently with that stream. No callback allocations or locks. Destruction and prepare must not race any other access.

Template Parameters

T	float or double sample storage; the DSP path computes in double.

Definition at line 60 of file StereoGenerator.h.

Member Enumeration Documentation

◆ Status

template<typename T >

enum class dspark::StereoGenerator::Status

strong

Result of the last processing call (also readable by a UI).

Enumerator
Ok
NotPrepared
InvalidInput
ClockOverflow
NumericalFailure

Definition at line 75 of file StereoGenerator.h.

Constructor & Destructor Documentation

◆ StereoGenerator() [1/2]

template<typename T >

dspark::StereoGenerator< T >::StereoGenerator ( )

default

◆ StereoGenerator() [2/2]

template<typename T >

dspark::StereoGenerator< T >::StereoGenerator ( const StereoGenerator< T > & )

delete

Member Function Documentation

◆ getLatency()

template<typename T >

int dspark::StereoGenerator< T >::getLatency ( ) const

inlinenoexcept

Exact active delay in source frames, including the optional FIR.

Definition at line 156 of file StereoGenerator.h.

◆ getOptions()

template<typename T >

Options dspark::StereoGenerator< T >::getOptions ( ) const

inlinenoexcept

Returns options for the next prepare (including restored presets).

Definition at line 151 of file StereoGenerator.h.

◆ getPrepareMemoryBound()

template<typename T >

static std::size_t dspark::StereoGenerator< T >::getPrepareMemoryBound	(	const AudioSpec &	spec,
		Options	options
	)

inlinestaticnoexcept

Conservative cumulative setup allocation bound, or zero for invalid settings. Includes state, temporary filter designs and supported vector/FFT overhead; excludes caller buffers and allocator bookkeeping. This query allocates nothing.

Definition at line 92 of file StereoGenerator.h.

◆ getSourceFrame()

template<typename T >

std::uint64_t dspark::StereoGenerator< T >::getSourceFrame ( ) const

inlinenoexcept

Returns the next input frame on this stream's source clock.

Definition at line 166 of file StereoGenerator.h.

◆ getState()

template<typename T >

std::vector< std::uint8_t > dspark::StereoGenerator< T >::getState ( ) const

inline

Serializes parameters only; filter history and source clock are excluded.

Definition at line 257 of file StereoGenerator.h.

◆ getStatus()

template<typename T >

Status dspark::StereoGenerator< T >::getStatus ( ) const

inlinenoexcept

Returns the last processing status. Numerical failure latches until reset.

Definition at line 161 of file StereoGenerator.h.

◆ getWidth()

template<typename T >

float dspark::StereoGenerator< T >::getWidth ( ) const

inlinenoexcept

Returns the published target, not the instantaneous ramp value.

Definition at line 146 of file StereoGenerator.h.

◆ operator=()

template<typename T >

StereoGenerator & dspark::StereoGenerator< T >::operator= ( const StereoGenerator< T > & )

delete

◆ prepare() [1/2]

template<typename T >

bool dspark::StereoGenerator< T >::prepare ( const AudioSpec & spec )

inline

Prepares pending options for stereo at 8 to 384 kHz. Invalid settings return false, leaving the previous prepared state intact. Allocation failure propagates with the same strong state guarantee.

Definition at line 119 of file StereoGenerator.h.

◆ prepare() [2/2]

template<typename T >

bool dspark::StereoGenerator< T >::prepare	(	const AudioSpec &	spec,
		Options	options
	)

inline

Prepares explicit options; on success clears all stream history.

Definition at line 125 of file StereoGenerator.h.

◆ processBlock() [1/2]

template<typename T >

bool dspark::StereoGenerator< T >::processBlock ( AudioBufferView< T > buffer )

inlinenoexcept

Processes writable, nonoverlapping stereo channels in place. Returns false without changing input or advancing state for invalid layout, nonfinite input, oversized blocks or clock overflow. A numerical DSP failure returns false and replaces the affected internal chunk and subsequent audio with aligned dry input until reset; earlier chunks remain processed. Inspect getStatus() and handle the failure in the host. No finite-value clamp occurs.

Definition at line 196 of file StereoGenerator.h.

◆ processBlock() [2/2]

template<typename T >

bool dspark::StereoGenerator< T >::processBlock	(	AudioBufferView< T >	buffer,
		std::span< double >	generatedDelta
	)

inlinenoexcept

Also captures the generated mono delta before rounded L/R add-back. An empty span disables capture. Otherwise its length must match the block and its storage must not overlap either audio channel. The delta includes width and low cut, with the same alignment delay as output. A numerical failure writes zero delta for each affected chunk. No subtraction of large original samples is needed to recover a small generated component.

Definition at line 208 of file StereoGenerator.h.

◆ reset()

template<typename T >

void dspark::StereoGenerator< T >::reset ( )

inlinenoexcept

Clears history and restarts modulation at source frame zero.

Definition at line 171 of file StereoGenerator.h.

◆ resetAtFrame()

template<typename T >

void dspark::StereoGenerator< T >::resetAtFrame ( std::uint64_t frame )

inlinenoexcept

Clears history and aligns modulation to an absolute source frame. This is not a seek restore: replay the preceding audio to recover filter history. The 64-frame modulation grid stays anchored to source frame zero. The clock is 64-bit; LFO time/phase is evaluated in double precision.

Definition at line 181 of file StereoGenerator.h.

◆ setState()

template<typename T >

bool dspark::StereoGenerator< T >::setState	(	const std::uint8_t *	data,
		std::size_t	size
	)

inline

Restores a validated preset. Factor/low cut apply at the next prepare. Missing keys retain their settings; malformed/duplicate known keys reject the entire preset unchanged. Unknown keys are ignored for forward compatibility.

Definition at line 270 of file StereoGenerator.h.

◆ setWidth()

template<typename T >

bool dspark::StereoGenerator< T >::setWidth ( float width )

inlinenoexcept

Publishes width in [0,1]. Invalid values return false unchanged.

Definition at line 138 of file StereoGenerator.h.

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

StereoGenerator.h

Classes

Public Types

Public Member Functions

Static Public Member Functions

Detailed Description

Member Enumeration Documentation

◆ Status

Constructor & Destructor Documentation

◆ StereoGenerator() [1/2]

◆ StereoGenerator() [2/2]

Member Function Documentation

◆ getLatency()

◆ getOptions()

◆ getPrepareMemoryBound()

◆ getSourceFrame()

◆ getState()

◆ getStatus()

◆ getWidth()

◆ operator=()

◆ prepare() [1/2]

◆ prepare() [2/2]

◆ processBlock() [1/2]

◆ processBlock() [2/2]

◆ reset()

◆ resetAtFrame()

◆ setState()

◆ setWidth()