spectral_frame_engine.hpp File Reference

Streaming STFT analysis + weighted overlap-add (WOLA) synthesis for DSP-grade spectral processing — distinct from the visualization-only Stft, which has no synthesis path. More...

#include <pulp/signal/checked_allocation.hpp>
#include <pulp/signal/fft.hpp>
#include <pulp/signal/windowing.hpp>
#include <algorithm>
#include <cassert>
#include <complex>
#include <cmath>
#include <cstdint>
#include <limits>
#include <optional>
#include <type_traits>
#include <utility>
#include <vector>

Go to the source code of this file.

Classes
struct	pulp::signal::SpectralFrameEngineConfig
	Configuration for a SpectralFrameEngine. More...
struct	pulp::signal::SpectralFrameEngineGeometry
class	pulp::signal::SpectralFrameEngineT< SampleType >
	Streaming multichannel STFT/WOLA engine. More...

Namespaces
namespace	pulp
namespace	pulp::signal

Typedefs
using	pulp::signal::SpectralFrameEngine = SpectralFrameEngineT<float>
using	pulp::signal::SpectralFrameEngine64 = SpectralFrameEngineT<double>

Enumerations
enum class	pulp::signal::SpectralSplitResult : std::uint8_t {   pulp::signal::Ok , pulp::signal::NotPrepared , pulp::signal::InvalidBlock , pulp::signal::InvalidFrame ,   pulp::signal::ChronologyExhausted , pulp::signal::CapacityExceeded , pulp::signal::NonfiniteSynthesis , pulp::signal::OutputUnderrun ,   pulp::signal::StreamStopped }

Functions
bool	pulp::signal::is_valid_spectral_frame_geometry (int fft_size, int analysis_hop) noexcept
constexpr std::int64_t	pulp::signal::spectral_frame_engine_first_frame_start (int fft_size, int analysis_hop, bool full_overlap_stream_start) noexcept
	Stream position of the first analysis frame after prepare()/reset().
template<typename SampleType>
double	pulp::signal::spectral_ola_window_energy (const SampleType *window, int fft_size, int hop, std::int64_t first_frame_start, std::int64_t position) noexcept
	Accumulated squared synthesis window at stream position for equal-hop frames of length fft_size starting at first_frame_start + k * hop (k >= 0) — the per-sample divisor the WOLA path normalizes by.
template<typename SampleType>
std::optional< SpectralFrameEngineGeometry >	pulp::signal::checked_spectral_frame_engine_geometry (const SpectralFrameEngineConfig &config, std::uint64_t target_max_bytes=kTargetAddressMaximumBytes) noexcept
	Derive every integer and typed backing-store capacity used by prepare().

Variables
constexpr int	pulp::signal::kSpectralFrameEngineMinimumFftSize = 256
constexpr int	pulp::signal::kSpectralFrameEngineMaximumFftSize = 16384
constexpr std::uint64_t	pulp::signal::kSpectralFrameEngineMaximumRingSize

Detailed Description

Streaming STFT analysis + weighted overlap-add (WOLA) synthesis for DSP-grade spectral processing — distinct from the visualization-only Stft, which has no synthesis path.

Channels are processed as a coherent group: every analysis callback delivers all channels' spectra for the same time index, so spectral modifications (pitch/time, formant, freeze) can make one decision per frame and apply it to the whole group.

Two usage levels:

• process() — equal-hop analysis→modify→resynthesis streaming with a per-frame callback. Neutral (identity callback) reconstruction is exact up to float rounding for any COLA-satisfying window/hop.
• analyze() / synthesize_frame() / read_output() — split API for processors that need a synthesis hop different from the analysis hop (time-scale modification). Output availability is tracked so callers can pull exactly what is final.

Reconstruction is normalized per-sample by the accumulated squared synthesis window, which keeps amplitude exact for any hop (including variable hops and stream edges) without hardcoded COLA constants.

Stream start: by default the frame grid begins before the first input sample (at first_frame_start(), the last hop multiple above -fft_size), with silence as the implicit history. Every real sample, including sample 0 after prepare() or reset(), is therefore covered by the full set of overlapping windows and reconstructs exactly; the pre-stream part of those frames is discarded, and the reported latency is unchanged. Callers need not prime the engine with silence; doing so is harmless but runs the FFTs of the primed frames.

Basis: Allen & Rabiner 1977 (unified STFT analysis/synthesis); Crochiere 1980 (weighted overlap-add). No allocation or locks after prepare().