.. This file is auto-generated by the Sphinx pre-build hook in
   ``documentation/source/conf.py`` from
   ``documentation/source/_data/patcher_objects.json`` and the notes in
   ``documentation/source/_data/patcher_notes/``.
   Do not edit by hand — re-run ``python yse.py dump-patcher-meta`` to
   refresh the JSON, then ``make html`` to re-render this page.

Filters
=======

Audio-rate filters.

4 objects. Every entry is
pulled directly from the engine source via the ``ADD_DESCRIPTION`` /
``INLET_DOC`` / ``OUTLET_DOC`` / ``PARAM_DOC`` macros (see
:file:`YseEngine/patcher/pObject.h`). The ``~`` prefix marks DSP /
audio-rate objects; ``.`` marks control-rate objects.

.. contents::
   :local:
   :depth: 1

``~bp``
-------

Bandpass filter. Passes a frequency band centered on 'frequency' with bandwidth shaped by 'Q' (resonance).

:Kind: DSP (audio-rate)

The center frequency is in Hz; below 0.001 Hz, including the default 0, the
filter uses 10 Hz. A higher ``Q`` makes the band narrower; the default is 1.
A tone at the center frequency comes out at the input's level for every
``Q``. A ``Q`` low enough to open the band fully (below 0.001, or below about
``2 * pi * frequency / samplerate``) turns filtering off and passes the input
unchanged.

**Inlets**

.. list-table::
   :header-rows: 1
   :widths: 6 18 18 18 40

   * - #
     - Label
     - Accepts
     - Range
     - Description
   * - 0
     - in
     - BUFFER
     - -1.0 to 1.0
     - Audio input buffer.
   * - 1
     - freq
     - FLOAT
     - 0-20000 Hz
     - Center frequency in Hz.
   * - 2
     - Q
     - FLOAT
     - 0.1-100
     - Resonance / inverse bandwidth — higher narrows the band.


**Outlets**

.. list-table::
   :header-rows: 1
   :widths: 6 18 18 18 40

   * - #
     - Label
     - Type
     - Range
     - Description
   * - 0
     - out
     - BUFFER
     - -1.0 to 1.0
     - Filtered audio output.


**Parameters**

.. list-table::
   :header-rows: 1
   :widths: 22 18 18 42

   * - Name
     - Default
     - Range
     - Description
   * - frequency
     - 0
     - 0-20000 Hz
     - Initial center frequency in Hz.
   * - Q
     - 1
     - 0.1-100
     - Initial Q / resonance.


``~hp``
-------

Single-pole highpass filter. Attenuates content below the cutoff frequency.

:Kind: DSP (audio-rate)

At 0 Hz, the default, the input passes unchanged. As for ``~lp``, the cutoff
is an approximation that holds well at low frequencies; from about a sixth of
the sample rate up, the output is the difference between successive samples.

**Inlets**

.. list-table::
   :header-rows: 1
   :widths: 6 18 18 18 40

   * - #
     - Label
     - Accepts
     - Range
     - Description
   * - 0
     - in
     - BUFFER
     - -1.0 to 1.0
     - Audio input buffer.
   * - 1
     - cutoff
     - FLOAT
     - 0-20000 Hz
     - Cutoff frequency in Hz.


**Outlets**

.. list-table::
   :header-rows: 1
   :widths: 6 18 18 18 40

   * - #
     - Label
     - Type
     - Range
     - Description
   * - 0
     - out
     - BUFFER
     - -1.0 to 1.0
     - Filtered audio output.


**Parameters**

.. list-table::
   :header-rows: 1
   :widths: 22 18 18 42

   * - Name
     - Default
     - Range
     - Description
   * - frequency
     - 0
     - 0-20000 Hz
     - Initial cutoff frequency in Hz.


``~lp``
-------

Single-pole lowpass filter. Attenuates content above the cutoff frequency.

:Kind: DSP (audio-rate)

The cutoff argument defaults to 0 Hz, where the filter lets nothing through:
give it a cutoff (``~lp 800``). The cutoff is an approximation that holds
well at low frequencies. From about a sixth of the sample rate up (about
7 kHz at 44.1 kHz), the filter is fully open and passes the input unchanged.

**Inlets**

.. list-table::
   :header-rows: 1
   :widths: 6 18 18 18 40

   * - #
     - Label
     - Accepts
     - Range
     - Description
   * - 0
     - in
     - BUFFER
     - -1.0 to 1.0
     - Audio input buffer.
   * - 1
     - cutoff
     - FLOAT
     - 0-20000 Hz
     - Cutoff frequency in Hz.


**Outlets**

.. list-table::
   :header-rows: 1
   :widths: 6 18 18 18 40

   * - #
     - Label
     - Type
     - Range
     - Description
   * - 0
     - out
     - BUFFER
     - -1.0 to 1.0
     - Filtered audio output.


**Parameters**

.. list-table::
   :header-rows: 1
   :widths: 22 18 18 42

   * - Name
     - Default
     - Range
     - Description
   * - frequency
     - 0
     - 0-20000 Hz
     - Initial cutoff frequency in Hz.


``~vcf``
--------

Resonant bandpass filter whose center frequency is a signal, so it can sweep at audio rate. Sharpness sets how narrow the band is.

:Kind: DSP (audio-rate)

Unlike ``~bp``, the center frequency comes in as a signal, in Hz, so it can
be swept smoothly or modulated at audio rate. Feed it from ``~line`` or an
oscillator scaled to a frequency range.

``sharpness`` sets how narrow the band is: higher is narrower. At 0, the
default, the left outlet passes the input unchanged and the right outlet is
silent.

Nothing comes out unless both the audio input and the center frequency are
connected.

**Inlets**

.. list-table::
   :header-rows: 1
   :widths: 6 18 18 18 40

   * - #
     - Label
     - Accepts
     - Range
     - Description
   * - 0
     - in
     - BUFFER
     - -1.0 to 1.0
     - Audio input.
   * - 1
     - center
     - BUFFER
     - 0-20000 Hz
     - Center frequency in Hz, as a signal. Both signal inlets must be connected for the filter to run.
   * - 2
     - sharpness
     - FLOAT
     - 0+
     - How narrow the band is: higher is narrower. 0 turns filtering off.


**Outlets**

.. list-table::
   :header-rows: 1
   :widths: 6 18 18 18 40

   * - #
     - Label
     - Type
     - Range
     - Description
   * - 0
     - real
     - BUFFER
     - -1.0 to 1.0
     - The bandpass output.
   * - 1
     - imag
     - BUFFER
     - -1.0 to 1.0
     - The imaginary part of the resonator, a lowpass-like response.


**Parameters**

.. list-table::
   :header-rows: 1
   :widths: 22 18 18 42

   * - Name
     - Default
     - Range
     - Description
   * - sharpness
     - 0
     - 0+
     - Initial sharpness.