biquad 0.3__tar.gz → 0.4__tar.gz

{biquad-0.3/src/python/biquad.egg-info → biquad-0.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: biquad
-Version: 0.3
+Version: 0.4
 Summary: Collection of alterable digital biquad filters for dynamic audio effect creation
 Home-page: https://github.com/jurihock/biquad
 Author: Juergen Hock
@@ -24,6 +24,7 @@ Classifier: Topic :: Scientific/Engineering
 Classifier: Topic :: Software Development :: Libraries
 Requires-Python: >=3
 Description-Content-Type: text/markdown
+Provides-Extra: plot
 License-File: LICENSE
 
 # Alterable biquad filters
@@ -32,7 +33,7 @@ License-File: LICENSE
 ![license](https://img.shields.io/github/license/jurihock/biquad?color=green)
 ![pypi](https://img.shields.io/pypi/v/biquad?color=gold)
 
-This is a collection of digital biquad filters whose parameters `frequency` and `quality` can be varied at runtime. Following filter implementations are available:
+This is a collection of [digital biquad filters](https://webaudio.github.io/Audio-EQ-Cookbook/audio-eq-cookbook.html) whose parameters `f` (frequency in *Hz*), `g` (gain in *dB*) and `q` (quality) can be varied at runtime. Following [DF1](https://ccrma.stanford.edu/~jos/fp/Direct_Form_I.html) filter implementations are available:
 
 - Allpass
 - Bandpass
@@ -45,7 +46,7 @@ This is a collection of digital biquad filters whose parameters `frequency` and
 
 ## Basic usage
 
-Filter with persistent configuration:
+Filter with static configuration:
 
 ```python
 import biquad
@@ -81,6 +82,18 @@ myq = np.linspace(2,  1/2, len(x))
 y = f(x, f=myf, q=myq)
 ```
 
-## See also
+Keep in mind:
 
-[Cookbook formulae for audio equalizer biquad filter coefficients](https://webaudio.github.io/Audio-EQ-Cookbook/audio-eq-cookbook.html)
+- All filters have a default value for the persistent parameters `g` and `q`, which is set in the particular `__init__` method.
+- Parameter `f` must be set either in the `__init__` or in the `__call__` method.
+- The optional instantaneous parameters `f`, `g` and `q`, if specified in the `__call__` method, override the persistent ones. 
+
+## References
+
+1. <span id="1">[Cookbook formulae for audio EQ biquad filter coefficients](https://webaudio.github.io/Audio-EQ-Cookbook/audio-eq-cookbook.html) by Robert Bristow-Johnson</span>
+2. <span id="2">[Introduction to Digital Filters with Audio Applications](https://ccrma.stanford.edu/~jos/filters/filters.html) by Julius O. Smith III</span>
+
+## License
+
+[github.com/jurihock/biquad](https://github.com/jurihock/biquad) is licensed under the terms of the MIT license.
+For details please refer to the accompanying [LICENSE](https://github.com/jurihock/biquad/raw/main/LICENSE) file distributed with it.

biquad-0.4/README.md

@@ -0,0 +1,70 @@
+# Alterable biquad filters
+
+![language](https://img.shields.io/badge/languages-C%2B%2B%20Python-blue)
+![license](https://img.shields.io/github/license/jurihock/biquad?color=green)
+![pypi](https://img.shields.io/pypi/v/biquad?color=gold)
+
+This is a collection of [digital biquad filters](https://webaudio.github.io/Audio-EQ-Cookbook/audio-eq-cookbook.html) whose parameters `f` (frequency in *Hz*), `g` (gain in *dB*) and `q` (quality) can be varied at runtime. Following [DF1](https://ccrma.stanford.edu/~jos/fp/Direct_Form_I.html) filter implementations are available:
+
+- Allpass
+- Bandpass
+- Highpass
+- Lowpass
+- Highshelf
+- Lowshelf
+- Notch
+- Peak
+
+## Basic usage
+
+Filter with static configuration:
+
+```python
+import biquad
+import numpy as np
+
+# load audio samples somehow
+x, sr = np.zeros(...), 44100
+
+# create a filter of your choice
+f = biquad.bandpass(sr, f=sr/4, q=1)
+
+# process all audio samples
+y = f(x)
+```
+
+Filter with dynamic configuration:
+
+```python
+import biquad
+import numpy as np
+
+# load audio samples somehow
+x, sr = np.zeros(...), 44100
+
+# create a filter of your choice
+f = biquad.bandpass(sr)
+
+# create parameter modifications as you like
+myf = np.linspace(1, sr/4, len(x))
+myq = np.linspace(2,  1/2, len(x))
+
+# process all audio samples
+y = f(x, f=myf, q=myq)
+```
+
+Keep in mind:
+
+- All filters have a default value for the persistent parameters `g` and `q`, which is set in the particular `__init__` method.
+- Parameter `f` must be set either in the `__init__` or in the `__call__` method.
+- The optional instantaneous parameters `f`, `g` and `q`, if specified in the `__call__` method, override the persistent ones. 
+
+## References
+
+1. <span id="1">[Cookbook formulae for audio EQ biquad filter coefficients](https://webaudio.github.io/Audio-EQ-Cookbook/audio-eq-cookbook.html) by Robert Bristow-Johnson</span>
+2. <span id="2">[Introduction to Digital Filters with Audio Applications](https://ccrma.stanford.edu/~jos/filters/filters.html) by Julius O. Smith III</span>
+
+## License
+
+[github.com/jurihock/biquad](https://github.com/jurihock/biquad) is licensed under the terms of the MIT license.
+For details please refer to the accompanying [LICENSE](https://github.com/jurihock/biquad/raw/main/LICENSE) file distributed with it.

{biquad-0.3 → biquad-0.4}/setup.cfg

@@ -58,6 +58,10 @@ install_requires =
 	numba
 	numpy
 
+[options.extras_require]
+plot = 
+	matplotlib
+
 [egg_info]
 tag_build = 
 tag_date = 0

{biquad-0.3 → biquad-0.4}/src/python/biquad/__init__.py

@@ -1,4 +1,4 @@
-__version__ = "0.3"
+__version__ = "0.4"
 
 
 from .allpass   import allpass

{biquad-0.3 → biquad-0.4}/src/python/biquad/allpass.py

@@ -6,7 +6,7 @@ SPDX-License-Identifier: MIT
 Source: https://github.com/jurihock/biquad
 """
 
-from .biquad import biquad, __df1__
+from .biquad import biquad, __df1__, __gain__, __resize__
 
 import numba
 import numpy
@@ -17,7 +17,7 @@ class allpass(biquad):
     Allpass filter (APF).
     """
 
-    def __init__(self, sr, *, f=None, q=1):
+    def __init__(self, sr, f=None, g=0, q=1):
         """
         Create a new filter instance.
 
@@ -27,15 +27,17 @@ class allpass(biquad):
             Sample rate in hertz.
         f : int or float, optional
             Persistent filter frequency parameter in hertz.
+        g : int or float, optional
+            Persistent filter gain parameter in decibel.
         q : int or float, optional
             Persistent filter quality parameter.
         """
 
-        super().__init__(sr=sr, f=f, q=q)
+        super().__init__(sr=sr, f=f, g=g, q=q)
 
-        self.__call__(0, 1) # warmup numba
+        self.__call__(0) # warmup numba
 
-    def __call__(self, x, f=None, q=None):
+    def __call__(self, x, f=None, g=None, q=None):
         """
         Process single or multiple contiguous signal values at once.
 
@@ -45,6 +47,8 @@ class allpass(biquad):
             Filter input data.
         f : scalar or array like, optional
             Instantaneous filter frequency parameter in hertz.
+        g : scalar or array like, optional
+            Instantaneous filter gain parameter in decibel.
         q : scalar or array like, optional
             Instantaneous filter quality parameter.
 
@@ -62,21 +66,23 @@ class allpass(biquad):
         x = numpy.atleast_1d(x)
         y = numpy.zeros(x.shape, x.dtype)
 
-        f = numpy.atleast_1d(self.f if f is None else f)
-        q = numpy.atleast_1d(self.q if q is None else q)
-
-        f = numpy.resize(f, x.shape)
-        q = numpy.resize(q, x.shape)
+        f = __resize__(self.f if f is None else f, x.shape)
+        g = __resize__(self.g if g is None else __gain__(g), x.shape)
+        q = __resize__(self.q if q is None else q, x.shape)
 
         sr = self.sr
 
-        self.__filter__(ba, xy, x, y, f, q, sr)
+        self.__filter__(ba, xy, x, y, f, g, q, sr)
+
+        self.f = f[-1]
+        self.g = g[-1]
+        self.q = q[-1]
 
         return y[0] if scalar else y
 
     @staticmethod
     @numba.jit(nopython=True, fastmath=True)
-    def __filter__(ba, xy, x, y, f, q, sr):
+    def __filter__(ba, xy, x, y, f, g, q, sr):
 
         rs = 2 * numpy.pi / sr
 
@@ -87,18 +93,18 @@ class allpass(biquad):
             cosw = numpy.cos(w)
             sinw = numpy.sin(w)
 
-            c = -(2 * cosw)
-            p = sinw / (2 * q[i])
+            alpha = sinw / (+2 * q[i])
+            beta  = cosw * (-2)
 
             # update b
-            ba[0, 0] = 1 - p
-            ba[0, 1] =     c
-            ba[0, 2] = 1 + p
+            ba[0, 0] = 1 - alpha
+            ba[0, 1] =     beta
+            ba[0, 2] = 1 + alpha
 
             # update a
-            ba[1, 0] = 1 + p
-            ba[1, 1] =     c
-            ba[1, 2] = 1 - p
+            ba[1, 0] = 1 + alpha
+            ba[1, 1] =     beta
+            ba[1, 2] = 1 - alpha
 
             # update y
-            __df1__(ba, xy, x, y, i)
+            __df1__(g[i], ba, xy, x, y, i)

{biquad-0.3 → biquad-0.4}/src/python/biquad/bandpass.py

@@ -6,7 +6,7 @@ SPDX-License-Identifier: MIT
 Source: https://github.com/jurihock/biquad
 """
 
-from .biquad import biquad, __df1__
+from .biquad import biquad, __df1__, __gain__, __resize__
 
 import numba
 import numpy
@@ -17,7 +17,7 @@ class bandpass(biquad):
     Bandpass filter (BPF).
     """
 
-    def __init__(self, sr, gain='skirt', *, f=None, q=0.7071):
+    def __init__(self, sr, f=None, g=0, q=0.7071, *, mode='peak'):
         """
         Create a new filter instance.
 
@@ -25,23 +25,25 @@ class bandpass(biquad):
         ----------
         sr : int or float
             Sample rate in hertz.
-        gain : str, skirt or peak, optional
-            Choice between constant skirt gain or constant 0 dB peak gain.
         f : int or float, optional
             Persistent filter frequency parameter in hertz.
+        g : int or float, optional
+            Persistent filter gain parameter in decibel.
         q : int or float, optional
             Persistent filter quality parameter.
+        mode : str, peak or skirt, optional
+            Choice between constant 0 dB peak gain or constant skirt gain.
         """
 
-        super().__init__(sr=sr, f=f, q=q)
+        super().__init__(sr=sr, f=f, g=g, q=q)
 
-        assert gain in ['skirt', 'peak']
+        assert mode in ['peak', 'skirt']
 
-        self.gain = gain
+        self.mode = mode
 
-        self.__call__(0, 1) # warmup numba
+        self.__call__(0) # warmup numba
 
-    def __call__(self, x, f=None, q=None):
+    def __call__(self, x, f=None, g=None, q=None):
         """
         Process single or multiple contiguous signal values at once.
 
@@ -51,6 +53,8 @@ class bandpass(biquad):
             Filter input data.
         f : scalar or array like, optional
             Instantaneous filter frequency parameter in hertz.
+        g : scalar or array like, optional
+            Instantaneous filter gain parameter in decibel.
         q : scalar or array like, optional
             Instantaneous filter quality parameter.
 
@@ -68,25 +72,27 @@ class bandpass(biquad):
         x = numpy.atleast_1d(x)
         y = numpy.zeros(x.shape, x.dtype)
 
-        f = numpy.atleast_1d(self.f if f is None else f)
-        q = numpy.atleast_1d(self.q if q is None else q)
-
-        f = numpy.resize(f, x.shape)
-        q = numpy.resize(q, x.shape)
+        f = __resize__(self.f if f is None else f, x.shape)
+        g = __resize__(self.g if g is None else __gain__(g), x.shape)
+        q = __resize__(self.q if q is None else q, x.shape)
 
         sr = self.sr
-        gain = self.gain
+        mode = self.mode
+
+        self.__filter__(ba, xy, x, y, f, g, q, sr, mode)
 
-        self.__filter__(ba, xy, x, y, f, q, sr, gain)
+        self.f = f[-1]
+        self.g = g[-1]
+        self.q = q[-1]
 
         return y[0] if scalar else y
 
     @staticmethod
     @numba.jit(nopython=True, fastmath=True)
-    def __filter__(ba, xy, x, y, f, q, sr, gain):
+    def __filter__(ba, xy, x, y, f, g, q, sr, mode):
 
         rs = 2 * numpy.pi / sr
-        skirt = gain == 'skirt'
+        skirt = mode == 'skirt'
 
         for i in range(x.size):
 
@@ -95,19 +101,19 @@ class bandpass(biquad):
             cosw = numpy.cos(w)
             sinw = numpy.sin(w)
 
-            c = -(2 * cosw)
-            p = sinw / (2 * q[i])
-            g = sinw / 2 if skirt else p
+            alpha = sinw / (+2 * q[i])
+            beta  = cosw * (-2)
+            gamma = sinw / (+2) if skirt else alpha
 
             # update b
-            ba[0, 0] = +g
+            ba[0, 0] = +gamma
             ba[0, 1] =  0
-            ba[0, 2] = -g
+            ba[0, 2] = -gamma
 
             # update a
-            ba[1, 0] = 1 + p
-            ba[1, 1] =     c
-            ba[1, 2] = 1 - p
+            ba[1, 0] = 1 + alpha
+            ba[1, 1] =     beta
+            ba[1, 2] = 1 - alpha
 
             # update y
-            __df1__(ba, xy, x, y, i)
+            __df1__(g[i], ba, xy, x, y, i)