spectral_frame_engine.hpp

Go to the documentation of this file.

#pragma once

 
#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>
 
namespace pulp::signal {

struct SpectralFrameEngineConfig {
    int fft_size = 2048;       // Power of 2, 256–16384
    int analysis_hop = 512;    // Samples between analysis frames (<= fft_size/2)
    int channels = 1;          // Channel-group size (>= 1)
    int max_block = 4096;      // Largest process() block the caller will use
    int max_synthesis_hop = 0; // 0 = 2 * analysis_hop; upper bound for synthesize_frame()
    WindowFunction::Type window = WindowFunction::Type::hann;
    bool full_overlap_stream_start = true;
    bool defer_synthesis = true;
    bool guarded_split = false;
};
 
enum class SpectralSplitResult : std::uint8_t {
    Ok,
    NotPrepared,
    InvalidBlock,
    InvalidFrame,
    ChronologyExhausted,
    CapacityExceeded,
    NonfiniteSynthesis,
    OutputUnderrun,
    StreamStopped
};
 
inline constexpr int kSpectralFrameEngineMinimumFftSize = 256;
inline constexpr int kSpectralFrameEngineMaximumFftSize = 16384;
inline constexpr std::uint64_t kSpectralFrameEngineMaximumRingSize =
    std::uint64_t{1} << 30u;
 
struct SpectralFrameEngineGeometry {
    int max_synthesis_hop = 0;
    int num_bins = 0;
    int ring_size = 0;
    std::uint64_t input_ring_elements = 0;
    std::uint64_t output_ring_elements = 0;
    std::uint64_t frame_elements = 0;
    std::uint64_t retained_bytes = 0;
};
 
inline bool is_valid_spectral_frame_geometry(int fft_size, int analysis_hop) noexcept {
    return fft_size >= kSpectralFrameEngineMinimumFftSize
        && fft_size <= kSpectralFrameEngineMaximumFftSize
        && (fft_size & (fft_size - 1)) == 0
        && analysis_hop > 0
        && analysis_hop <= fft_size / 2;
}

inline constexpr std::int64_t
spectral_frame_engine_first_frame_start(int fft_size, int analysis_hop,
                                        bool full_overlap_stream_start) noexcept {
    if (!full_overlap_stream_start || fft_size <= 0 || analysis_hop <= 0)
        return 0;
    return -static_cast<std::int64_t>((fft_size - 1) / analysis_hop) * analysis_hop;
}

template <typename SampleType>
inline double spectral_ola_window_energy(const SampleType* window, int fft_size, int hop,
                                         std::int64_t first_frame_start,
                                         std::int64_t position) noexcept {
    if (window == nullptr || fft_size <= 0 || hop <= 0 || position < first_frame_start)
        return 0.0;
    const std::int64_t lowest =
        std::max(first_frame_start, position - static_cast<std::int64_t>(fft_size) + 1);
    const std::int64_t first_k = (lowest - first_frame_start + hop - 1) / hop;
    double sum = 0.0;
    for (std::int64_t start = first_frame_start + first_k * hop; start <= position; start += hop) {
        const auto w = static_cast<double>(window[static_cast<std::size_t>(position - start)]);
        sum += w * w;
    }
    return sum;
}

template <typename SampleType>
inline std::optional<SpectralFrameEngineGeometry> checked_spectral_frame_engine_geometry(
    const SpectralFrameEngineConfig& config,
    std::uint64_t target_max_bytes = kTargetAddressMaximumBytes) noexcept {
    static_assert(std::is_floating_point_v<SampleType>);
    if (!is_valid_spectral_frame_geometry(config.fft_size, config.analysis_hop)
        || config.channels < 1 || config.max_block <= 0)
        return std::nullopt;
    if (config.guarded_split && config.defer_synthesis)
        return std::nullopt;
 
    const int max_synthesis_hop = config.max_synthesis_hop > 0
        ? config.max_synthesis_hop
        : 2 * config.analysis_hop;
    if (max_synthesis_hop <= 0) return std::nullopt;
 
    const auto fft_size = static_cast<std::uint64_t>(config.fft_size);
    const auto channels = static_cast<std::uint64_t>(config.channels);
    const auto max_block = static_cast<std::uint64_t>(config.max_block);
    const auto synthesis_hop = static_cast<std::uint64_t>(max_synthesis_hop);
    const auto worst_frames = max_block / static_cast<std::uint64_t>(config.analysis_hop) + 2u;
 
    std::uint64_t backlog = 0;
    std::uint64_t ring_span = 0;
    if (!checked_capacity_product(worst_frames, synthesis_hop,
                                  kSpectralFrameEngineMaximumRingSize, backlog)
        || !checked_capacity_sum(fft_size, max_block,
                                 kSpectralFrameEngineMaximumRingSize, ring_span)
        || !checked_capacity_sum(ring_span, backlog,
                                 kSpectralFrameEngineMaximumRingSize, ring_span))
        return std::nullopt;
 
    std::uint64_t ring_size = 1;
    while (ring_size < ring_span) ring_size <<= 1u;
 
    const auto num_bins = fft_size / 2u + 1u;
    SpectralFrameEngineGeometry geometry;
    if (!checked_capacity_product(channels, fft_size,
                                  std::numeric_limits<std::uint64_t>::max(),
                                  geometry.input_ring_elements)
        || !checked_capacity_product(channels, ring_size,
                                     std::numeric_limits<std::uint64_t>::max(),
                                     geometry.output_ring_elements)
        || !checked_capacity_product(channels, num_bins,
                                     std::numeric_limits<std::uint64_t>::max(),
                                     geometry.frame_elements))
        return std::nullopt;
 
    CheckedRetainedByteCharge charge(target_max_bytes);
    std::uint64_t fft_retained_bytes = 0;
    if (!charge.add<SampleType>(geometry.input_ring_elements)
        || !charge.add<SampleType>(geometry.output_ring_elements)
        || !charge.add<SampleType>(ring_size) // norm ring
        || !charge.add<SampleType>(fft_size) // window
        || !charge.add<SampleType>(fft_size) // time scratch
        || !charge.add<std::complex<SampleType>>(geometry.frame_elements)
        || !charge.add<std::complex<SampleType>*>(channels) // frame pointers
        || !checked_fft_retained_bytes<SampleType>(fft_size, target_max_bytes,
                                                   fft_retained_bytes)
        || !charge.add_retained_bytes(fft_retained_bytes))
        return std::nullopt;
    if (config.guarded_split && (!charge.add<SampleType>(geometry.input_ring_elements) ||
                                 !charge.add<SampleType>(fft_size)))
        return std::nullopt;
 
    geometry.max_synthesis_hop = max_synthesis_hop;
    geometry.num_bins = static_cast<int>(num_bins);
    geometry.ring_size = static_cast<int>(ring_size);
    geometry.retained_bytes = charge.total();
    return geometry;
}

template <typename SampleType = float>
class SpectralFrameEngineT {
public:
    SpectralFrameEngineT() = default;

