audio_filters: clarify make_notch, document biquad notation, tighten set_coefficients guard

- Add a shared notation guide to butterworth_filter so the single-letter
  RBJ-cookbook names (w0/alpha/a0..a2/b0..b2) are self-explanatory across
  every filter instead of diverging in one function.
- Comment make_notch's feed-forward/feed-back sections in plain English.
- set_coefficients only fills the optional a_0 when exactly one coefficient
  is missing, so genuinely too-short inputs raise with their real length
  (new regression doctest).

Author: priya-sundaram-dev

audio_filters/butterworth_filter.py

@@ -9,6 +9,14 @@
 Alternatively you can use scipy.signal.butter, which should yield the same results.
 
 https://en.wikipedia.org/wiki/Butterworth_filter
+
+Notation used throughout this module (from the RBJ Audio EQ Cookbook):
+    w0     -- normalised angular frequency, ``2 * pi * frequency / samplerate``
+    alpha  -- bandwidth parameter, ``sin(w0) / (2 * q_factor)``
+    b0..b2 -- feed-forward (numerator) coefficients of the biquad
+    a0..a2 -- feed-back (denominator) coefficients of the biquad
+The a/b coefficient names match ``IIRFilter.set_coefficients`` and the standard
+biquad transfer function, so they are kept consistent across every filter here.
 """
 
 
@@ -254,15 +262,19 @@ def make_notch(
     [1.0922959556412573, -1.9828897227476208, 0.9077040443587427, 1.0,
      -1.9828897227476208, 1.0]
     """
-    w0 = tau * frequency / samplerate
+    w0 = tau * frequency / samplerate  # centre frequency, in radians/sample
     _sin = sin(w0)
     _cos = cos(w0)
-    alpha = _sin / (2 * q_factor)
+    alpha = _sin / (2 * q_factor)  # controls how narrow the rejected band is
 
+    # Feed-forward: a pair of zeros placed exactly on the notch frequency, so
+    # that frequency is fully cancelled while the rest of the spectrum passes.
     b0 = 1.0
     b1 = -2 * _cos
     b2 = 1.0
 
+    # Feed-back: matching poles just inside the unit circle keep the notch
+    # narrow and the surrounding gain flat.
     a0 = 1 + alpha
     a1 = -2 * _cos
     a2 = 1 - alpha

audio_filters/iir_filter.py

@@ -69,8 +69,19 @@ def set_coefficients(self, a_coeffs: list[float], b_coeffs: list[float]) -> None
         Traceback (most recent call last):
             ...
         ValueError: Expected b_coeffs to have 3 elements for 2-order filter, got 2
+
+        A genuinely too-short ``a_coeffs`` is reported with its real length
+        rather than after the optional ``a_0`` has been filled in:
+
+        >>> IIRFilter(2).set_coefficients([1.0], [1.0, 2.0, 3.0])
+        Traceback (most recent call last):
+            ...
+        ValueError: Expected a_coeffs to have 3 elements for 2-order filter, got 1
         """
-        if len(a_coeffs) < self.order + 1:
+        if len(a_coeffs) == self.order:
+            # The leading a_0 coefficient is optional; default it to 1.0.
+            # Only a single missing coefficient is filled in this way, so that
+            # genuinely too-short inputs are reported with their real length.
             a_coeffs = [1.0, *a_coeffs]
 
         if len(a_coeffs) != self.order + 1: