Merge branch 'master' into add-fast-walsh-hadamard-transform

Author: Clear20-22

.github/workflows/build.yml

@@ -17,7 +17,7 @@ jobs:
           cache-dependency-glob: uv.lock
       - uses: actions/setup-python@v7
         with:
-          python-version: 3.14
+          python-version-file: pyproject.toml
           allow-prereleases: true
       - run: uv sync --group=test
       - name: Run tests

.github/workflows/directory_writer.yml

@@ -11,7 +11,7 @@ jobs:
           fetch-depth: 0
       - uses: actions/setup-python@v7
         with:
-          python-version: 3.14
+          python-version-file: pyproject.toml
           allow-prereleases: true
       - name: Write DIRECTORY.md
         run: |

.github/workflows/project_euler.yml

@@ -25,7 +25,7 @@ jobs:
       - uses: astral-sh/setup-uv@v7
       - uses: actions/setup-python@v7
         with:
-          python-version: 3.14
+          python-version-file: pyproject.toml
           allow-prereleases: true
       - run: uv sync --group=euler-validate --group=test
       - run: uv run pytest --doctest-modules --cov-report=term-missing:skip-covered --cov=project_euler/ project_euler/
@@ -43,7 +43,7 @@ jobs:
       - uses: astral-sh/setup-uv@v7
       - uses: actions/setup-python@v7
         with:
-          python-version: 3.14
+          python-version-file: pyproject.toml
           allow-prereleases: true
       - run: uv sync --group=euler-validate --group=test
       - run: uv run pytest scripts/validate_solutions.py

.github/workflows/sphinx.yml

@@ -36,7 +36,7 @@ jobs:
       - uses: astral-sh/setup-uv@v7
       - uses: actions/setup-python@v7
         with:
-          python-version: 3.14
+          python-version-file: pyproject.toml
           allow-prereleases: true
       - run: uv sync --group=docs
       - uses: actions/configure-pages@v6

.pre-commit-config.yaml

@@ -1,5 +1,8 @@
 ci:
   autoupdate_schedule: monthly
+  # uv-lock resolves dependencies from PyPI, but pre-commit.ci runs hooks with no
+  # network access, so it fails there. Skip it on pre-commit.ci; it still runs locally.
+  skip: [uv-lock]
 
 repos:
   - repo: https://github.com/pre-commit/pre-commit-hooks
@@ -18,6 +21,11 @@ repos:
     hooks:
       - id: auto-walrus
 
+  - repo: https://github.com/astral-sh/uv-pre-commit
+    rev: 0.12.7
+    hooks:
+      - id: uv-lock
+
   - repo: https://github.com/astral-sh/ruff-pre-commit
     rev: v0.16.1
     hooks:

audio_filters/README.md

@@ -1,9 +1,58 @@
-# Audio Filter
+# Audio Filters
 
-Audio filters work on the frequency of an audio signal to attenuate unwanted frequency and amplify wanted ones.
-They are used within anything related to sound, whether it is radio communication or a hi-fi system.
+Audio filters work on the frequency of an audio signal to attenuate unwanted
+frequencies and amplify wanted ones. They are used within anything related to
+sound, whether it is radio communication or a hi-fi system. If you have ever
+turned up the bass or cut the treble on a stereo, tuned a radio to a station, or
+removed the background hum from a recording, you have used an audio filter.
+
+Curious to learn more? These are great starting points:
 
 * <https://www.masteringbox.com/filter-types/>
 * <http://ethanwiner.com/filters.html>
 * <https://en.wikipedia.org/wiki/Audio_filter>
 * <https://en.wikipedia.org/wiki/Electronic_filter>