    void prepare(const SpectralFrameEngineConfig& config) {
        const auto geometry = checked_spectral_frame_engine_geometry<SampleType>(config);
        assert(geometry.has_value());
        if (!geometry) return;
 
        config_ = config;
        config_.max_synthesis_hop = geometry->max_synthesis_hop;
        num_bins_ = geometry->num_bins;
        first_frame_start_ = spectral_frame_engine_first_frame_start(
            config_.fft_size, config_.analysis_hop, config_.full_overlap_stream_start);
 
        fft_ = FftT<SampleType>(config_.fft_size);
        window_ = WindowFunction::generate<SampleType>(config_.fft_size,
                                                       config_.window);
 
        // Steady-state OLA window-energy at a fully-overlapped sample for
        // the analysis hop. Without full-overlap stream start it floors the
        // per-sample normalization so partial-overlap samples at the stream
        // start taper to zero instead of being amplified by division by a
        // near-zero coverage. The floor sits far below any real body coverage
        // (down to a 4x sparser synthesis hop), so body samples normalize
        // unchanged.
        double steady = 0.0;
        const int n = config_.fft_size, h = config_.analysis_hop;
        const int center = n; // well inside the plateau
        for (int j = -n / h - 1; j <= n / h + 1; ++j) {
            const int idx = center - j * h - (n / 2);
            if (idx >= 0 && idx < n) {
                const SampleType w = window_[static_cast<size_t>(idx)];
                steady += static_cast<double>(w) * w;
            }
        }
        min_norm_ = std::max(static_cast<SampleType>(steady) * SampleType{0.25f},
                             SampleType{1e-9f});
 
        ring_size_ = geometry->ring_size;
        ring_mask_ = ring_size_ - 1;
 
        input_ring_.assign(static_cast<size_t>(geometry->input_ring_elements),
                           SampleType{0.0f});
        output_ring_.assign(static_cast<size_t>(geometry->output_ring_elements),
                            SampleType{0.0f});
        norm_ring_.assign(ring_size_, SampleType{0.0f});
 
        frames_.assign(static_cast<size_t>(geometry->frame_elements),
                       std::complex<SampleType>(SampleType{0.0f}, SampleType{0.0f}));
        frame_ptrs_.resize(config_.channels);
        for (int ch = 0; ch < config_.channels; ++ch)
            frame_ptrs_[ch] = frames_.data() + static_cast<size_t>(ch) * num_bins_;
 
        time_buf_.assign(config_.fft_size, SampleType{0.0f});
        guarded_numerator_.assign(
            config_.guarded_split ? static_cast<size_t>(geometry->input_ring_elements) : 0,
            SampleType{0});
        guarded_norm_.assign(config_.guarded_split ? config_.fft_size : 0, SampleType{0});
 
        reset();
    }

