# SPDX-FileCopyrightText: 2026 Brad Barnett
#
# SPDX-License-Identifier: MIT
"""CircuitPython's filter effects: a biquad chain, a phaser and a distortion.
Each class is an audio source that reads another source, changes it and hands
the result on, so it sits in a chain like any other effect:
``mixer.play(effect)`` after ``effect.play(source)``. The module is
CircuitPython's own and takes the same arguments on every port, so a program
written for a board runs here unchanged. The biquad filter of
`audiobiquad`, which carries more options and whose tail reaches exact zero,
is a separate module.
A setting that takes a `synthio.BlockInput` can be a number, or a
`synthio.LFO` or `synthio.Math` that is read once a block.
"""
from __future__ import annotations
from types import TracebackType
from typing import Protocol, Self, Union
_BlockInput = Union[float, object, None]
"""A number, or a `synthio.LFO` or `synthio.Math` read once a block."""
_Biquad = object
"""A `synthio.Biquad`."""
class _AudioSample(Protocol):
@property
def sample_rate(self) -> int: ...
@property
def bits_per_sample(self) -> int: ...
@property
def channel_count(self) -> int: ...
[docs]
class DistortionMode:
"""The way `Distortion` shapes the signal."""
CLIP: DistortionMode
"""Hard clipping: anything past full scale is cut off."""
LOFI: DistortionMode
"""Bit reduction, which makes a gritty low-resolution sound."""
OVERDRIVE: DistortionMode
"""A rounded saturation that squeezes the peaks."""
WAVESHAPE: DistortionMode
"""A smooth curve that folds the peaks back."""
[docs]
class Filter:
"""A chain of biquad filters.
Args:
filter: A `synthio.Biquad`, or a sequence of them that run one after
another, or None for a wire. The same object is returned from
the `filter` property.
mix: How much of the filtered signal goes out: 0 is the dry signal
and 1 is the filtered one. A `synthio.BlockInput`.
buffer_size: The size in bytes of each block the filter hands out.
sample_rate: The rate of the audio in Hz. It must match the source.
bits_per_sample: 8 or 16. It must match the source.
samples_signed: Whether the samples are signed.
channel_count: 1 or 2. It must match the source.
Raises:
ValueError: ``channel_count`` is not 1 or 2, ``sample_rate`` is less
than 1, or ``bits_per_sample`` is not 8 or 16.
TypeError: ``filter`` holds something that is not a `synthio.Biquad`.
"""
def __init__(
self,
*,
filter: _Biquad | tuple[_Biquad, ...] | list[_Biquad] | None = None,
mix: _BlockInput = 1,
buffer_size: int = 512,
sample_rate: int = 8000,
bits_per_sample: int = 16,
samples_signed: bool = True,
channel_count: int = 1,
) -> None: ...
[docs]
def deinit(self) -> None:
"""Free the filter. Later calls other than `deinit` raise
`ValueError`."""
def __enter__(self) -> Self: ...
def __exit__(self, exc_type: type[BaseException] | None, exc: BaseException | None, tb: TracebackType | None, /) -> None: ...
sample_rate: int
"""Frames per second. Writable, to 1 or more."""
@property
def bits_per_sample(self) -> int:
"""Size of one sample in bits."""
@property
def channel_count(self) -> int:
"""Number of channels: 1 or 2."""
@property
def playing(self) -> bool:
"""True while a source is playing through the filter."""
filter: _Biquad | tuple[_Biquad, ...] | list[_Biquad] | None
"""The biquad or biquads applied to the signal."""
mix: _BlockInput
"""How much of the filtered signal goes out, 0 to 1."""
[docs]
def play(self, sample: _AudioSample, *, loop: bool = False) -> None:
"""Read from a source and filter it.
Args:
sample: The audio source to filter.
loop: Start the source over when it ends.
"""
[docs]
def stop(self) -> None:
"""Stop reading the source."""
[docs]
class Phaser:
"""A phaser: a cascade of all-pass stages mixed with the dry signal.
Args:
frequency: The corner frequency of the all-pass stages in Hz.
A `synthio.BlockInput`.
feedback: How much of the output goes back into the input, 0 to 1.
None leaves it off. A `synthio.BlockInput`.
mix: How much of the processed signal goes out, 0 to 1. A
`synthio.BlockInput`.
stages: How many all-pass stages. More stages make more notches.
buffer_size: The size in bytes of each block the effect hands out.
sample_rate: The rate of the audio in Hz. It must match the source.
bits_per_sample: 8 or 16. It must match the source.
samples_signed: Whether the samples are signed.
channel_count: 1 or 2. It must match the source.
Raises:
ValueError: ``channel_count`` is not 1 or 2, ``sample_rate`` is less
than 1, or ``bits_per_sample`` is not 8 or 16.
"""
def __init__(
self,
*,
frequency: _BlockInput = 1000,
feedback: _BlockInput = None,
mix: _BlockInput = 1,
stages: int = 6,
buffer_size: int = 512,
sample_rate: int = 8000,
bits_per_sample: int = 16,
samples_signed: bool = True,
channel_count: int = 1,
) -> None: ...
[docs]
def deinit(self) -> None:
"""Free the effect. Later calls other than `deinit` raise
`ValueError`."""
def __enter__(self) -> Self: ...
def __exit__(self, exc_type: type[BaseException] | None, exc: BaseException | None, tb: TracebackType | None, /) -> None: ...
sample_rate: int
"""Frames per second. Writable, to 1 or more."""
@property
def bits_per_sample(self) -> int:
"""Size of one sample in bits."""
@property
def channel_count(self) -> int:
"""Number of channels: 1 or 2."""
@property
def playing(self) -> bool:
"""True while a source is playing through the effect."""
frequency: _BlockInput
"""The corner frequency of the all-pass stages in Hz."""
feedback: _BlockInput
"""How much of the output goes back into the input."""
mix: _BlockInput
"""How much of the processed signal goes out, 0 to 1."""
stages: int
"""How many all-pass stages."""
[docs]
def play(self, sample: _AudioSample, *, loop: bool = False) -> None:
"""Read from a source and process it.
Args:
sample: The audio source.
loop: Start the source over when it ends.
"""
[docs]
def stop(self) -> None:
"""Stop reading the source."""
[docs]
class Distortion:
"""A distortion with four modes.
Args:
drive: How hard the signal is pushed, 0 to 1. A `synthio.BlockInput`.
pre_gain: Gain in dB before the distortion. A `synthio.BlockInput`.
post_gain: Gain in dB after the distortion. A `synthio.BlockInput`.
mode: A `DistortionMode`. The default is `DistortionMode.CLIP`.
soft_clip: Round off what the mode leaves past full scale instead of
wrapping it.
mix: How much of the distorted signal goes out, 0 to 1. A
`synthio.BlockInput`.
buffer_size: The size in bytes of each block the effect hands out.
sample_rate: The rate of the audio in Hz. It must match the source.
bits_per_sample: 8 or 16. It must match the source.
samples_signed: Whether the samples are signed.
channel_count: 1 or 2. It must match the source.
Raises:
ValueError: ``channel_count`` is not 1 or 2, ``sample_rate`` is less
than 1, or ``bits_per_sample`` is not 8 or 16.
"""
def __init__(
self,
*,
drive: _BlockInput = 0,
pre_gain: _BlockInput = 0,
post_gain: _BlockInput = 0,
mode: DistortionMode = ...,
soft_clip: bool = False,
mix: _BlockInput = 1,
buffer_size: int = 512,
sample_rate: int = 8000,
bits_per_sample: int = 16,
samples_signed: bool = True,
channel_count: int = 1,
) -> None: ...
[docs]
def deinit(self) -> None:
"""Free the effect. Later calls other than `deinit` raise
`ValueError`."""
def __enter__(self) -> Self: ...
def __exit__(self, exc_type: type[BaseException] | None, exc: BaseException | None, tb: TracebackType | None, /) -> None: ...
sample_rate: int
"""Frames per second. Writable, to 1 or more."""
@property
def bits_per_sample(self) -> int:
"""Size of one sample in bits."""
@property
def channel_count(self) -> int:
"""Number of channels: 1 or 2."""
@property
def playing(self) -> bool:
"""True while a source is playing through the effect."""
drive: _BlockInput
"""How hard the signal is pushed, 0 to 1."""
pre_gain: _BlockInput
"""Gain in dB before the distortion."""
post_gain: _BlockInput
"""Gain in dB after the distortion."""
mode: DistortionMode
"""The `DistortionMode` in use."""
soft_clip: bool
"""Whether the output is softly clipped."""
mix: _BlockInput
"""How much of the distorted signal goes out, 0 to 1."""
[docs]
def play(self, sample: _AudioSample, *, loop: bool = False) -> None:
"""Read from a source and distort it.
Args:
sample: The audio source.
loop: Start the source over when it ends.
"""
[docs]
def stop(self) -> None:
"""Stop reading the source."""