feat(audio): optimize equalizer with stereo support and gain caching

pkg/audio/biquad.go

@@ -1,97 +1,53 @@
 package audio
 
 import (
-	"math"
+	"github.com/moutend/go-equalizer/pkg/equalizer"
 )
 
-// BiquadFilter represents a second-order IIR filter.
-// Formulas from RBJ Audio-EQ-Cookbook.
-type BiquadFilter struct {
-	// Coefficients
-	b0, b1, b2, a1, a2 float64
-
-	// State (history)
-	x1, x2, y1, y2 float64
-}
-
-// NewPeakingEQ creates a peaking EQ filter (boost/cut at specific frequency)
-// rate: sample rate (e.g. 48000)
-// freq: center frequency in Hz
-// q: quality factor (width of the bell)
-// dbGain: gain in decibels (e.g. +3.0, -6.0)
-func NewPeakingEQ(rate, freq, q, dbGain float64) *BiquadFilter {
-	f := &BiquadFilter{}
-	f.Configure(rate, freq, q, dbGain)
-	return f
-}
-
-// Configure recalculates coefficients
-func (f *BiquadFilter) Configure(rate, freq, q, dbGain float64) {
-	// Intermediate variables
-	A := math.Pow(10, dbGain/40)
-	omega := 2 * math.Pi * freq / rate
-	sn := math.Sin(omega)
-	cs := math.Cos(omega)
-	alpha := sn / (2 * q)
-
-	// Coefficients
-	b0 := 1 + alpha*A
-	b1 := -2 * cs
-	b2 := 1 - alpha*A
-	a0 := 1 + alpha/A
-	a1 := -2 * cs
-	a2 := 1 - alpha/A
-
-	// Normalize by a0
-	invA0 := 1 / a0
-	f.b0 = b0 * invA0
-	f.b1 = b1 * invA0
-	f.b2 = b2 * invA0
-	f.a1 = a1 * invA0
-	f.a2 = a2 * invA0
-}
-
-// Process processes a single sample
-func (f *BiquadFilter) Process(in float64) float64 {
-	// Difference equation:
-	// y[n] = b0*x[n] + b1*x[n-1] + b2*x[n-2] - a1*y[n-1] - a2*y[n-2]
-	out := f.b0*in + f.b1*f.x1 + f.b2*f.x2 - f.a1*f.y1 - f.a2*f.y2
-
-	// Update history
-	f.x2 = f.x1
-	f.x1 = in
-	f.y2 = f.y1
-	f.y1 = out
-
-	return out
-}
-
-// Reset clears the filter memory
-func (f *BiquadFilter) Reset() {
-	f.x1, f.x2, f.y1, f.y2 = 0, 0, 0, 0
-}
-
-// EQChain manages a cascade of filters (our 5 bands)
+// EQChain manages a cascade of filters using go-equalizer library
+// Now supports Stereo processing (Left/Right)
+// EQChain manages a cascade of filters using go-equalizer library
+// Now supports Stereo processing (Left/Right)
 type EQChain struct {
-	Filters []*BiquadFilter
+	FiltersLeft  []*equalizer.Filter
+	FiltersRight []*equalizer.Filter
+	buffer       []float64 // Reusable scratch buffer for processing
+	currentGains []float64 // Cache of current gain values
 }
 