    int latency_samples() const { return config_.fft_size + config_.analysis_hop; }

    std::int64_t first_frame_start() const {
        return first_frame_start_;
    }
 
    int fft_size() const { return config_.fft_size; }
    int analysis_hop() const { return config_.analysis_hop; }
    int num_bins() const { return num_bins_; }
    int channels() const { return config_.channels; }

    std::uint64_t retained_storage_bytes() const noexcept {
        CheckedRetainedByteCharge charge(kTargetAddressMaximumBytes);
        std::uint64_t fft_bytes = 0;
        if (!checked_fft_retained_bytes<SampleType>(config_.fft_size, kTargetAddressMaximumBytes,
                                                    fft_bytes) ||
            !charge.add_retained_bytes(fft_bytes) || !charge.add<SampleType>(window_.capacity()) ||
            !charge.add<SampleType>(input_ring_.capacity()) ||
            !charge.add<SampleType>(output_ring_.capacity()) ||
            !charge.add<SampleType>(norm_ring_.capacity()) ||
            !charge.add<SampleType>(time_buf_.capacity()) ||
            !charge.add<SampleType>(guarded_numerator_.capacity()) ||
            !charge.add<SampleType>(guarded_norm_.capacity()) ||
            !charge.add<std::complex<SampleType>>(frames_.capacity()) ||
            !charge.add<std::complex<SampleType>*>(frame_ptrs_.capacity()))
            return std::numeric_limits<std::uint64_t>::max();
        return charge.total();
    }

    template <typename Fn>
    SpectralSplitResult analyze_guarded(const SampleType* const* in, int count, Fn&& fn) {
        if (!config_.guarded_split || num_bins_ == 0)
            return SpectralSplitResult::NotPrepared;
        if (count < 0 || count > config_.max_block || (count != 0 && !in))
            return SpectralSplitResult::InvalidBlock;
        for (int ch = 0; count != 0 && ch < config_.channels; ++ch)
            if (!in[ch])
                return SpectralSplitResult::InvalidBlock;
        constexpr auto limit = std::numeric_limits<std::int64_t>::max();
        if (samples_fed_ > limit - count || samples_fed_ + count > limit - config_.analysis_hop)
            return SpectralSplitResult::ChronologyExhausted;
        analyze(in, count, std::forward<Fn>(fn));
        return SpectralSplitResult::Ok;
    }

