biquad 0.2__tar.gz → 0.4__tar.gz

biquad-0.4/PKG-INFO

@@ -0,0 +1,99 @@
+Metadata-Version: 2.1
+Name: biquad
+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
+Author-email: juergen.hock@jurihock.de
+License: MIT
+Keywords: digital,audio,signal,processing,dasp,dafx,effects,filter,equalizer,eq,biquad,frequency,phase,spectrum,algorithms,analysis,synthesis,c,cpp,python
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Education
+Classifier: Intended Audience :: Other Audience
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: C
+Classifier: Programming Language :: C++
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Artistic Software
+Classifier: Topic :: Education
+Classifier: Topic :: Multimedia :: Sound/Audio
+Classifier: Topic :: Multimedia :: Sound/Audio :: Analysis
+Classifier: Topic :: Multimedia :: Sound/Audio :: Sound Synthesis
+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
+
+![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.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.2 → 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.2 → biquad-0.4}/src/python/biquad/__init__.py

@@ -1,4 +1,4 @@
-__version__ = "0.2"
+__version__ = "0.4"
 
 
 from .allpass   import allpass
@@ -13,6 +13,18 @@ from .peak      import peak
 
 
 def filter(name, sr, **kwargs):
+    """
+    Create a filter instance of the specified filter name.
+
+    Parameters
+    ----------
+    sr : int or float
+        Sample rate in hertz.
+    f : int or float, optional
+        Persistent filter frequency parameter in hertz.
+    q : int or float, optional
+        Persistent filter quality parameter.
+    """
 
     name = str(name).lower()
 

biquad-0.4/src/python/biquad/allpass.py

