audiofilters – Support for audio filter effects

The audiofilters module contains classes to provide access to audio filter effects.

Available on these boards
  • Adafruit Feather RP2350
  • Adafruit Feather RP2350 Adalogger
  • Adafruit Fruit Jam
  • Adafruit Metro RP2350
  • Adafruit Tinychad RP2350
  • Challenger+ RP2350 BConnect
  • Challenger+ RP2350 WiFi6/BLE5
  • Cytron EDU PICO 2
  • Cytron IRIV IO Controller
  • Cytron MOTION 2350 Pro
  • Datanoise PicoADK V2
  • Music Thing Modular Workshop Computer
  • NXP Semiconductors FRDM-MCXN947
  • NXP Semiconductors MIMXRT1170-EVK
  • Nordic Semiconductor nRF5340 DK
  • POSIX/Native Boards Native simulator - native_sim
  • Pimoroni Badger 2350
  • Pimoroni Explorer
  • Pimoroni PGA2350
  • Pimoroni Pico Plus 2
  • Pimoroni Pico Plus 2 W
  • Pimoroni Plasma 2350
  • Pimoroni Plasma 2350W
  • Pimoroni Tiny 2350
  • RP2350 Stamp
  • RP2350 Stamp XL
  • Raspberry Pi Pico 2
  • Raspberry Pi Pico 2 W
  • Seeeduino XIAO RP2350
  • SparkFun Pro Micro RP2350
  • SparkFun Thing Plus RP2350
  • Studiolab Pico Expander
  • TinyCircuits Thumby Color
  • W5100S-EVB-Pico2
  • W5500-EVB-Pico2
  • Waveshare RP2350-GEEK
  • Waveshare RP2350-LCD-0.96
  • Waveshare RP2350-LCD-1.28
  • Waveshare RP2350-One
  • Waveshare RP2350-Plus
  • Waveshare RP2350-TOUCH-LCD-1.28
  • Waveshare RP2350-Tiny
  • Waveshare RP2350-Zero
  • WeAct Studio RP2350B Core

class audiofilters.DistortionMode

The method of distortion used by the audiofilters.Distortion effect.

CLIP: DistortionMode

Digital distortion effect which cuts off peaks at the top and bottom of the waveform.

LOFI: DistortionMode

Low-resolution digital distortion effect (bit depth reduction). You can use it to emulate the sound of early digital audio devices.

OVERDRIVE: DistortionMode

Emulates the warm distortion produced by a field effect transistor, which is commonly used in solid-state musical instrument amplifiers. The audiofilters.Distortion.drive property has no effect in this mode.

WAVESHAPE: DistortionMode

Waveshaper distortions are used mainly by electronic musicians to achieve an extra-abrasive sound.

class audiofilters.Distortion(drive: synthio.BlockInput = 0.0, pre_gain: synthio.BlockInput = 0.0, post_gain: synthio.BlockInput = 0.0, mode: DistortionMode = DistortionMode.CLIP, soft_clip: bool = False, mix: synthio.BlockInput = 1.0, buffer_size: int = 512, sample_rate: int = 8000, bits_per_sample: int = 16, samples_signed: bool = True, channel_count: int = 1)

A Distortion effect

Create a Distortion effect where the original sample is manipulated to create a distorted

sound according to the DistortionMode.

The mix parameter allows you to change how much of the unchanged sample passes through to the output to how much of the effect audio you hear as the output.

Parameters:

  • drive (synthio.BlockInput) – Distortion power. Value can range from 0.0 to 1.0.

  • pre_gain (synthio.BlockInput) – Increases or decreases the volume before the effect, in decibels. Value can range from -60 to 60.

  • post_gain (synthio.BlockInput) – Increases or decreases the volume after the effect, in decibels. Value can range from -80 to 24.

  • mode (DistortionMode) – Distortion type.

  • soft_clip (bool) – Whether or not to soft clip (True) or hard clip (False) the output.

  • mix (synthio.BlockInput) – The mix as a ratio of the sample (0.0) to the effect (1.0).

  • buffer_size (int) – The total size in bytes of each of the two playback buffers to use

  • sample_rate (int) – The sample rate to be used

  • channel_count (int) – The number of channels the source samples contain. 1 = mono; 2 = stereo.

  • bits_per_sample (int) – The bits per sample of the effect

  • samples_signed (bool) – Effect is signed (True) or unsigned (False)