    SpectralSplitResult
    synthesize_frame_guarded(const std::complex<SampleType>* const* frames) noexcept {
        if (!config_.guarded_split || num_bins_ == 0)
            return SpectralSplitResult::NotPrepared;
        if (guarded_stopped_)
            return SpectralSplitResult::StreamStopped;
        const int n = config_.fft_size;
        constexpr auto limit = std::numeric_limits<std::int64_t>::max();
        if (synth_pos_ > limit - n)
            return SpectralSplitResult::ChronologyExhausted;
        if (synth_pos_ + n - read_pos_ > ring_size_)
            return SpectralSplitResult::CapacityExceeded;
        if (!frames)
            return SpectralSplitResult::InvalidFrame;
        for (int ch = 0; ch < config_.channels; ++ch) {
            if (!frames[ch])
                return SpectralSplitResult::InvalidFrame;
            for (int bin = 0; bin < num_bins_; ++bin)
                if (!std::isfinite(frames[ch][bin].real()) ||
                    !std::isfinite(frames[ch][bin].imag()))
                    return SpectralSplitResult::InvalidFrame;
            if (frames[ch][0].imag() != SampleType{0} ||
                frames[ch][num_bins_ - 1].imag() != SampleType{0})
                return SpectralSplitResult::InvalidFrame;
        }
        const int skip = synth_pos_ < 0 ? static_cast<int>(-synth_pos_) : 0;
        for (int ch = 0; ch < config_.channels; ++ch) {
            fft_.inverse_real_half(frames[ch], time_buf_.data());
            for (int i = 0; i < n; ++i)
                if (!std::isfinite(time_buf_[i]))
                    return SpectralSplitResult::NonfiniteSynthesis;
            const auto* ring = output_ring_.data() + static_cast<size_t>(ch) * ring_size_;
            auto* staged = guarded_numerator_.data() + static_cast<size_t>(ch) * n;
            for (int i = skip; i < n; ++i) {
                const auto idx = static_cast<size_t>((synth_pos_ + i) & ring_mask_);
                const SampleType contribution = time_buf_[i] * window_[i];
                staged[i] = ring[idx] + contribution;
                if (!std::isfinite(contribution) || !std::isfinite(staged[i]))
                    return SpectralSplitResult::NonfiniteSynthesis;
            }
        }
        for (int i = skip; i < n; ++i) {
            const auto idx = static_cast<size_t>((synth_pos_ + i) & ring_mask_);
            guarded_norm_[i] = norm_ring_[idx] + window_[i] * window_[i];
            if (!std::isfinite(guarded_norm_[i]))
                return SpectralSplitResult::NonfiniteSynthesis;
        }
        for (int ch = 0; ch < config_.channels; ++ch) {
            auto* ring = output_ring_.data() + static_cast<size_t>(ch) * ring_size_;
            const auto* staged = guarded_numerator_.data() + static_cast<size_t>(ch) * n;
            for (int i = skip; i < n; ++i)
                ring[static_cast<size_t>((synth_pos_ + i) & ring_mask_)] = staged[i];
        }
        for (int i = skip; i < n; ++i)
            norm_ring_[static_cast<size_t>((synth_pos_ + i) & ring_mask_)] = guarded_norm_[i];
        available_ = std::max(available_, synth_pos_);
        synth_pos_ += config_.analysis_hop;
        return SpectralSplitResult::Ok;
    }

    void stop_synthesis_guarded() noexcept {
        if (!config_.guarded_split)
            return;
        available_ = std::max(available_, synth_pos_);
        guarded_stopped_ = true;
    }