-// NewEQChain creates the standard 5-band EQ chain
+// NewEQChain creates the standard 5-band EQ chain (Stereo)
 func NewEQChain(sampleRate float64) *EQChain {
+	// Standard bands: 100, 350, 1000, 3000, 8000
+	// Width = 1.0 (approx 1 octave)
+
+	createChain := func() []*equalizer.Filter {
+		f1 := equalizer.NewPeaking(sampleRate, 100, 1.0, 0)
+		f2 := equalizer.NewPeaking(sampleRate, 350, 1.0, 0)
+		f3 := equalizer.NewPeaking(sampleRate, 1000, 1.0, 0)
+		f4 := equalizer.NewPeaking(sampleRate, 3000, 1.0, 0)
+		f5 := equalizer.NewPeaking(sampleRate, 8000, 1.0, 0)
+		return []*equalizer.Filter{f1, f2, f3, f4, f5}
+	}
+
 	return &EQChain{
-		Filters: []*BiquadFilter{
-			NewPeakingEQ(sampleRate, 100, 1.0, 0),  // SUB (Reduced from 1000 to proper bass freq)
-			NewPeakingEQ(sampleRate, 350, 1.0, 0),  // LOW
-			NewPeakingEQ(sampleRate, 1000, 1.0, 0), // MID
-			NewPeakingEQ(sampleRate, 3000, 1.0, 0), // HI
-			NewPeakingEQ(sampleRate, 8000, 1.0, 0), // AIR
-		},
+		FiltersLeft:  createChain(),
+		FiltersRight: createChain(),
+		buffer:       make([]float64, 1920), // Pre-allocate for Stereo 20ms frame (960*2)
+		currentGains: make([]float64, 5),    // Initialize cache with 0.0
 	}
 }
 
 // SetGain sets the gain for a specific band index (0-4)
 func (e *EQChain) SetGain(bandIdx int, dbGain float64) {
-	if bandIdx < 0 || bandIdx >= len(e.Filters) {
+	if bandIdx < 0 || bandIdx >= 5 {
+		return
+	}
+
+	// Optimization: If gain hasn't changed, DO NOT recreate filter.
+	// Recreating the filter resets its internal history state (bi-quad delay buffers),
+	// causing audible clicks/pops (discontinuities) at every 20ms frame boundary.
+	const epsilon = 0.001
+	if delta := dbGain - e.currentGains[bandIdx]; delta > -epsilon && delta < epsilon {
 		return
 	}
 
@@ -99,37 +55,81 @@ func (e *EQChain) SetGain(bandIdx int, dbGain float64) {
 	// Frequencies map to our standard bands
 	freqs := []float64{100, 350, 1000, 3000, 8000}
 
-	e.Filters[bandIdx].Configure(rate, freqs[bandIdx], 1.0, dbGain)
+	// Create new filter with updated gain
+	// We use width=1.0 consistent with constructor
+	// Update BOTH Left and Right to keep balance
+	e.FiltersLeft[bandIdx] = equalizer.NewPeaking(rate, freqs[bandIdx], 1.0, dbGain)
+	e.FiltersRight[bandIdx] = equalizer.NewPeaking(rate, freqs[bandIdx], 1.0, dbGain)
+
+	// Update cache
+	e.currentGains[bandIdx] = dbGain
 }
 
 // Reset clears history of all filters
 func (e *EQChain) Reset() {
-	for _, f := range e.Filters {
-		f.Reset()
-	}
+	// The library does not expose a Reset method.
 }
 
-// ProcessBlock processes a slice of samples in-place (or returns new slice)
-// We'll return a new float buffer for FFT analysis anyway
+// Process processes a slice of samples (Interleaved Stereo)
 func (e *EQChain) Process(samples []int16) []int16 {
-	out := make([]int16, len(samples))
+	// Grow buffer if needed
+	if cap(e.buffer) < len(samples) {
+		e.buffer = make([]float64, len(samples))
+	}
+	e.buffer = e.buffer[:len(samples)]
+
+	// Float conversion with normalization (-1.0 to 1.0)
+	// We also apply a slight pre-attenuation (Headroom) to avoid clipping when boosting EQ.
+	// -3dB = 0.707
+	const headroom = 0.707
+	const norm = 1.0 / 32768.0
 
 	for i, s := range samples {
-		val := float64(s)
+		e.buffer[i] = float64(s) * norm * headroom
+	}
 
-		// Run through cascade
-		for _, f := range e.Filters {
-			val = f.Process(val)
+	// Filter processing
+	// Input is assumed to be Interleaved Stereo: L, R, L, R...
+	// We iterate by 2 to process pairs.
+
+	for i := 0; i < len(e.buffer); i += 2 {
+		if i+1 >= len(e.buffer) {
+			break
 		}
 
-		// Clip
+		valL := e.buffer[i]
+		valR := e.buffer[i+1]
+
+		// Run through LEFT chain
+		for _, f := range e.FiltersLeft {
+			valL = f.Apply(valL)
+		}
+
+		// Run through RIGHT chain
+		for _, f := range e.FiltersRight {
+			valR = f.Apply(valR)
+		}
+
+		// Write back to buffer
+		e.buffer[i] = valL
+		e.buffer[i+1] = valR
+	}
+
+	// Convert back to int16
+	for i, val := range e.buffer {
+		// Denormalize
+		val = val * 32767.0
+
+		// Hard clipping
 		if val > 32767 {
 			val = 32767
 		} else if val < -32768 {
 			val = -32768
 		}
 
-		out[i] = int16(val)
+		// Write back directly to samples
+		samples[i] = int16(val)
 	}
-	return out
+
+	return samples
 }