Playing adding a distortion to a synth:

import time
import board
import audiobusio
import synthio
import audiofilters

audio = audiobusio.I2SOut(bit_clock=board.GP20, word_select=board.GP21, data=board.GP22)
synth = synthio.Synthesizer(channel_count=1, sample_rate=44100)
effect = audiofilters.Distortion(drive=0.5, mix=1.0, buffer_size=1024, channel_count=1, sample_rate=44100)
effect.play(synth)
audio.play(effect)

note = synthio.Note(261)
while True:
    synth.press(note)
    time.sleep(0.25)
    synth.release(note)
    time.sleep(5)
deinit() → None

Deinitialises the Distortion.

__enter__() → Distortion

No-op used by Context Managers.

__exit__() → None

Automatically deinitializes when exiting a context. See Lifetime and ContextManagers for more info.

drive: synthio.BlockInput

Distortion power. Value can range from 0.0 to 1.0.

pre_gain: synthio.BlockInput

Increases or decreases the volume before the effect, in decibels. Value can range from -60 to 60.

post_gain: synthio.BlockInput

Increases or decreases the volume after the effect, in decibels. Value can range from -80 to 24.

mode: DistortionMode

Distortion type.

soft_clip: bool

Whether or not to soft clip (True) or hard clip (False) the output.

mix: synthio.BlockInput

The rate the filtered signal mix between 0 and 1 where 0 is only sample and 1 is all effect.

playing: bool

True when the effect is playing a sample. (read-only)

play(sample: circuitpython_typing.AudioSample, *, loop: bool = False) → Distortion

Plays the sample once when loop=False and continuously when loop=True. Does not block. Use playing to block.

The sample must match the encoding settings given in the constructor.

Returns:

The effect object itself. Can be used for chaining, ie: audio.play(effect.play(sample)).

Return type:

Distortion

stop() → None

Stops playback of the sample.

class audiofilters.Filter(filter: synthio.Biquad | Tuple[synthio.Biquad] | None = None, mix: synthio.BlockInput = 1.0, buffer_size: int = 512, sample_rate: int = 8000, bits_per_sample: int = 16, samples_signed: bool = True, channel_count: int = 1)

A Filter effect

Create a Filter effect where the original sample is processed through a biquad filter

created by a synthio.Synthesizer object. This can be used to generate a low-pass, high-pass, or band-pass filter.

The mix parameter allows you to change how much of the unchanged sample passes through to the output to how much of the effect audio you hear as the output.

Parameters:

  • filter (Optional[synthio.Biquad|Tuple[synthio.Biquad]]) – A normalized biquad filter object or tuple of normalized biquad filter objects. The sample is processed sequentially by each filter to produce the output samples.

  • mix (synthio.BlockInput) – The mix as a ratio of the sample (0.0) to the effect (1.0).

  • buffer_size (int) – The total size in bytes of each of the two playback buffers to use

  • sample_rate (int) – The sample rate to be used

  • channel_count (int) – The number of channels the source samples contain. 1 = mono; 2 = stereo.

  • bits_per_sample (int) – The bits per sample of the effect

  • samples_signed (bool) – Effect is signed (True) or unsigned (False)

Playing adding a filter to a synth:

import time
import board
import audiobusio
import synthio
import audiofilters

audio = audiobusio.I2SOut(bit_clock=board.GP20, word_select=board.GP21, data=board.GP22)
synth = synthio.Synthesizer(channel_count=1, sample_rate=44100)
effect = audiofilters.Filter(buffer_size=1024, channel_count=1, sample_rate=44100, mix=1.0)
effect.filter = synth.low_pass_filter(frequency=2000, Q=1.25)
effect.play(synth)
audio.play(effect)

note = synthio.Note(261)
while True:
    synth.press(note)
    time.sleep(0.25)
    synth.release(note)
    time.sleep(5)
