audio-dsp

Files (1)

• SKILL.md

SKILL.md (first lines)

Requires: audio-engineering-principles

## Workflow

### 1. Design: Thread Model + Constraints

Before writing any code, classify each component:

| Component | Thread | Allocation allowed? |
|-----------|--------|---------------------|
| DSP (filter, STFT) | Audio | No — preallocate in init |
| Parameter smoothing | Audio | No |
| SPSC push (events out) | Audio | No — fixed buffer |
| Analysis, logging | Worker | Yes |
| Result publishing | Worker | Yes |

**RT constraints checklist (audio thread must pass ALL):**
- [ ] No `new`/`malloc`/`std::vector::push_back`
- [ ] No mutex, no `std::lock_guard`
- [ ] No file IO, no `printf`/`std::cout`
- [ ] No syscalls, no exceptions
- [ ] No dynamic container resize
- [ ] All state pre-allocated in `prepare()`/`prepareToPlay()`

### 2. Implement DSP

**Biquad filter (Direct Form II Transposed) — RT-safe:**

```cpp
struct Biquad {
    float b0, b1, b2, a1, a2;
    float z1 = 0, z2 = 0;

    float process(float in) {
        float out = b0 * in + z1;
        z1 = b1 * in - a1 * out + z2;
        z2 = b2 * in - a2 * out;
        return out;
    }

    void setLowpass(float freq, float q, float sr) {
        float w0 = 2.0f * M_PI * freq / sr;
        float alpha = sinf(w0) / (2.0f * q);
        float cosw0 = cosf(w0);
        float a0 = 1.0f + alpha;
        b0 = ((1.0f - cosw0) / 2.0f) / a0;
        b1 = (1.0f - cosw0) / a0;
        b2 = b0;
        a1 = (-2.0f * cosw0) / a0;
        a2 = (1.0f - alpha) / a0;
    }
};
```

⚠️ **Pitfall:** Call `setLowpass()` only on the non-RT thread or in `prepare()`. Calling it mid-block without smoothing causes audible zipper noise.

**STFT pipeline (offline/hybrid — allocation OK):**

```cpp
void analyzeSpectrum(const float* input, size_t numSamples, float sampleRate) {
    constexpr size_t fftSize = 2048;  // default; Hann window
    constexpr size_t hopSize = 512;
    std::vector<float> window(fftSize);
    hannWindow(window.data(), fftSize);

    for (size_t pos = 0; pos + fftSize <= numSamples; pos += hopSize) {
        std::vector<float> windowed(input + pos, input + pos + fftSize);
        applyWindow(windowed.data(), window.data(), fftSize);
        auto magnitudes = computeFFT(windowed.data(), fftSize);
        float centroid = spectralCentroid(magnitudes.data(), fftSize, sampleRate);
        // store or process centroid per frame
    }
}
```

**STFT defaults (use unless specified):**
- Window: Hann
- FFT size: 2048
- Hop: 512 (use 256 for higher time resolution)
- Output: magnitude spectrum

**Parameter smoothing (required for any modulated RT param):**

```cpp
struct SmoothedParam {
    float current, target, coeff;
    void prepare(float sr, float smoothMs) {
        coeff = expf(-1.0f / (sr * smoothMs * 0.001f));
    }
    float next() {
        current = current * coeff + target * (1.0f - coeff);
        return current;
    }
};
```

### 3. Wire Concurrency

Use SPSC queue to pass data from audio thread → worker thread. Never share mutable state without atomics.

```cpp
template<typename T, size_t Size>
struct SPSCQueue {
    std::array<T, Size> buffer;
    std::atomic<size_t> head{0}, tail{0};

    bool push(const T& item) {
        size_t h = head.load(std::memory_order_relaxed);
        size_t next = (h + 1) % Size;
        if (next == tail.load(std::memory_order_acquire)) return false; // full
        buffer[h] = item;
        head.store(next, std::memory_order_release);
        return true;
    }

    bool pop(T& item) {
        size_t t = tail.load(std::memory_order_relaxed);
        if (t == head.load(std::memory_order_acquire)) return false; // empty
        item = buffer[t];

From viniciuscs84/sdd-toolkit, MIT.

More from viniciuscs84/sdd-toolkit