    SpectralSplitResult read_output_guarded(SampleType* const* out, int count,
                                            int& consumed) noexcept {
        consumed = 0;
        if (!config_.guarded_split || num_bins_ == 0)
            return SpectralSplitResult::NotPrepared;
        if (count < 0 || count > config_.max_block || (count != 0 && !out))
            return SpectralSplitResult::InvalidBlock;
        for (int ch = 0; count != 0 && ch < config_.channels; ++ch)
            if (!out[ch])
                return SpectralSplitResult::InvalidBlock;
        for (; consumed < count; ++consumed) {
            if (read_pos_ >= available_)
                return SpectralSplitResult::OutputUnderrun;
            const auto idx = static_cast<size_t>(read_pos_ & ring_mask_);
            const bool startup = !config_.full_overlap_stream_start && read_pos_ < config_.fft_size;
            const SampleType norm =
                startup ? std::max(norm_ring_[idx], min_norm_) : norm_ring_[idx];
            if (!std::isfinite(norm))
                return SpectralSplitResult::NonfiniteSynthesis;
            for (int ch = 0; ch < config_.channels; ++ch) {
                const auto* ring = output_ring_.data() + static_cast<size_t>(ch) * ring_size_;
                auto& value = guarded_numerator_[static_cast<size_t>(ch) * config_.fft_size];
                value = norm > SampleType{1e-9f} ? ring[idx] / norm : SampleType{0};
                if (!std::isfinite(value))
                    return SpectralSplitResult::NonfiniteSynthesis;
            }
            for (int ch = 0; ch < config_.channels; ++ch) {
                out[ch][consumed] = guarded_numerator_[static_cast<size_t>(ch) * config_.fft_size];
                output_ring_[static_cast<size_t>(ch) * ring_size_ + idx] = SampleType{0};
            }
            norm_ring_[idx] = SampleType{0};
            ++read_pos_;
        }
        return SpectralSplitResult::Ok;
    }

    template <typename Fn>
    void process(const SampleType* const* in,
                 SampleType* const* out,
                 int num_samples,
                 Fn&& on_frames) {
        assert(num_samples <= config_.max_block);
        // Deferred resynthesis. A frame that completes at input sample F is
        // first read at output sample F + analysis_hop (the latency is
        // fft_size + analysis_hop), so its inverse transforms and overlap-add
        // can wait up to a hop. Each channel's runs in the first callback at
        // or past its own due point inside that hop, spreading what used to
        // land whole in the callback that completed the frame; whatever is
        // still pending runs before the next frame (analyze() flushes).
        // Same arithmetic in the same order: output is bit-identical.
        run_due_synthesis_(samples_fed_ + num_samples);
        analyze(in, num_samples, [&](std::complex<SampleType>* const* frames,
                                     int bins) {
            on_frames(frames, bins);
            if (config_.defer_synthesis)
                begin_deferred_synthesis_(frames);
            else
                synthesize_frame(frames, config_.analysis_hop);
        });
        run_due_synthesis_(samples_fed_);
        // Fixed-latency read: the first latency_samples() outputs are zeros;
        // afterwards every output pops exactly one final ring sample, so the
        // input→output delay is constant regardless of block size or phase.
        const auto lat = static_cast<std::int64_t>(latency_samples());
        for (int i = 0; i < num_samples; ++i) {
            if (out_count_ < lat) {
                for (int ch = 0; ch < config_.channels; ++ch)
                    out[ch][i] = SampleType{0.0f};
            } else {
                pop_one(out, i);
            }
            ++out_count_;
        }
    }

    int samples_until_next_frame() const {
        return static_cast<int>(next_frame_at_ - samples_fed_);
    }

    template <typename Fn>
    void analyze(const SampleType* const* in, int num_samples, Fn&& on_frames) {
        const int n = config_.fft_size;
        int done = 0;
        while (done < num_samples) {
            const auto until_frame = static_cast<int>(
                std::min<std::int64_t>(next_frame_at_ - samples_fed_,
                                       static_cast<std::int64_t>(num_samples - done)));
            const int run = std::max(until_frame, 1);
            for (int ch = 0; ch < config_.channels; ++ch) {
                SampleType* ring = input_ring_.data() + static_cast<size_t>(ch) * n;
                for (int i = 0; i < run; ++i)
                    ring[(input_pos_ + i) % n] = in[ch][done + i];
            }
            input_pos_ = (input_pos_ + run) % n;
            samples_fed_ += run;
            done += run;
 
            if (samples_fed_ == next_frame_at_) {
                flush_deferred_synthesis_();
                next_frame_at_ += config_.analysis_hop;
                emit_frame(on_frames);
            }
        }
    }

    void synthesize_frame(std::complex<SampleType>* const* frames, int synthesis_hop) {
        assert(synthesis_hop > 0 && synthesis_hop <= config_.max_synthesis_hop);
        for (int ch = 0; ch < config_.channels; ++ch)
            synthesize_channel_(frames, ch);
        finish_synthesis_(synthesis_hop);
    }

    int available_output() const {
        return static_cast<int>(available_ - read_pos_);
    }

    void read_output(SampleType* const* out, int num_samples) {
        for (int i = 0; i < num_samples; ++i) {
            if (read_pos_ < available_) {
                pop_one(out, i);
            } else {
                for (int ch = 0; ch < config_.channels; ++ch)
                    out[ch][i] = SampleType{0.0f};
            }
        }
    }
 
    void reset() {
        std::fill(input_ring_.begin(), input_ring_.end(), SampleType{0.0f});
        std::fill(output_ring_.begin(), output_ring_.end(), SampleType{0.0f});
        std::fill(norm_ring_.begin(), norm_ring_.end(), SampleType{0.0f});
        std::fill(frames_.begin(), frames_.end(),
                  std::complex<SampleType>(SampleType{0.0f}, SampleType{0.0f}));
        input_pos_ = 0;
        samples_fed_ = 0;
        next_frame_at_ = config_.fft_size + first_frame_start_;
        synth_pos_ = first_frame_start_;
        available_ = 0;
        read_pos_ = 0;
        out_count_ = 0;
        deferred_frames_ = nullptr;
        deferred_next_channel_ = 0;
        guarded_stopped_ = false;
    }
 
private:
  // One channel of synthesize_frame(): inverse transform and overlap-add.
  // Pre-stream samples of a frame that starts before position 0 are never
  // read, so they are never written: the ring slots they would alias stay
  // clean for the real stream.
  void synthesize_channel_(std::complex<SampleType>* const* frames, int ch) {
      const int n = config_.fft_size;
      const int skip =
          synth_pos_ < 0 ? static_cast<int>(std::min<std::int64_t>(-synth_pos_, n)) : 0;
      // The frame holds DC..Nyquist of a real signal; the real inverse reads
      // exactly that and ignores DC/Nyquist imaginary parts, which a full
      // complex inverse would only have sent to the discarded imaginary output.
      fft_.inverse_real_half(frames[ch], time_buf_.data());
      SampleType* ring = output_ring_.data() + static_cast<size_t>(ch) * ring_size_;
      for (int i = skip; i < n; ++i) {
          const auto idx = static_cast<size_t>((synth_pos_ + i) & ring_mask_);
          ring[idx] += time_buf_[static_cast<size_t>(i)] * window_[static_cast<size_t>(i)];
      }
  }
 
  // The rest of synthesize_frame(): the shared normalization ring, then
  // advance the synthesis position.
  void finish_synthesis_(int synthesis_hop) {
      const int n = config_.fft_size;
      const int skip =
          synth_pos_ < 0 ? static_cast<int>(std::min<std::int64_t>(-synth_pos_, n)) : 0;
      for (int i = skip; i < n; ++i) {
          const auto idx = static_cast<size_t>((synth_pos_ + i) & ring_mask_);
          norm_ring_[idx] += window_[static_cast<size_t>(i)] * window_[static_cast<size_t>(i)];
      }
      synth_pos_ += synthesis_hop;
      // Samples before the start of the frame just written are final.
      available_ = std::max(available_, synth_pos_ - synthesis_hop);
  }
 
  void begin_deferred_synthesis_(std::complex<SampleType>* const* frames) {
      deferred_frames_ = frames;
      deferred_next_channel_ = 0;
      deferred_frame_at_ = samples_fed_;
  }
 
  // Run every deferred channel whose due point is before `fed`.
  void run_due_synthesis_(std::int64_t fed) {
      const int channels = config_.channels;
      while (deferred_frames_ != nullptr) {
          const std::int64_t due =
              deferred_frame_at_ + static_cast<std::int64_t>(config_.analysis_hop) *
                                       (deferred_next_channel_ + 1) / (channels + 1);
          if (due > fed)
              return;
          step_deferred_synthesis_();
      }
  }
 
  void step_deferred_synthesis_() {
      synthesize_channel_(deferred_frames_, deferred_next_channel_);
      if (++deferred_next_channel_ == config_.channels) {
          finish_synthesis_(config_.analysis_hop);
          deferred_frames_ = nullptr;
      }
  }
 
  void flush_deferred_synthesis_() {
      while (deferred_frames_ != nullptr)
          step_deferred_synthesis_();
  }
 