+* <https://webaudio.github.io/Audio-EQ-Cookbook/audio-eq-cookbook.html>
+
+## What's in this directory
+
+| File | Description |
+| ---- | ----------- |
+| [`iir_filter.py`](iir_filter.py) | A generic N-order [Infinite Impulse Response (IIR)](https://en.wikipedia.org/wiki/Infinite_impulse_response) filter. This is the engine every filter below runs on: give it a set of coefficients and it processes a stream of samples one at a time. |
+| [`butterworth_filter.py`](butterworth_filter.py) | A collection of second-order [Butterworth](https://en.wikipedia.org/wiki/Butterworth_filter) / biquad filter designs from the RBJ Audio EQ Cookbook. Each function returns a ready-to-use `IIRFilter`. |
+| [`equal_loudness_filter.py`](equal_loudness_filter.py) | An [equal-loudness](https://en.wikipedia.org/wiki/Equal-loudness_contour) filter that compensates for the human ear's non-linear response to sound by cascading a Yule-Walker filter and a Butterworth high-pass filter. Includes a dependency-free `yulewalk` implementation. |
+| [`show_response.py`](show_response.py) | Helpers to plot the [magnitude and phase response](https://en.wikipedia.org/wiki/Frequency_response) of any filter so you can *see* what it does. |
+| [`loudness_curve.json`](loudness_curve.json) | The Robinson-Dadson equal-loudness contour data used by the equal-loudness filter. |
+
+## Filter designs in `butterworth_filter.py`
+
+| Function | Effect |
+| -------- | ------ |
+| `make_lowpass` | Passes frequencies below the cutoff, attenuates those above it. |
+| `make_highpass` | Passes frequencies above the cutoff, attenuates those below it. |
+| `make_bandpass` | Passes a band of frequencies around the center (constant skirt gain). |
+| `make_bandpass_peak` | Passes a band of frequencies around the center (constant 0 dB peak gain). |
+| `make_notch` | Rejects a narrow band around the center — great for removing mains hum. |
+| `make_allpass` | Passes all frequencies but changes their phase relationship. |
+| `make_peak` | Boosts or cuts a band around the center by a given gain (parametric EQ). |
+| `make_lowshelf` | Boosts or cuts everything below the cutoff. |
+| `make_highshelf` | Boosts or cuts everything above the cutoff. |
+
+## Try it out
+
+```python
+from audio_filters.butterworth_filter import make_lowpass
+from audio_filters.show_response import show_frequency_response
+
+# A 5 kHz low-pass filter for CD-quality audio (44.1 kHz sample rate)
+filt = make_lowpass(5000, 44100)
+
+# Process samples one at a time...
+filtered = [filt.process(sample) for sample in my_audio_samples]
+
+# ...or visualise what the filter does to the spectrum:
+show_frequency_response(make_lowpass(5000, 44100), 44100)
+```
+
+Every module has runnable doctests — read them for concrete, copy-pasteable
+examples of each filter in action.

audio_filters/butterworth_filter.py

@@ -7,6 +7,16 @@
 
 Code based on https://webaudio.github.io/Audio-EQ-Cookbook/audio-eq-cookbook.html
 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.
 """
 
 
@@ -232,3 +242,81 @@ def make_highshelf(
     filt = IIRFilter(2)
     filt.set_coefficients([a0, a1, a2], [b0, b1, b2])
     return filt
+
+
+def make_notch(
+    frequency: int,
+    samplerate: int,
+    q_factor: float = 1 / sqrt(2),
+) -> IIRFilter:
+    """
+    Creates a notch (band-reject) filter that strongly attenuates a narrow band
+    of frequencies around ``frequency`` while leaving the rest of the spectrum
+    unchanged. It is the complement of the band-pass filter and is commonly used
+    to remove a single tone such as 50/60 Hz mains hum.
+
+    https://en.wikipedia.org/wiki/Band-stop_filter
+
+    >>> filter = make_notch(1000, 48000)
+    >>> filter.a_coeffs + filter.b_coeffs  # doctest: +NORMALIZE_WHITESPACE
+    [1.0922959556412573, -1.9828897227476208, 0.9077040443587427, 1.0,
+     -1.9828897227476208, 1.0]
+    """
+    w0 = tau * frequency / samplerate  # centre frequency, in radians/sample
+    _sin = sin(w0)
+    _cos = cos(w0)
+    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
+
+    filt = IIRFilter(2)
+    filt.set_coefficients([a0, a1, a2], [b0, b1, b2])
+    return filt
+
+
+def make_bandpass_peak(
+    frequency: int,
+    samplerate: int,
+    q_factor: float = 1 / sqrt(2),
+) -> IIRFilter:
+    """
+    Creates a band-pass filter with constant 0 dB peak gain.
+
+    Unlike :func:`make_bandpass`, whose skirt (edge) gain is held constant so the
+    peak gain grows with ``q_factor``, this variant normalises the response so
+    the peak always reaches 0 dB regardless of the chosen ``q_factor``. Both
+    forms come from the RBJ Audio EQ Cookbook.
+
+    https://en.wikipedia.org/wiki/Band-pass_filter
+
+    >>> filter = make_bandpass_peak(1000, 48000)
+    >>> filter.a_coeffs + filter.b_coeffs  # doctest: +NORMALIZE_WHITESPACE
+    [1.0922959556412573, -1.9828897227476208, 0.9077040443587427,
+     0.09229595564125725, 0, -0.09229595564125725]
+    """
+    w0 = tau * frequency / samplerate
+    _sin = sin(w0)
+    _cos = cos(w0)
+    alpha = _sin / (2 * q_factor)
+
+    b0 = alpha
+    b1 = 0
+    b2 = -alpha
+
+    a0 = 1 + alpha
+    a1 = -2 * _cos
+    a2 = 1 - alpha
+
+    filt = IIRFilter(2)
+    filt.set_coefficients([a0, a1, a2], [b0, b1, b2])
+    return filt