deinit() → None

Deinitialises the Filter.

__enter__() → Filter

No-op used by Context Managers.

__exit__() → None

Automatically deinitializes when exiting a context. See Lifetime and ContextManagers for more info.

filter: synthio.Biquad | Tuple[synthio.Biquad] | None

A normalized biquad filter object or tuple of normalized biquad filter objects. The sample is processed sequentially by each filter to produce the output samples.

mix: synthio.BlockInput

The rate the filtered signal mix between 0 and 1 where 0 is only sample and 1 is all effect.

playing: bool

True when the effect is playing a sample. (read-only)

play(sample: circuitpython_typing.AudioSample, *, loop: bool = False) → Filter

Plays the sample once when loop=False and continuously when loop=True. Does not block. Use playing to block.

The sample must match the encoding settings given in the constructor.

Returns:

The effect object itself. Can be used for chaining, ie: audio.play(effect.play(sample)).

Return type:

Filter

stop() → None

Stops playback of the sample.

class audiofilters.Phaser(frequency: synthio.BlockInput = 1000.0, feedback: synthio.BlockInput = 0.7, mix: synthio.BlockInput = 1.0, stages: int = 6, buffer_size: int = 512, sample_rate: int = 8000, bits_per_sample: int = 16, samples_signed: bool = True, channel_count: int = 1)

A Phaser effect

Create a Phaser effect where the original sample is processed through a variable

number of all-pass filter stages. This slightly delays the signal so that it is out of phase with the original signal. When the amount of phase is modulated and mixed back into the original signal with the mix parameter, it creates a distinctive phasing sound.

Parameters:

  • frequency (synthio.BlockInput) – The target frequency which is affected by the effect in hz.

  • stages (int) – The number of all-pass filters which will be applied to the signal.

  • feedback (synthio.BlockInput) – The amount that the previous output of the filters is mixed back into their input along with the unprocessed signal.

  • mix (synthio.BlockInput) – The mix as a ratio of the sample (0.0) to the effect (1.0).

  • buffer_size (int) – The total size in bytes of each of the two playback buffers to use

  • sample_rate (int) – The sample rate to be used

  • channel_count (int) – The number of channels the source samples contain. 1 = mono; 2 = stereo.

  • bits_per_sample (int) – The bits per sample of the effect

  • samples_signed (bool) – Effect is signed (True) or unsigned (False)

Playing adding a phaser to a synth:

import time
import board
import audiobusio
import audiofilters
import synthio

audio = audiobusio.I2SOut(bit_clock=board.GP20, word_select=board.GP21, data=board.GP22)
synth = synthio.Synthesizer(channel_count=1, sample_rate=44100)
effect = audiofilters.Phaser(channel_count=1, sample_rate=44100)
effect.frequency = synthio.LFO(offset=1000.0, scale=600.0, rate=0.5)
effect.play(synth)
audio.play(effect)

synth.press(48)
deinit() → None

Deinitialises the Phaser.

__enter__() → Phaser

No-op used by Context Managers.

__exit__() → None

Automatically deinitializes when exiting a context. See Lifetime and ContextManagers for more info.

frequency: synthio.BlockInput

The target frequency in hertz at which the phaser is delaying the signal.

feedback: synthio.BlockInput

The amount of which the incoming signal is fed back into the phasing filters from 0.1 to 0.9.

mix: synthio.BlockInput

The amount that the effect signal is mixed into the output between 0 and 1 where 0 is only the original sample and 1 is all effect.

stages: int

The number of allpass filters to pass the signal through. More stages requires more processing but produces a more pronounced effect. Requires a minimum value of 1.

playing: bool

True when the effect is playing a sample. (read-only)

play(sample: circuitpython_typing.AudioSample, *, loop: bool = False) → Phaser

Plays the sample once when loop=False and continuously when loop=True. Does not block. Use playing to block.

The sample must match the encoding settings given in the constructor.

Returns:

The effect object itself. Can be used for chaining, ie: audio.play(effect.play(sample)).

Return type:

Phaser

stop() → None

Stops playback of the sample.