@@ -0,0 +1,110 @@
+"""
+Copyright (c) 2023 Juergen Hock
+
+SPDX-License-Identifier: MIT
+
+Source: https://github.com/jurihock/biquad
+"""
+
+from .biquad import biquad, __df1__, __gain__, __resize__
+
+import numba
+import numpy
+
+
+class allpass(biquad):
+    """
+    Allpass filter (APF).
+    """
+
+    def __init__(self, sr, f=None, g=0, q=1):
+        """
+        Create a new filter instance.
+
+        Parameters
+        ----------
+        sr : int or float
+            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, g=g, q=q)
+
+        self.__call__(0) # warmup numba
+
+    def __call__(self, x, f=None, g=None, q=None):
+        """
+        Process single or multiple contiguous signal values at once.
+
+        Parameters
+        ----------
+        x : scalar or array like
+            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.
+
+        Returns
+        -------
+        y : scalar or ndarray
+            Filter output data of the same shape and dtype as the input x.
+        """
+
+        scalar = numpy.isscalar(x)
+
+        ba = self.ba
+        xy = self.xy
+
+        x = numpy.atleast_1d(x)
+        y = numpy.zeros(x.shape, x.dtype)
+
+        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, 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, g, q, sr):
+
+        rs = 2 * numpy.pi / sr
+
+        for i in range(x.size):
+
+            w = f[i] * rs
+
+            cosw = numpy.cos(w)
+            sinw = numpy.sin(w)
+
+            alpha = sinw / (+2 * q[i])
+            beta  = cosw * (-2)
+
+            # update b
+            ba[0, 0] = 1 - alpha
+            ba[0, 1] =     beta
+            ba[0, 2] = 1 + alpha
+
+            # update a
+            ba[1, 0] = 1 + alpha
+            ba[1, 1] =     beta
+            ba[1, 2] = 1 - alpha
+
+            # update y
+            __df1__(g[i], ba, xy, x, y, i)

biquad-0.4/src/python/biquad/bandpass.py

@@ -0,0 +1,119 @@
+"""
+Copyright (c) 2023 Juergen Hock
+
+SPDX-License-Identifier: MIT
+
+Source: https://github.com/jurihock/biquad
+"""
+
+from .biquad import biquad, __df1__, __gain__, __resize__
+
+import numba
+import numpy
+
+
+class bandpass(biquad):
+    """
+    Bandpass filter (BPF).
+    """
+
+    def __init__(self, sr, f=None, g=0, q=0.7071, *, mode='peak'):
+        """
+        Create a new filter instance.
+
+        Parameters
+        ----------
+        sr : int or float
+            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.
+        mode : str, peak or skirt, optional
+            Choice between constant 0 dB peak gain or constant skirt gain.
+        """
+
+        super().__init__(sr=sr, f=f, g=g, q=q)
+
+        assert mode in ['peak', 'skirt']
+
+        self.mode = mode
+
+        self.__call__(0) # warmup numba
+
+    def __call__(self, x, f=None, g=None, q=None):
+        """
+        Process single or multiple contiguous signal values at once.
+
+        Parameters
+        ----------
+        x : scalar or array like
+            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.
+
+        Returns
+        -------
+        y : scalar or ndarray
+            Filter output data of the same shape and dtype as the input x.
+        """
+
+        scalar = numpy.isscalar(x)
+
+        ba = self.ba
+        xy = self.xy
+
+        x = numpy.atleast_1d(x)
+        y = numpy.zeros(x.shape, x.dtype)
+
+        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
+        mode = self.mode
+
+        self.__filter__(ba, xy, x, y, f, g, q, sr, mode)
+
+        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, g, q, sr, mode):
+
+        rs = 2 * numpy.pi / sr
+        skirt = mode == 'skirt'
+
+        for i in range(x.size):
+
+            w = f[i] * rs
+
+            cosw = numpy.cos(w)
+            sinw = numpy.sin(w)
+
+            alpha = sinw / (+2 * q[i])
+            beta  = cosw * (-2)
+            gamma = sinw / (+2) if skirt else alpha
+
+            # update b
+            ba[0, 0] = +gamma
+            ba[0, 1] =  0
+            ba[0, 2] = -gamma
+
+            # update a
+            ba[1, 0] = 1 + alpha
+            ba[1, 1] =     beta
+            ba[1, 2] = 1 - alpha
+
+            # update y
+            __df1__(g[i], ba, xy, x, y, i)

biquad-0.4/src/python/biquad/biquad.py

@@ -0,0 +1,270 @@
+"""
+Copyright (c) 2023 Juergen Hock
+
+SPDX-License-Identifier: MIT
+
+Source: https://github.com/jurihock/biquad
+"""
+
+import numba
+import numpy
+
+
+@numba.jit(nopython=True, fastmath=True)
+def __df1__(g, ba, xy, x, y, i):
+    """
+    Compute filter output y[i] based on filter input x[i]
+    as well as specified filter gain g, coeffs ba and delay line xy,
+    according to the Direct Form 1.
+    """
+
+    # roll x
+    xy[0, 2] = xy[0, 1]
+    xy[0, 1] = xy[0, 0]
+
+    # roll y
+    xy[1, 2] = xy[1, 1]
+    xy[1, 1] = xy[1, 0]
+
+    # update x
+    xy[0, 0] = x[i]
+
+    # compute intermediate results b*x and a*y
+    bx = ba[0, 0] * xy[0, 0] + ba[0, 1] * xy[0, 1] + ba[0, 2] * xy[0, 2]
+    ay =                       ba[1, 1] * xy[1, 1] + ba[1, 2] * xy[1, 2]
+
+    # update y
+    xy[1, 0] = (bx * g - ay) / ba[1, 0]
+
+    # return y
+    y[i] = xy[1, 0]
+
+
+def __gain__(x, divisor=20):
+    """
+    Convert the specified decibel gain to the linear gain.
+    """
+
+    if numpy.isscalar(x):
+
+        y = x / divisor
+        y = 10 ** y
+
+    else:
+
+        y = numpy.atleast_1d(x) / divisor
+        numpy.power(10, y, out=y)
+
+    return y
+
+
+def __resize__(x, shape):
+    """
+    Resize the specified value to the ndarray of desired shape.
+    """
+
+    if numpy.isscalar(x):
+
+        y = numpy.full(shape, x)
+
+    else:
+
+        x = numpy.atleast_1d(x)
+        y = numpy.resize(x, shape)
+
+    return y
+
+
+class biquad:
+    """
+    Biquad filter base class.
+    """
+
+    ba = numpy.array([[1, 0, 0], [1, 0, 0]], float)
+    """
+    Biquad filter coefficient matrix of shape (2, 3) excl. gain factor:
+        - ba[0] holds b coefficients
+        - ba[1] holds a coefficients
+    """
+
+    xy = numpy.array([[0, 0, 0], [0, 0, 0]], float)
+    """
+    Biquad filter delay line matrix of shape (2, 3):
+        - xy[0] holds input values
+        - xy[1] holds output values
+    """
+
+    def __init__(self, sr, f=None, g=None, q=None):
+        """
+        Create a new filter instance.
+
+        Parameters
+        ----------
+        sr : int or float
+            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.
+        """
+
+        assert (sr is not None) and (numpy.isscalar(sr) and numpy.isreal(sr))
+        assert (f  is     None) or  (numpy.isscalar(f)  and numpy.isreal(f))
+        assert (g  is     None) or  (numpy.isscalar(g)  and numpy.isreal(g))
+        assert (q  is     None) or  (numpy.isscalar(q)  and numpy.isreal(q))
+
+        self.sr = sr
+        self.f  = (sr / 4) if f is None else f
+        self.g  = __gain__(0 if g is None else g)
+        self.q  = 1 if q is None else q
+
+        # warmup numba
+        g  = self.g
+        ba = self.ba
+        xy = self.xy
+        x  = numpy.zeros(1, float)
+        y  = numpy.zeros(x.shape, x.dtype)
+        __df1__(g, ba, xy, x, y, 0)
+
+    def __call__(self, x, f=None, g=None, q=None):
+        """
+        Process single or multiple contiguous signal values at once.
+
+        Parameters
+        ----------
+        x : scalar or array like
+            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.
+
+        Returns
+        -------
+        y : scalar or ndarray
+            Filter output data of the same shape and dtype as the input x.
+        """
+
+        scalar = numpy.isscalar(x)
+
+        ba = self.ba
+        xy = self.xy
+
+        x = numpy.atleast_1d(x)
+        y = numpy.zeros(x.shape, x.dtype)
+
+        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)
+
+        self.__filter__(ba, xy, x, y, g)
+
+        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, g):
+
+        for i in range(x.size):
+
+            __df1__(g[i], ba, xy, x, y, i)
+
+    def response(self, *, norm=False, log=False):
+        """
+        Returns frequency and phase response of the transfer function given by the ba coefficients.
+
+        Parameters
+        ----------
+        norm : bool, optional
+            Option whether to normalize the output frequency response.
+        log : bool, optional
+            Option whether to express the output frequency values logarithmically.
+
+        Returns
+        -------
+        w : array
+            Corresponding frequency values.
+        h : array
+            Complex filter response values.
+
+        See also
+        --------
+            scipy.signal.freqz
+        """
+
+        (b, a), sr = self.ba, self.sr
+
+        b *= self.g
+
+        n = int(sr / 2)
+
+        # compute frequencies from 0 to pi or sr/2 but excluding the Nyquist frequency
+        w = numpy.linspace(0, numpy.pi, n, endpoint=False) \
+            if not log else \
+            numpy.logspace(numpy.log10(1), numpy.log10(numpy.pi), n, endpoint=False, base=10)
+
+        # compute the z-domain transfer function
+        z = numpy.exp(-1j * w)
+        x = numpy.polynomial.polynomial.polyval(z, a, tensor=False)
+        y = numpy.polynomial.polynomial.polyval(z, b, tensor=False)
+        h = y / x
+
+        # normalize frequency amplitudes
+        h /= len(h) if norm else 1
+
+        # normalize frequency values according to sr
+        w = (w * sr) / (2 * numpy.pi)
+
+        return w, h
+
+    def plot(self, *, log=False):
+        """
+        Creates filter frequency and phase response plot.
+
+        Parameters
+        ----------
+        log : bool, optional
+            Option whether to express frequency values logarithmically.
+        """
+
+        import matplotlib.pyplot as pyplot
+
+        w, h = self.response()
+
+        with numpy.errstate(divide='ignore', invalid='ignore'):
+            habs = 20 * numpy.log10(numpy.abs(h))
+
+        harg = numpy.angle(h)
+
+        pyplot.plot(w, habs, color='b', alpha=0.9)
+        axis1 = pyplot.gca()
+        axis2 = axis1.twinx()
+        axis2.plot(w, harg, color='g', alpha=0.9)
+
+        axis1.set_xlabel('Hz')
+        axis1.set_ylabel('dB',  color='b')
+        axis2.set_ylabel('rad', color='g')
+
+        habsmin = numpy.min(habs[numpy.isfinite(habs)])
+        habsmax = numpy.max(habs[numpy.isfinite(habs)])
+
+        habsmin = numpy.minimum(habsmin, -100)
+        habsmax = numpy.maximum(habsmax, +10)
+
+        hargmin = -numpy.pi
+        hargmax = +numpy.pi
+
+        axis1.set_ylim((habsmin * 1.1, habsmax * 1.1))
+        axis2.set_ylim((hargmin * 1.1, hargmax * 1.1))
+
+        if log: axis1.set_xscale('log')
+
+        return pyplot