    // Pop one final sample (all channels) into out[..][i], normalizing by
    // the accumulated squared synthesis window and clearing the slot.
    void pop_one(SampleType* const* out, int i) {
        // A frame whose synthesis is deferred is final for its first hop
        // before available_ (conservative by a hop) says so.
        assert(read_pos_ < available_ + config_.analysis_hop);
        const auto idx = static_cast<size_t>(read_pos_ & ring_mask_);
        // Floor only the stream-start partial-overlap region, which exists
        // only without full-overlap stream start. Elsewhere per-sample
        // normalization must remain exact for non-COLA windows/hops whose
        // valid body coverage can dip below the startup floor; a genuinely
        // zero coverage is still guarded below.
        const bool startup_edge =
            !config_.full_overlap_stream_start && read_pos_ < config_.fft_size;
        const SampleType norm = startup_edge
            ? std::max(norm_ring_[idx], min_norm_)
            : norm_ring_[idx];
        for (int ch = 0; ch < config_.channels; ++ch) {
            SampleType* ring =
                output_ring_.data() + static_cast<size_t>(ch) * ring_size_;
            out[ch][i] =
                norm > SampleType{1e-9f} ? ring[idx] / norm : SampleType{0.0f};
            ring[idx] = SampleType{0.0f};
        }
        norm_ring_[idx] = SampleType{0.0f};
        ++read_pos_;
    }
 
    // Window + transform the last fft_size samples of every channel's
    // input ring and hand the frame group to the callback.
    template <typename Fn>
    void emit_frame(Fn&& on_frames) {
        const int n = config_.fft_size;
        for (int ch = 0; ch < config_.channels; ++ch) {
            const SampleType* ring =
                input_ring_.data() + static_cast<size_t>(ch) * n;
            for (int i = 0; i < n; ++i)
                time_buf_[static_cast<size_t>(i)] =
                    ring[(input_pos_ + i) % n] * window_[static_cast<size_t>(i)];
            fft_.forward_real_half(time_buf_.data(),
                                   frames_.data() + static_cast<size_t>(ch) * num_bins_);
        }
        on_frames(frame_ptrs_.data(), num_bins_);
    }
 
    SpectralFrameEngineConfig config_;
    FftT<SampleType> fft_{2048};
    std::vector<SampleType> window_;
    int num_bins_ = 0;
    int ring_size_ = 0;
    int ring_mask_ = 0;
    SampleType min_norm_ = SampleType{1e-9f}; // OLA coverage floor for edge taper.
    std::int64_t first_frame_start_ = 0;      // <= 0; see first_frame_start().
 
    std::vector<SampleType> input_ring_;  // channels * fft_size
    std::vector<SampleType> output_ring_; // channels * ring_size
    std::vector<SampleType> norm_ring_;   // ring_size (shared across channels)
 
    std::vector<std::complex<SampleType>> frames_;      // channels * num_bins
    std::vector<std::complex<SampleType>*> frame_ptrs_; // channels
    std::vector<SampleType> time_buf_;                  // fft_size
    std::vector<SampleType> guarded_numerator_;         // channels * fft_size
    std::vector<SampleType> guarded_norm_;              // fft_size
    bool guarded_stopped_ = false;
 
    int input_pos_ = 0;
    std::int64_t samples_fed_ = 0;
    std::int64_t next_frame_at_ = 0;
    std::int64_t synth_pos_ = 0;   // next frame start (absolute samples)
    std::int64_t available_ = 0;   // final samples high-water mark
    std::int64_t read_pos_ = 0;    // absolute read position
    std::int64_t out_count_ = 0;   // samples emitted by process()
    // process()'s deferred resynthesis: the frame group awaiting it (the
    // engine's own frame buffers, untouched until the next frame), the next
    // channel to synthesize, and the input sample the frame completed at.
    std::complex<SampleType>* const* deferred_frames_ = nullptr;
    int deferred_next_channel_ = 0;
    std::int64_t deferred_frame_at_ = 0;
};
 
using SpectralFrameEngine = SpectralFrameEngineT<float>;
using SpectralFrameEngine64 = SpectralFrameEngineT<double>;
 
} // namespace pulp::signal