Filters and effects

What the added filters and effects take and return. For a task-shaped introduction to the biquad, see Filter a sound. The reasons these exist beside CircuitPython’s own modules are in Additions beyond CircuitPython.

A level moved on a playing node walks to its new value in a straight line over 20 ms instead of stepping, so turning it in one call doesn’t click: the mix of Biquad, AllPass, Waveshaper, FeedbackDelay, audioverb.Tank and audiomath.Multiply, the Waveshaper’s post_gain and the Dynamics node’s makeup_db. A node that hasn’t played yet, or has just been reset, takes its levels at once. audiodelays.Flanger walks its mix the same way once you set its mix_ramp to a number of frames; it is 0 by default, as in CircuitPython.

audiobiquad

What the two kinds of node take, side by side:

Biquad

AllPass

constructor

mode, frequency, Q, gain_db, mix, sample_rate, channel_count

stages, frequency, feedback, mix, sample_rate, channel_count

block inputs

frequency, Q, gain_db, mix

frequency, feedback, mix

fixed at construction

sample_rate, channel_count

those, plus stages (it sizes the state)

methods

play, stop, clear

play, stop, clear

read-only

playing, coefficients

playing, stages, coefficient

latency

0 samples

0 samples

Generated from audiobiquad.pyi; the file reads on its own.

Biquad and all-pass filters whose tails reach exact zero.

Biquad is one filter section in any of seven modes, and AllPass is a cascade of first-order all-pass stages, which is what a phaser is made of. Both keep their state in floating point, so a ringing tail decays to exactly zero instead of sitting at one least-significant bit. Q is bounded to 0.05 to 60 and feedback to plus or minus 0.99: a pole on the unit circle is a filter that never stops ringing, which is the one thing this module exists to avoid.

This module is named apart from CircuitPython’s audiofilters on purpose. It is not an extension of audiofilters.Filter or audiofilters.Phaser but a second set of kernels, so the ported modules stay the same as the ones on a stock board. For a task-shaped introduction, see “Filter a sound”.

Both nodes hand out 256 frames at a time (or fewer, with buffer_size), sit in an audio chain like any other effect, add no latency, and never report themselves finished: a chain with nothing left to read gets silence.

A level moved on a playing node walks to its new value in a straight line over 20 ms instead of stepping, so turning mix in one call does not click. A node that has not played yet, or has just been reset, takes its levels at once.

audiobiquad.LOW_PASS

pass what is below frequency. This is 0.

Type:

A Biquad mode

audiobiquad.HIGH_PASS

pass what is above frequency. This is 1.

Type:

A Biquad mode

audiobiquad.BAND_PASS

pass a band around frequency. This is 2.

Type:

A Biquad mode

audiobiquad.NOTCH

remove a band around frequency. This is 3.

Type:

A Biquad mode

audiobiquad.PEAKING_EQ

boost or cut a band around frequency by gain_db. This is 4.

Type:

A Biquad mode

audiobiquad.LOW_SHELF

boost or cut everything below frequency by gain_db. This is 5.

Type:

A Biquad mode

audiobiquad.HIGH_SHELF

boost or cut everything above frequency by gain_db. This is 6.

Type:

A Biquad mode

audiobiquad.MODES

The seven mode numbers, LOW_PASS to HIGH_SHELF, in order. They are numbered exactly as synthio.FilterMode numbers its modes, so either can be handed to either.

audiobiquad.FRAMES
Type:

Frames in one block when buffer_size is not given

audiobiquad.MAX_STAGES
Type:

The most stages an AllPass can have

class audiobiquad.Biquad(*, mode=0, frequency=1000, Q=None, gain_db=0, mix=1, sample_rate=48000, channel_count=2, buffer_size=None)[source]

Bases: object

One filter section.

Every argument is a keyword. frequency, Q, gain_db and mix are block inputs: a number, or a synthio.LFO or synthio.Math that is read once a block, so an LFO on frequency arrives about a block late.

When frequency, Q, gain_db or mode changes while the filter plays, it glides to the new filter over about 20 ms instead of jumping, so a preset change that drops the corner from 20 kHz to 20 Hz does not thump. A filter that has not played yet takes its new settings at once.

Parameters:
  • mode – One of LOW_PASS, HIGH_PASS, BAND_PASS, NOTCH, PEAKING_EQ, LOW_SHELF and HIGH_SHELF. The default is LOW_PASS.

  • frequency – The corner or centre in Hz. The default is 1000.

  • Q – The resonance, bounded to 0.05 to 60. The default, None, is 0.7071 (Butterworth), and reads back as that number.

  • gain_db – The boost or cut in dB, for PEAKING_EQ, LOW_SHELF and HIGH_SHELF. The default is 0.

  • mix – A crossfade: 0 is a wire, 1 is the filtered signal alone. The default is 1.

  • sample_rate – Frames per second. The default is 48000.

  • channel_count – 1 or 2. The default is 2.

  • buffer_size – Bytes in each block, a whole number of frames from one to 256. The default, None, is 256 frames.

Raises:

ValueError – mode is not one of the seven, channel_count is not 1 or 2, sample_rate is below 1, or buffer_size is not whole frames from one to 256.

mode

The filter’s mode. Setting it raises ValueError for a number that is not one of the seven.

frequency

The corner or centre in Hz.

Q

The resonance, bounded to 0.05 to 60.

gain_db

The boost or cut in dB.

mix

The crossfade from the dry signal (0) to the filtered one (1).

sample_rate

Frames per second. Writable, to 1 or more.

property bits_per_sample

Size of one sample in bits: always 16.

property channel_count

Number of channels: 1 or 2.

property playing

Whether a source is set with play.

property coefficients

The filter’s (b0, b1, b2, a1, a2), normalised, at the settings in force. Reading it does not advance an LFO on a block input.

play(source, /)[source]

Set the stream to filter, replacing the last one.

stop()[source]

Forget the source. The node then hands out silence.

clear()[source]

Empty the filter’s memory, which stops a ringing tail.

deinit()[source]

Release the node. Later calls other than deinit raise ValueError.

class audiobiquad.AllPass(*, stages=4, frequency=1000, feedback=0, mix=1, sample_rate=48000, channel_count=2, buffer_size=None)[source]

Bases: object

A cascade of first-order all-pass stages.

frequency really is the frequency at which one stage’s phase passes minus 90 degrees, so nothing has to be pre-warped. With mix at 0.5 the cascade sums with the dry signal into the notches a script phaser makes, and that is where they are deepest.

Every argument is a keyword. frequency, feedback and mix are block inputs, as for Biquad. stages sizes the node’s state, so it can only be given here.

Parameters:
  • stages – How many stages, 1 to MAX_STAGES. The default is 4.

  • frequency – The frequency in Hz at which one stage reaches minus 90 degrees. The default is 1000.

  • feedback – Output fed back to the input, bounded to plus or minus 0.99. The default is 0.

  • mix – A crossfade: 0 is a wire, 1 is the all-pass cascade alone. The default is 1.

  • sample_rate – Frames per second. The default is 48000.

  • channel_count – 1 or 2. The default is 2.

  • buffer_size – Bytes in each block, as for Biquad.

Raises:

ValueError – stages is out of range, channel_count is not 1 or 2, sample_rate is below 1, or buffer_size is not whole frames from one to 256.

frequency

The frequency in Hz at which one stage’s phase passes minus 90 degrees.

feedback

Output fed back to the input, bounded to plus or minus 0.99.

mix

The crossfade from the dry signal (0) to the cascade (1).

sample_rate

Frames per second. Writable, to 1 or more.

property bits_per_sample

Size of one sample in bits: always 16.

property channel_count

Number of channels: 1 or 2.

property playing

Whether a source is set with play.

property stages

How many stages the cascade has.

property coefficient

The coefficient of each stage at the settings in force. Reading it does not advance an LFO on a block input.

play(source, /)[source]

Set the stream to filter, replacing the last one.

stop()[source]

Forget the source. The node then hands out silence.

clear()[source]

Empty the filter’s memory, which stops a ringing tail.

deinit()[source]

Release the node. Later calls other than deinit raise ValueError.

audiodynamics

Generated from audiodynamics.pyi; the file reads on its own.

Compression, limiting, expansion, gating and transient shaping.

Dynamics is one node that does the job of a compressor, a limiter, an expander, a gate or a transient shaper, chosen by its mode. Hand it an audio source with play, and the result is another audio source. Its detector can run on the signal itself or on a separate key signal given to key, which is how a sidechain compressor is made.

Beyond the usual settings it has a number of options, every one of them off by default, so a node that sets none of them does what a plain compressor does: an RMS detector, a feedback detector and an external key input with Key Listen, a 4x true-peak reconstruction, a two-pole key band with both corners settable, a settable expander and gate depth, a four-stage gate envelope with hold and hysteresis, a relative-threshold gain computer, a program-dependent attack, and the transient shaper’s four detector time constants, a second envelope pair and a hold on the slow one.

A level moved on a playing node walks to its new value over 20 ms instead of stepping, so turning makeup_db in one call does not click. Every option changes together or not at all, so a bad keyword leaves the node as it was.

The node takes and gives 16-bit audio in blocks of 256 frames, with 1 or 2 channels, and never reports itself finished: a chain with nothing left to read gets silence.

audiodynamics.DYN_COMPRESS

turn down what is above the threshold, by ratio. This is 0.

Type:

A mode

audiodynamics.DYN_LIMIT

stop the level at the threshold. This is 1.

Type:

A mode

audiodynamics.DYN_EXPAND

turn down what is below the threshold, by ratio. This is 2.

Type:

A mode

audiodynamics.DYN_GATE

shut off what is below the threshold. This is 3.

Type:

A mode

audiodynamics.DYN_TRANSIENT

reshape the start and the body of notes, by attack_gain_db and sustain_gain_db. This is 4.

Type:

A mode

class audiodynamics.Dynamics(mode=0, *, sample_rate=48000, channel_count=2, threshold_db=Ellipsis, ratio=Ellipsis, knee_db=Ellipsis, makeup_db=Ellipsis, attack_ms=Ellipsis, release_ms=Ellipsis, attack_gain_db=Ellipsis, sustain_gain_db=Ellipsis, sidechain_hz=Ellipsis, lookahead_ms=Ellipsis, true_peak=Ellipsis, transient_fast_attack_ms=Ellipsis, transient_fast_release_ms=Ellipsis, transient_slow_attack_ms=Ellipsis, transient_slow_release_ms=Ellipsis, detector=Ellipsis, rms_ms=Ellipsis, feedback_detector=Ellipsis, sidechain_lp_hz=Ellipsis, sidechain_poles=Ellipsis, key_listen=Ellipsis, depth_db=Ellipsis, hold_ms=Ellipsis, hysteresis_db=Ellipsis, relative_threshold=Ellipsis, program_attack=Ellipsis, transient_dual=Ellipsis, sustain_fast_attack_ms=Ellipsis, sustain_fast_release_ms=Ellipsis, sustain_slow_attack_ms=Ellipsis, sustain_slow_release_ms=Ellipsis, slow_hold_ms=Ellipsis, gain_smooth_ms=Ellipsis, feedback_gain_corrected=Ellipsis)[source]

Bases: object

A compressor, limiter, expander, gate or transient shaper.

The mode is the one positional argument; everything else is a keyword.

Parameters:
  • mode – One of DYN_COMPRESS, DYN_LIMIT, DYN_EXPAND, DYN_GATE and DYN_TRANSIENT. The default is DYN_COMPRESS.

  • sample_rate – Frames per second. The default is 48000.

  • channel_count – 1 or 2. The default is 2.

  • threshold_db – The level in dB where the effect starts, for every mode. The default is -24.

  • ratio – The compression or expansion ratio, 1 or more (lower values are 1). The default is 4.

  • knee_db – The width of the soft knee around the threshold, in dB, 0 or more. The default is 6.

  • makeup_db – Gain added after the effect, in dB. A change walks to its new value over 20 ms. The default is 0.

  • attack_ms – How fast the detector follows a rise, in milliseconds. The default is 10.

  • release_ms – How fast the detector follows a fall, in milliseconds. The default is 120.

  • attack_gain_db – DYN_TRANSIENT only: the gain in dB for the start of a note. The default is 0.

  • sustain_gain_db – DYN_TRANSIENT only: the gain in dB for the body of a note. The default is 0.

  • sidechain_hz – A high-pass corner in Hz on the signal the detector hears, so low notes do not pump the gain. 0 or less is off, the default.

  • lookahead_ms – How far ahead of the output the detector looks, in milliseconds, 0 to 50. It adds that much latency. The default is 0.

  • true_peak – How the detector finds peaks between samples. 0 or False reads the samples; 1 or True estimates the peak with a half-band filter; 2 or more reconstructs it at four times the rate. The default is 0.

  • transient_fast_attack_ms – DYN_TRANSIENT: the fast envelope’s attack time, in milliseconds. The default is 1.

  • transient_fast_release_ms – DYN_TRANSIENT: the fast envelope’s release time, in milliseconds. The default is 50.

  • transient_slow_attack_ms – DYN_TRANSIENT: the slow envelope’s attack time, in milliseconds. The default is 25.

  • transient_slow_release_ms – DYN_TRANSIENT: the slow envelope’s release time, in milliseconds. The default is 300.

  • detector – What the detector measures: 'peak' or 'rms', or 0 or 1 for the same. The default is 'peak'.

  • rms_ms – The averaging window of the RMS detector, in milliseconds. The default is 10.

  • feedback_detector – Have the detector read the previous output frame instead of the input, the feedback arrangement of classic hardware compressors. The default is off.

  • sidechain_lp_hz – A low-pass corner in Hz on the signal the detector hears, which with sidechain_hz makes a band. 0 or less is off, the default.

  • sidechain_poles – How steep the key band’s filters are: 1 pole (6 dB an octave) or 2 (12). The default is 1.

  • key_listen – Put the detector’s signal on the output instead of the audio, as a gate’s Key Listen switch does. The default is off.

  • depth_db – The floor DYN_EXPAND and DYN_GATE pull the level down to, in dB, zero or below. A positive value, the default, leaves it unset: -60 dB for the expander and -80 dB for the gate.

  • hold_ms – DYN_GATE: how long the gate holds open after the level falls below the threshold, in milliseconds, which makes the gate’s envelope four-stage. 0 is no hold, the default.

  • hysteresis_db – DYN_GATE: the gap in dB between the level that opens the gate and the one that closes it. The default is 0.

  • relative_threshold – Drive the gain computer by the key band’s level minus the full-band level, so a fixed spectral balance gets the same reduction wherever it sits in the level range. The default is off.

  • program_attack – Scale the attack by how far the level overshoots the envelope, so a bigger overshoot is caught faster. The default is off.

  • transient_dual – DYN_TRANSIENT: apply the attack and sustain gains together, the sustain section reading its own, slower pair of envelopes. The default is off.

  • sustain_fast_attack_ms – DYN_TRANSIENT, with transient_dual: the sustain section’s fast attack, in milliseconds. The default is 1.

  • sustain_fast_release_ms – DYN_TRANSIENT, with transient_dual: the sustain section’s fast release, in milliseconds. The default is 200.

  • sustain_slow_attack_ms – DYN_TRANSIENT, with transient_dual: the sustain section’s slow attack, in milliseconds. The default is 25.

  • sustain_slow_release_ms – DYN_TRANSIENT, with transient_dual: the sustain section’s slow release, in milliseconds. The default is 1200.

  • slow_hold_ms – DYN_TRANSIENT: how long the slow envelope holds its peak before it releases, in milliseconds. 0 is no hold, the default.

  • gain_smooth_ms – Smooth the computed gain with a one-pole filter of this time, in milliseconds. 0 or less is off, the default.

  • feedback_gain_corrected – With feedback_detector in DYN_COMPRESS, make the loop land on the ratio you asked for. Off, the loop reduces its own input and settles near 2:1 whatever the ratio. The default is off.

Raises:
  • ValueError – channel_count is not 1 or 2, or detector is not 'peak' or 'rms'.

  • TypeError – An unknown option was given.

sample_rate

Frames per second. Writable, to 1 or more.

property bits_per_sample

Size of one sample in bits: always 16.

property channel_count

Number of channels: 1 or 2.

play(source, /)[source]

Set the stream to process, replacing the last one.

key(source, /)[source]

Set the key signal the detector listens to instead of the stream itself, or None to go back to the stream. The key has to match the stream’s channel count.

set(*, sample_rate=Ellipsis, channel_count=Ellipsis, threshold_db=Ellipsis, ratio=Ellipsis, knee_db=Ellipsis, makeup_db=Ellipsis, attack_ms=Ellipsis, release_ms=Ellipsis, attack_gain_db=Ellipsis, sustain_gain_db=Ellipsis, sidechain_hz=Ellipsis, lookahead_ms=Ellipsis, true_peak=Ellipsis, transient_fast_attack_ms=Ellipsis, transient_fast_release_ms=Ellipsis, transient_slow_attack_ms=Ellipsis, transient_slow_release_ms=Ellipsis, detector=Ellipsis, rms_ms=Ellipsis, feedback_detector=Ellipsis, sidechain_lp_hz=Ellipsis, sidechain_poles=Ellipsis, key_listen=Ellipsis, depth_db=Ellipsis, hold_ms=Ellipsis, hysteresis_db=Ellipsis, relative_threshold=Ellipsis, program_attack=Ellipsis, transient_dual=Ellipsis, sustain_fast_attack_ms=Ellipsis, sustain_fast_release_ms=Ellipsis, sustain_slow_attack_ms=Ellipsis, sustain_slow_release_ms=Ellipsis, slow_hold_ms=Ellipsis, gain_smooth_ms=Ellipsis, feedback_gain_corrected=Ellipsis)[source]

Change options while the node plays.

Takes the same options as the constructor. All of them change together or not at all, and a change to lookahead_ms or channel_count allocates what it needs before anything changes.

Raises:
gain_reduction_db()[source]

How much the node is turning the level down now, in dB, for a meter.

deinit()[source]

Release the node. Later calls other than deinit raise ValueError.

audioecho

Generated from audioecho.pyi; the file reads on its own.

A delay with a filter, a soft-clip and a cross-feed in its feedback loop.

FeedbackDelay is a delay line with the things a tape or bucket-brigade echo has in its loop: a low-pass that darkens each repeat, a high-pass that thins it, a soft-clip, a cross-feed that ping-pongs the repeats between channels, and a slow wobble in the delay time (“wow”) applied per sample, so it bends pitch the way tape does instead of stepping once a block. It is named apart from __future__ import annotations from audiodelays on purpose: that module is CircuitPython’s own, and the additions here would not exist on a stock board.

Four options go further, each off by default. wow_shape swaps the built-in modulation sine for one period of your own, because a bucket brigade’s delay is its line length over its clock, so a triangle on the clock is a reciprocal on the delay, and no sine is that. delay_slew walks the read head to a new delay_ms at a constant rate instead of jumping to it, which is both an Echoplex’s varispeed and the reason a delay-time knob can be turned mid-take without a click. wow_am_depth puts the same oscillator on the wet gain, dipping only. loop_semitones pitch-shifts the line read inside the loop, so every repeat rises again: a shimmer, which chaining audiodelays.PitchShift after a delay is not. Shifting up, the climb fades out at the top of the band rather than folding back past Nyquist.

The node is one 256-frame block at a time, 16-bit audio, 1 or 2 channels. A level moved on a playing node, such as mix, walks to its new value over 20 ms instead of stepping. Latency from dry to wet is the delay itself. When the source ends the tail rings out on silence until it reaches exactly zero, and the node rests, so a source played into it afterwards meets an empty line; audiomodal.Bank, audioverb.Tank and audioconvolve.Convolver do the same.

class audioecho.FeedbackDelay(*, sample_rate=48000, max_delay_ms=250, channel_count=2, delay_ms=Ellipsis, delay_frames=Ellipsis, feedback=0.4, mix=0.3, damping_hz=0.0, cut_hz=0.0, wow_hz=0.0, wow_depth_ms=0.0, wow_depth_ramp_ms=20.0, wow_shape=None, wow_am_depth=0.0, cross_feed=0.0, loop_drive=0.0, input_pan=0.0, delay_slew=0.0, loop_semitones=0.0, loop_window_ms=25.0)[source]

Bases: object

A delay with a processed feedback loop.

Every argument is a keyword. sample_rate, max_delay_ms and channel_count size the delay line and the audio, so they can only be given here; every other option can be changed with set. A keyword that is not one of these raises TypeError.

Parameters:
  • sample_rate – Frames per second. The default is 48000.

  • max_delay_ms – The longest delay in milliseconds, above 0. It sizes the line. The default is 250.

  • channel_count – 1 or 2. The default is 2.

  • delay_ms – The delay in milliseconds, clamped to the line. The default is half of max_delay_ms. Give this or delay_frames, not both.

  • delay_frames – The delay in frames, read exactly that many frames back. At 44.1 and 22.05 kHz some whole frames have no delay_ms that lands on them, so a lossless repeat at those rates needs this.

  • feedback – How much of each repeat feeds back, 0.0 to 0.99 (clamped). The default is 0.4.

  • mix – The wet level, 0.0 to 2.0, clamped. The dry stays at unity until 1.0, as for audiodelays.Echo, so 0.3 is the dry plus 30 percent wet and 2.0 is the wet alone. The default is 0.3.

  • damping_hz – A low-pass in the loop at this corner, in Hz, that darkens each repeat. 0 takes the filter out, the default.

  • cut_hz – A high-pass in the loop at this corner, in Hz, that thins each repeat. 0 takes the filter out, the default.

  • wow_hz – The rate of the delay-time wobble, in Hz. 0 is none, the default.

  • wow_depth_ms – How far the wobble moves the delay, 0 to 1000 milliseconds. A change ramps over wow_depth_ramp_ms. The default is 0.

  • wow_depth_ramp_ms – How long a change of wow_depth_ms takes to land, 0 to 60000 milliseconds. The default is 20.

  • wow_shape – One period of the wobble as int16 Q15 samples, a power-of-two count from 2 to 4096, or None for the built-in sine. The default is None.

  • wow_am_depth – How far the wobble also dips the wet gain, 0.0 to 1.0. It never boosts. The default is 0.

  • cross_feed – How much of each repeat goes to the other channel, 0.0 to 1.0. The default is 0.

  • loop_drive – The soft-clip in the loop, 0.0 to 1.0. The default is 0.

  • input_pan – Where the input goes: -1.0 sends both channels into the left line, 1.0 into the right, 0.0 leaves each on its own. Hard over sends the average of the two channels. With cross_feed it makes a ping-pong. The default is 0.

  • delay_slew – How fast the read head walks to a new delay_ms, in seconds of delay per second, 0 to 64. 0 jumps, the default.

  • loop_semitones – How far each pass through the loop shifts the pitch, -24 to 24 semitones, clamped. 0 is off, the default.

  • loop_window_ms – The crossfade window of the loop’s pitch shifter, 1 to 250 milliseconds, clamped. The default is 25.

Raises:
  • ValueError – max_delay_ms is not above 0, channel_count is not 1 or 2, or wow_shape is not a power-of-two count from 2 to 4096 int16 samples.

  • TypeError – An unknown option was given, or both delay_ms and delay_frames.

sample_rate

Frames per second. Writable, to 1 or more.

property bits_per_sample

Size of one sample in bits: always 16.

property channel_count

Number of channels: 1 or 2.

play(source, /)[source]

Set the stream to delay, replacing the last one.

set(*, delay_ms=Ellipsis, delay_frames=Ellipsis, feedback=Ellipsis, mix=Ellipsis, damping_hz=Ellipsis, cut_hz=Ellipsis, wow_hz=Ellipsis, wow_depth_ms=Ellipsis, wow_depth_ramp_ms=Ellipsis, wow_shape=Ellipsis, wow_am_depth=Ellipsis, cross_feed=Ellipsis, loop_drive=Ellipsis, input_pan=Ellipsis, delay_slew=Ellipsis, loop_semitones=Ellipsis, loop_window_ms=Ellipsis)[source]

Change options while the node plays, with the meanings and ranges of the constructor’s. All of them change together or not at all, so a bad keyword leaves the node as it was.

Raises:
  • ValueError – wow_shape is not a power-of-two count from 2 to 4096 int16 samples.

  • TypeError – An unknown option was given, or both delay_ms and delay_frames. sample_rate, max_delay_ms and channel_count are ignored here, not applied.

clear()[source]

Empty the line and every filter, which stops a ringing tail.

deinit()[source]

Release the node. Later calls other than deinit raise ValueError.

audioshaper

Generated from audioshaper.pyi; the file reads on its own.

A waveshaper whose curve is data, and an exact-ratio sample-and-hold.

Waveshaper pushes audio through a transfer curve you supply, between a pair of oversampling stages, because a nonlinearity at the base rate folds the harmonics it makes above Nyquist straight back onto the signal. SampleHold is the other half of a lo-fi effect: the waveshaper quantises the value, the hold quantises the time.

class audioshaper.Waveshaper(*, curve, sample_rate=48000, channel_count=2, oversample=4, pre_gain=1.0, bias=0.0, post_gain=1.0, mix=1.0, hysteresis=0.0, hysteresis_width=0.02, hysteresis_bias=0.0)[source]

Bases: object

A waveshaper with oversampling, played like any audio sample.

The shaping happens at oversample times the sample rate, between a matched pair of polyphase all-pass half-bands. It hands out 256 frames at a time and renders 16-bit audio. Every option is a keyword. curve, sample_rate, channel_count and oversample are fixed when the node is made, except that set can replace the curve. The rest can be given here or to set.

curve is signed 16-bit samples (Q15) of at least two points, spanning -1 to +1 of input. Compute it once on a desktop and ship it as data; never rebuild it on a board, whose float is single precision where the desktop’s is double. The node copies it.

A curve that reaches the rails has a ceiling of its own, because the decimator can ring past the rails on a hard edge. Keep post_gain * max(abs(curve)) at or below about 0.74 and put the rest of the level you want on a mixer voice after this node.

The mix and post_gain of a playing node walk to a new value in a straight line over 20 ms instead of stepping, so turning one in a single call does not click. A node that has not played yet, or has just been cleared, takes them at once.

Parameters:
  • curve – The transfer curve: a buffer of signed 16-bit values, at least two points. Required.

  • sample_rate – Frames per second. The default is 48000.

  • channel_count – 1 or 2. The default is 2.

  • oversample – 1, 2, 4 or 8. The default is 4. The oversampling adds a group delay of about 0, 2.2, 3.3 and 3.9 base-rate samples for those factors, for a component that has to report its latency.

  • pre_gain – The drive knob: a gain into the normalised curve, -1000 to 1000, clamped. The default is 1.

  • bias – Moves the operating point, -1.0 to 1.0, clamped. The default is 0.

  • post_gain – A gain after the curve, -1000 to 1000, clamped. The default is 1.

  • mix – A crossfade, 0.0 to 1.0, clamped. 0 is the dry signal and 1 the shaped one. The default is 1.

  • hysteresis – How much memory the curve has, 0.0 to 1.0, clamped. At 0, the default, there is none. Above 0 a slow signal in and out traces two paths and encloses an area.

  • hysteresis_width – The half-width of that loop as a fraction of full scale at the input, 0.0 to 0.5, clamped. The default is 0.02.

  • hysteresis_bias – How the width is split between the rising and falling branches, -1.0 to 1.0, clamped. The default is 0.

Raises:
  • ValueError – curve is missing, shorter than two points or not a whole number of 16-bit values; channel_count is not 1 or 2; or oversample is not 1, 2, 4 or 8.

  • TypeError – An unknown option was given.

  • MemoryError – The curve does not fit.

sample_rate

Frames per second. Writable, to 1 or more.

property bits_per_sample

Size of one sample in bits: always 16.

property channel_count

Number of channels: 1 or 2.

play(source, /)[source]

Set the stream to shape, replacing the last one.

set(*, curve=Ellipsis, pre_gain=Ellipsis, bias=Ellipsis, post_gain=Ellipsis, mix=Ellipsis, hysteresis=Ellipsis, hysteresis_width=Ellipsis, hysteresis_bias=Ellipsis)[source]

Change options while the node plays. All the options given change together or not at all. sample_rate, channel_count and oversample are accepted and ignored, because they are fixed when the node is made.

Parameters:
  • curve – A new transfer curve, as for the constructor.

  • pre_gain – As for the constructor.

  • bias – As for the constructor.

  • post_gain – As for the constructor.

  • mix – As for the constructor.

  • hysteresis – As for the constructor.

  • hysteresis_width – As for the constructor.

  • hysteresis_bias – As for the constructor.

Raises:
  • ValueError – curve is shorter than two points or not a whole number of 16-bit values.

  • TypeError – An unknown option was given.

clear()[source]

Empty the oversampling stages and put the hysteresis memory back to the start.

recentre()[source]

Settle the node on its operating point after silence.

Once every channel’s input has been exactly zero for a whole block, this puts the hysteresis memory where a silent input would hold it, and moves the decimator’s memories to match, so the output steps to the curve’s answer at the operating point at once instead of ringing down from the old position. Under signal it does nothing.

Returns:

True if it moved anything, False under signal.

deinit()[source]

Release the node and let go of its source. Every later use raises ValueError.

class audioshaper.SampleHold(source, num=1, den=1)[source]

Bases: object

A zero-order hold in which num source frames carry den new values.

So 26040 Hz at 48 kHz is 400 over 217, and it is exact: one frame in, one frame out, at the source’s own rate, channels and bit depth, with an integer accumulator that cannot drift however long the render runs. When num equals den the node is a wire, byte for byte. Its latency is 0: what a hold displaces is an event landing on a frame it drops, up to ceil(num / den) - 1 frames, which is the effect and for the caller to report.

It reads mono or stereo audio of 8 or 16 bits.

Parameters:
  • source – The audio to hold.

  • num – Source frames in the ratio, 1 or more.

  • den – New values in the ratio, 1 or more and no more than num, because a hold cannot invent frames. num can be up to 2**30.

Raises:
  • ValueError – The ratio is not whole numbers with den <= num, or the source is not 1 or 2 channels of 8 or 16 bits.

  • TypeError – source is not an audio source.

sample_rate

Frames per second, the source’s to begin with. Writable, to 1 or more.

property bits_per_sample

Size of one sample in bits, the source’s.

property channel_count

Number of channels, the source’s.

property num

Source frames in the ratio.

property den

New values in the ratio.

property latency

Frames of delay the node adds: always 0.

play(source, /)[source]

Hold a new source, and start the hold over.

Raises:

ValueError – The source’s bit depth or channel count is not the one this node was made with.

set(num, den)[source]

Move the ratio while the node plays, as for the constructor.

Raises:

ValueError – The ratio is not whole numbers with den <= num.

clear()[source]

Start the hold over.

deinit()[source]

Release the node and let go of its source. Every later use raises ValueError.

audioladder

Generated from audioladder.pyi; the file reads on its own.

A transistor ladder filter.

Ladder is a low-pass filter that behaves like the circuit. audiofilters.Filter is a better resonant low-pass than this one: a cascade of biquads tracks the analytic response to a fraction of a decibel. It is also linear, so it never sustains a tone of its own, has no harmonics to speak of and sounds the same however hard you hit it. A ladder does those three things, and that is what this module is for.

import audioladder

ladder = audioladder.Ladder(
    sample_rate=48000,      # and channel_count=1 or 2
    cutoff_hz=800.0,        # where the filter turns over
    resonance=3.6,          # 0 to 4.2; at 4 it sustains a tone at the cutoff
    drive=2.5,              # linear gain into the loop, 1 being unity
    poles=4,                # tap stage 1 to 4: 6, 12, 18 or 24 dB an octave
    passband_comp=0.0,      # 0 to 1, how much of the passband to give back
    oversample=2,           # 1 or 2; 2 folds back fewer of its harmonics
    mix=1.0,                # 0 a wire, 1 the filter
    cutoff_octaves=10.0,    # octaves for a full-scale cutoff input
)
ladder.play(source)
ladder.set(cutoff_hz=1200.0)   # any option, mid-stream, once a block
ladder.modulate(cutoff=lfo)    # the cutoff read from a stream, every sample
ladder.clear()                 # empty the integrators; stops a sustained tone
class audioladder.Ladder(*, sample_rate=48000, channel_count=2, buffer_size=None, cutoff_hz=1000.0, resonance=0.0, drive=1.0, poles=4, passband_comp=0.0, oversample=2, mix=1.0, cutoff_octaves=10.0, ramp_ms=0.0, cutoff=None)[source]

Bases: object

A four-pole transistor ladder low-pass filter, played like any audio sample.

It hands out 256 frames at a time, or fewer with buffer_size, and renders 16-bit audio. Every option is a keyword. sample_rate, channel_count and buffer_size can only be given here; the rest can be given here or to set.

Parameters:
  • sample_rate – Frames per second, 1 or more. The default is 48000.

  • channel_count – 1 or 2. The default is 2.

  • buffer_size – Bytes in each block, a whole number of frames from one frame to 256. None, the default, is 256 frames.

  • cutoff_hz – Where the filter turns over, in Hz. The default is 1000. It is held between 1 Hz and just under half the sample rate.

  • resonance – Feedback around the loop, 0.0 to 4.2, clamped. The default is 0. At 4 the loop sustains a tone at the cutoff; a little past it is where a ladder is usually played.

  • drive – A linear gain into the loop, 0.0 to 64.0, clamped, where 1 is unity. The default is 1.

  • poles – Which stage the output is tapped from, 1 to 4, which is 6, 12, 18 or 24 dB an octave above the cutoff. The default is 4. The feedback comes from the fourth stage at every tap.

  • passband_comp – How much of the passband the feedback takes away to give back, 0.0 to 1.0, clamped. At a resonance of 4 the whole band below the cutoff is 14 dB down; 1 gives all of it back. The default is 0, which leaves the filter as the circuit behaves.

  • oversample – 1 or 2. At 2, the default, the filter runs at twice the rate, so fewer of the harmonics it makes fold back above Nyquist.

  • mix – A crossfade, 0.0 to 1.0, clamped. 0 is a wire and 1 is the filter. This is not the 0 to 2 scale of audiodelays.Echo. The default is 1.

  • cutoff_octaves – How many octaves a full-scale modulate input moves the cutoff, of either sign. The default is 10.

  • ramp_ms – How long a change of cutoff_hz, resonance, drive, passband_comp or mix takes to arrive, 0 to 1000 ms, clamped. The cutoff walks evenly in pitch and the rest in a straight line, a step every 8 frames, so a jump does not click. A change during a walk turns from where the walk stands. The default is 0, which lands a change at the next block. poles and oversample always land at once.

  • cutoff – A stream to read the cutoff from, as for modulate.

Raises:
  • ValueError – sample_rate is less than 1, channel_count is not 1 or 2, or buffer_size is not whole frames up to 256.

  • TypeError – An unknown option was given.

sample_rate

Frames per second. Writable, to 1 or more.

property bits_per_sample

Size of one sample in bits: always 16.

property channel_count

Number of channels: 1 or 2.

play(source, /)[source]

Set the stream to filter, replacing the last one.

set(*, cutoff_hz=Ellipsis, resonance=Ellipsis, drive=Ellipsis, poles=Ellipsis, passband_comp=Ellipsis, oversample=Ellipsis, mix=Ellipsis, cutoff_octaves=Ellipsis, ramp_ms=Ellipsis)[source]

Change options while the filter plays.

The cutoff moves once a block, which is plenty for an envelope or a knob; with ramp_ms set, a move walks there over that long instead of landing at the next block. Swept by an audio-rate signal that way, it is heard as a staircase, a buzz at the block rate; use modulate for that. All the options given change together or not at all.

Parameters:
  • cutoff_hz – As for the constructor.

  • resonance – As for the constructor.

  • drive – As for the constructor.

  • poles – As for the constructor.

  • passband_comp – As for the constructor.

  • oversample – As for the constructor.

  • mix – As for the constructor.

  • cutoff_octaves – As for the constructor.

  • ramp_ms – As for the constructor.

Raises:

TypeError – An unknown option was given.

modulate(*, cutoff)[source]

Read the cutoff from a stream, every sample.

For an input at v of full scale the cutoff is cutoff_hz * 2 ** (v * cutoff_octaves), so filter FM sounds like filter FM. Only the first channel of a stereo input is read. An input of zero, or none at all, leaves the filter exactly as cutoff_hz sets it.

Parameters:

cutoff – The stream, mono or stereo, or None to disconnect it.

Raises:
  • TypeError – An input other than cutoff was named.

  • ValueError – The stream is not mono or stereo.

clear()[source]

Empty the integrators. This stops a tone the loop is sustaining.

deinit()[source]

Release the filter and let go of its source. Every later use raises ValueError.

audioverb

Generated from audioverb.pyi; the file reads on its own.

A plate reverberator whose network you hand in.

Tank is Dattorro’s plate reverberator, with the network passed in rather than compiled in. That is the difference from audiofreeverb.Freeverb, whose comb and all-pass lengths are constants.

plate = audioverb.Tank(
    sample_rate=48000, channel_count=2, max_predelay_ms=200,
    decay=0.7, diffusion=0.75, bandwidth_hz=9000, damping_hz=4500,
    mod_rate_hz=1.0, mod_depth_ms=0.27, mix=0.35)
plate.play(source)
audio_out.play(plate)
class audioverb.Tank(*, sample_rate=48000, channel_count=2, max_predelay_ms=200.0, delays=None, taps=None, decay=0.5, diffusion=0.75, damping_hz=0.0, bandwidth_hz=0.0, low_cut_hz=0.0, predelay_ms=0.0, mod_depth_ms=0.0, mod_rate_hz=0.0, drive=0.0, width=1.0, tone_db=0.0, mix=0.3)[source]

Bases: object

A plate reverberator, played like any audio sample.

Construction fixes the allocation: sample_rate, channel_count and max_predelay_ms. It also takes the network, delays and taps. set moves every other option while the node plays and without emptying the lines; giving it delays or taps cuts a new network, which does empty them. Every filter is out of the path at zero, so a Tank() given nothing else is that network with nothing added to it.

There is no latency from dry to wet. The tail reaches exact zero rather than sitting at one least significant bit, because every line write is a magnitude truncation, which is the standard cure for the limit cycles of a recirculating fixed-point network. When the source ends, the tail rings out on silence to that zero and the node rests, so a source played into it afterwards meets an empty plate. audioecho.FeedbackDelay and audioconvolve.Convolver do the same.

delays is twelve line lengths in frames: the four input diffusers, then each tank half’s modulated all-pass, delay, all-pass and delay. Each is at least 4. taps is four values per tap: the output channel (0 or 1), the line (0 to 11), the offset in frames within that line and the gain, with at most 32 taps. Both default to Dattorro’s published table, scaled from 29761 Hz to sample_rate.

Every argument is a keyword.

Parameters:
  • sample_rate – Frames per second, 1 or more. The default is 48000.

  • channel_count – 1 or 2. The default is 2.

  • max_predelay_ms – The longest pre-delay predelay_ms can ask for, in milliseconds, 0 or more. It sets how much memory the pre-delay line takes. The default is 200.

  • delays – The twelve line lengths, in frames.

  • taps – The output taps, a flat sequence of four numbers a tap.

  • decay – How much of the tail comes round again, 0.0 to 0.999, clamped. The default is 0.5.

  • diffusion – The all-pass coefficient of the diffusers, 0.0 to 0.9, clamped. The default is 0.75.

  • damping_hz – A low-pass in the tank’s loop, in Hz. 0, the default, is out of the path.

  • bandwidth_hz – A low-pass on the input, in Hz. 0, the default, is out of the path.

  • low_cut_hz – A high-pass on the input, in Hz. 0, the default, is out of the path.

  • predelay_ms – Delay before the reverb, in milliseconds, held between 0 and max_predelay_ms. The default is 0.

  • mod_depth_ms – How far the modulated all-passes move, in milliseconds, 0 to 100, clamped. The default is 0.

  • mod_rate_hz – How fast they move, 0 to 100 Hz, clamped. The default is 0.

  • drive – A saturation on the input, 0.0 to 1.0, clamped. The default is 0.

  • width – The stereo width of the wet signal, 0.0 to 2.0, clamped. The default is 1.

  • tone_db – A tilt of the wet signal, bright to dark, -24 to 24 dB, clamped: half the change up at the top and the same down at the bottom, pivoting at 1 kHz. A balance control, not a trim. The default is 0.

  • mix – How much of the reverb is added, 0.0 to 2.0, clamped. It follows audiodelays.Echo: the dry signal stays at unity until 1, and from there it fades out. The default is 0.3.

Raises:
  • ValueError – sample_rate is less than 1, channel_count is not 1 or 2, max_predelay_ms is negative, delays is not twelve lengths of at least 4 frames that fit, or taps is not whole taps naming a channel, a line and an offset that exist.

  • TypeError – An unknown option was given.

  • MemoryError – The lines do not fit.

sample_rate

Frames per second. Writable, to 1 or more.

property bits_per_sample

Size of one sample in bits: always 16.

property channel_count

Number of channels: 1 or 2.

play(source, /)[source]

Set the stream to reverberate, replacing the last one.

set(*, delays=Ellipsis, taps=Ellipsis, decay=Ellipsis, diffusion=Ellipsis, damping_hz=Ellipsis, bandwidth_hz=Ellipsis, low_cut_hz=Ellipsis, predelay_ms=Ellipsis, mod_depth_ms=Ellipsis, mod_rate_hz=Ellipsis, drive=Ellipsis, width=Ellipsis, tone_db=Ellipsis, mix=Ellipsis)[source]

Change options while the tank plays, without emptying the lines.

Giving delays or taps cuts a new network, which does empty every line and filter. All the options given change together or not at all.

Parameters:
  • delays – As for the constructor.

  • taps – As for the constructor.

  • decay – As for the constructor.

  • diffusion – As for the constructor.

  • damping_hz – As for the constructor.

  • bandwidth_hz – As for the constructor.

  • low_cut_hz – As for the constructor.

  • predelay_ms – As for the constructor.

  • mod_depth_ms – As for the constructor.

  • mod_rate_hz – As for the constructor.

  • drive – As for the constructor.

  • width – As for the constructor.

  • tone_db – As for the constructor.

  • mix – As for the constructor.

Raises:
  • TypeError – An unknown option was given, or one of sample_rate, channel_count or max_predelay_ms, which are fixed when the node is made.

  • ValueError – delays or taps are not valid, as for the constructor.

clear()[source]

Empty every line and every filter.

deinit()[source]

Release the node and let go of its source. Every later use raises ValueError.

audioroute.MidSide

Generated from audioroute.pyi; the file reads on its own.

class audioroute.MidSide(source=None, width=None, sample_rate=48000, channel_count=2)[source]

Bases: object

Scales the difference between the left and right channels.

At a width of 1.0 the output is the input exactly, so the node can stay in a chain that does not use it. A mono node copies its input, since a mono signal has no difference to scale. The node keeps no state and adds no latency.

It also suits the drive classes. A nonlinearity applied to a stereo pair intermodulates its channels, so a saturator that wants to keep its image drives the mid and leaves the side alone.

Parameters:
  • source – The stream to process, or None to set it later with play. Its channel count must match this node’s.

  • width – 0.0 collapses the signal to mono, 1.0 leaves it as it is and 2.0 doubles the difference. Values outside 0.0 to 2.0 are clamped. The default is 1.0.

  • sample_rate – Frames per second.

  • channel_count – 1 or 2.

Raises:

ValueError – channel_count is not 1 or 2, or the source’s channel count differs.

sample_rate

Frames per second. Writable, to 1 or more.

property bits_per_sample

Size of one sample in bits: always 16.

property channel_count

Number of channels: 1 or 2.

play(source, /)[source]

Replace the stream being processed.

Raises:

ValueError – The stream’s channel count differs from this node’s.

set(*, width=Ellipsis)[source]

Change an option while the node plays.

Parameters:

width – As for the constructor.

Raises:

TypeError – An option other than width was given.

deinit()[source]

Release the node and let go of its source. Every later use raises ValueError.

audiofilters

Generated from audiofilters.pyi; the file reads on its own.

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.

class audiofilters.DistortionMode[source]

Bases: object

The way Distortion shapes the signal.

CLIP

anything past full scale is cut off.

Type:

Hard clipping

LOFI

Bit reduction, which makes a gritty low-resolution sound.

OVERDRIVE

A rounded saturation that squeezes the peaks.

WAVESHAPE

A smooth curve that folds the peaks back.

class audiofilters.Filter(*, filter=None, mix=1, buffer_size=512, sample_rate=8000, bits_per_sample=16, samples_signed=True, channel_count=1)[source]

Bases: object

A chain of biquad filters.

Parameters:
  • 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.

deinit()[source]

Free the filter. Later calls other than deinit raise ValueError.

sample_rate

Frames per second. Writable, to 1 or more.

property bits_per_sample

Size of one sample in bits.

property channel_count

Number of channels: 1 or 2.

property playing

True while a source is playing through the filter.

filter

The biquad or biquads applied to the signal.

mix

How much of the filtered signal goes out, 0 to 1.

play(sample, *, loop=False)[source]

Read from a source and filter it.

Parameters:
  • sample – The audio source to filter.

  • loop – Start the source over when it ends.

stop()[source]

Stop reading the source.

class audiofilters.Phaser(*, frequency=1000, feedback=None, mix=1, stages=6, buffer_size=512, sample_rate=8000, bits_per_sample=16, samples_signed=True, channel_count=1)[source]

Bases: object

A phaser: a cascade of all-pass stages mixed with the dry signal.

Parameters:
  • 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.

deinit()[source]

Free the effect. Later calls other than deinit raise ValueError.

sample_rate

Frames per second. Writable, to 1 or more.

property bits_per_sample

Size of one sample in bits.

property channel_count

Number of channels: 1 or 2.

property playing

True while a source is playing through the effect.

frequency

The corner frequency of the all-pass stages in Hz.

feedback

How much of the output goes back into the input.

mix

How much of the processed signal goes out, 0 to 1.

stages

How many all-pass stages.

play(sample, *, loop=False)[source]

Read from a source and process it.

Parameters:
  • sample – The audio source.

  • loop – Start the source over when it ends.

stop()[source]

Stop reading the source.

class audiofilters.Distortion(*, drive=0, pre_gain=0, post_gain=0, mode=Ellipsis, soft_clip=False, mix=1, buffer_size=512, sample_rate=8000, bits_per_sample=16, samples_signed=True, channel_count=1)[source]

Bases: object

A distortion with four modes.

Parameters:
  • 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.

deinit()[source]

Free the effect. Later calls other than deinit raise ValueError.

sample_rate

Frames per second. Writable, to 1 or more.

property bits_per_sample

Size of one sample in bits.

property channel_count

Number of channels: 1 or 2.

property playing

True while a source is playing through the effect.

drive

How hard the signal is pushed, 0 to 1.

pre_gain

Gain in dB before the distortion.

post_gain

Gain in dB after the distortion.

mode

The DistortionMode in use.

soft_clip

Whether the output is softly clipped.

mix

How much of the distorted signal goes out, 0 to 1.

play(sample, *, loop=False)[source]

Read from a source and distort it.

Parameters:
  • sample – The audio source.

  • loop – Start the source over when it ends.

stop()[source]

Stop reading the source.

audiodelays

Generated from audiodelays.pyi; the file reads on its own.

Delay-based effects: echo, chorus, flanger, pitch shifters and a multi-tap delay.

These are CircuitPython’s audiodelays effects, with the same names and arguments, so code written for a CircuitPython board runs unchanged. Each one is an audio source that reads another audio source: give it a source with play, hand the effect to an output or a mixer, and it processes the audio a block at a time.

The effects take a buffer_size in bytes for each block, the sample format (sample_rate, bits_per_sample, samples_signed, channel_count) the source has to match, and then their own options. Every argument is a keyword. Options that can change while the effect plays are block inputs: a number, or a synthio.LFO or synthio.Math read once a block. A level moved on a playing node walks to its new value over 20 ms instead of stepping, so turning a knob does not click.

audioecho.FeedbackDelay is a separate delay with a filter, a soft-clip and a cross-feed in its feedback loop; reach for it when Echo is not enough.

class audiodelays.Echo(*, max_delay_ms=500, delay_ms=Ellipsis, decay=Ellipsis, filter=None, mix=Ellipsis, buffer_size=512, sample_rate=8000, bits_per_sample=16, samples_signed=True, channel_count=1, freq_shift=True)[source]

Bases: object

A single-tap echo with feedback.

The delay line repeats the source, each repeat decay times as loud as the one before. filter is applied to the signal inside the feedback loop, so each repeat is filtered again. With freq_shift on, a change to delay_ms while playing shifts the pitch of the repeats, as moving a tape head does; with it off the repeats do not shift.

Parameters:
  • max_delay_ms – The longest delay the effect can be set to, 1 to 4000. It sizes the delay line, so it can only be given here. The default is 500.

  • delay_ms – The delay in milliseconds, up to max_delay_ms. The default is 250.

  • decay – How much of each repeat feeds back, 0.0 to 1.0. The default is 0.7.

  • filter – A filter, or a sequence of them, applied inside the feedback loop, or None for none.

  • mix – The balance of the effect, 0.0 for the dry signal only, 1.0 for the echo only. The default is 0.25.

  • freq_shift – Whether a change to delay_ms shifts the pitch of the repeats. The default is True.

  • buffer_size – How many bytes the effect hands out in each block. The default is 512.

  • sample_rate – Frames per second, 1 or more. The default is 8000.

  • bits_per_sample – 8 or 16. The default is 16.

  • samples_signed – Whether samples are signed. The default is True.

  • channel_count – 1 or 2. The default is 1.

Raises:
  • ValueError – max_delay_ms is not 1 to 4000.

  • ValueError – channel_count is not 1 or 2, sample_rate is below 1, or bits_per_sample is not 8 or 16.

delay_ms

The delay in milliseconds.

decay

How much of each repeat feeds back, 0.0 to 1.0.

filter

The filter, or sequence of filters, in the feedback loop.

mix

The balance from the dry signal (0.0) to the echo (1.0).

freq_shift

Whether a change to delay_ms shifts the repeats’ pitch.

sample_rate

Frames per second. Writable, to 1 or more.

property bits_per_sample

Size of one sample in bits: 8 or 16.

property channel_count

Number of channels: 1 or 2.

property playing

Whether a source is playing.

play(sample, *, loop=False)[source]

Start reading a source.

Parameters:
  • sample – The audio to process. Its sample format has to match the effect’s.

  • loop – Whether to start the source again when it ends.

Returns:

The effect itself.

stop()[source]

Stop reading the source. The tail is not played out.

deinit()[source]

Release the effect. Later calls other than deinit raise ValueError.

class audiodelays.Chorus(*, max_delay_ms=50, delay_ms=Ellipsis, voices=Ellipsis, mix=Ellipsis, buffer_size=512, sample_rate=8000, bits_per_sample=16, samples_signed=True, channel_count=1)[source]

Bases: object

A chorus: the source mixed with slightly detuned, delayed copies of itself.

voices sets how many copies, and may be fractional, so a chorus can fade from one voice to two.

Parameters:
  • max_delay_ms – The longest delay the effect can be set to, 1 to 4000. It sizes the delay line, so it can only be given here. The default is 50.

  • delay_ms – The centre delay of the copies in milliseconds. The default is 50.

  • voices – How many copies are mixed in. The default is 1.0.

  • mix – The balance from the dry signal (0.0) to the copies only (1.0). The default is 0.5.

  • buffer_size – How many bytes the effect hands out in each block. The default is 512.

  • sample_rate – Frames per second, 1 or more. The default is 8000.

  • bits_per_sample – 8 or 16. The default is 16.

  • samples_signed – Whether samples are signed. The default is True.

  • channel_count – 1 or 2. The default is 1.

Raises:
  • ValueError – max_delay_ms is not 1 to 4000.

  • ValueError – channel_count is not 1 or 2, sample_rate is below 1, or bits_per_sample is not 8 or 16.

delay_ms

The centre delay of the copies in milliseconds.

voices

How many copies are mixed in.

mix

The balance from the dry signal (0.0) to the copies (1.0).

sample_rate

Frames per second. Writable, to 1 or more.

property bits_per_sample

Size of one sample in bits: 8 or 16.

property channel_count

Number of channels: 1 or 2.

property playing

Whether a source is playing.

play(sample, *, loop=False)[source]

Start reading a source.

Parameters:
  • sample – The audio to process. Its sample format has to match the effect’s.

  • loop – Whether to start the source again when it ends.

Returns:

The effect itself.

stop()[source]

Stop reading the source. The tail is not played out.

deinit()[source]

Release the effect. Later calls other than deinit raise ValueError.

class audiodelays.Flanger(*, max_delay_ms=10, min_delay_ms=Ellipsis, rate=Ellipsis, depth=Ellipsis, feedback=Ellipsis, mix=Ellipsis, invert=False, buffer_size=512, sample_rate=8000, bits_per_sample=16, samples_signed=True, channel_count=1)[source]

Bases: object

A flanger: a short, swept delay mixed with the source, with feedback.

A low-frequency oscillator sweeps the delay from min_delay_ms up towards max_delay_ms, by as much of the span as depth says.

Parameters:
  • max_delay_ms – The longest delay the sweep can reach, 1 to 100. It sizes the delay line, so it can only be given here. The default is 10.

  • min_delay_ms – The shortest delay of the sweep in milliseconds. The default is 1.0.

  • rate – How fast the sweep runs, in Hz. The default is 0.5.

  • depth – How much of the span between the shortest and longest delay the sweep covers. The default is 0.5.

  • feedback – How much of the delayed signal feeds back. The default is 0.5.

  • mix – The balance from the dry signal (0.0) to the delayed one (1.0). The default is 0.5.

  • invert – Whether the delayed signal is inverted, which moves the notches from the harmonics to between them. The default is False.

  • buffer_size – How many bytes the effect hands out in each block. The default is 512.

  • sample_rate – Frames per second, 1 or more. The default is 8000.

  • bits_per_sample – 8 or 16. The default is 16.

  • samples_signed – Whether samples are signed. The default is True.

  • channel_count – 1 or 2. The default is 1.

Raises:
  • ValueError – max_delay_ms is not 1 to 100.

  • ValueError – channel_count is not 1 or 2, sample_rate is below 1, or bits_per_sample is not 8 or 16.

min_delay_ms

The shortest delay of the sweep in milliseconds.

rate

How fast the sweep runs, in Hz.

depth

How much of the delay span the sweep covers.

feedback

How much of the delayed signal feeds back.

mix

The balance from the dry signal (0.0) to the delayed one (1.0).

mix_ramp

How many frames a change of mix walks over, 0 to 96000. With 0, the default, a change lands at the next block, as CircuitPython’s flanger does. Set, a change walks from where the mix stands to the new value in a straight line over that many frames, so a jump doesn’t click: 960 is 20 ms at 48 kHz. A move during a walk starts a new walk from where it stands. A new node’s first mix, and the first after a reset, land at once. Not in CircuitPython.

invert

Whether the delayed signal is inverted.

sample_rate

Frames per second. Writable, to 1 or more.

property bits_per_sample

Size of one sample in bits: 8 or 16.

property channel_count

Number of channels: 1 or 2.

property lfo_value

Where the sweep is now, as the oscillator’s triangle from 0.0 to 1.0.

property playing

Whether a source is playing.

play(sample, *, loop=False)[source]

Start reading a source.

Parameters:
  • sample – The audio to process. Its sample format has to match the effect’s.

  • loop – Whether to start the source again when it ends.

Returns:

The effect itself.

stop()[source]

Stop reading the source. The tail is not played out.

deinit()[source]

Release the effect. Later calls other than deinit raise ValueError.

class audiodelays.GranularPitchShift(*, semitones=0, mix=1, grain_size=1024, density=2, spread=0, buffer_size=512, sample_rate=8000, bits_per_sample=16, samples_signed=True, channel_count=1)[source]

Bases: object

A pitch shifter that plays overlapping grains of the source.

Grains are short slices of the recent input, replayed at a different speed. It keeps the tempo and shifts the pitch.

Parameters:
  • semitones – How far to shift the pitch, in semitones. Negative is down. The default is 0.

  • mix – The balance from the dry signal (0.0) to the shifted one (1.0). The default is 1.

  • grain_size – How many frames in a grain, 2 or more. The default is 1024.

  • density – How many grains play at once, 1 to 8. The default is 2.

  • spread – How much each grain’s start is randomised, 0.0 to 1.0. The default is 0.

  • buffer_size – How many bytes the effect hands out in each block. The default is 512.

  • sample_rate – Frames per second, 1 or more. The default is 8000.

  • bits_per_sample – 8 or 16. The default is 16.

  • samples_signed – Whether samples are signed. The default is True.

  • channel_count – 1 or 2. The default is 1.

Raises:
  • ValueError – grain_size is below 2 or density is not 1 to 8.

  • ValueError – channel_count is not 1 or 2, sample_rate is below 1, or bits_per_sample is not 8 or 16.

semitones

How far to shift the pitch, in semitones.

mix

The balance from the dry signal (0.0) to the shifted one (1.0).

spread

How much each grain’s start is randomised.

sample_rate

Frames per second. Writable, to 1 or more.

property bits_per_sample

Size of one sample in bits: 8 or 16.

property channel_count

Number of channels: 1 or 2.

property playing

Whether a source is playing.

play(sample, *, loop=False)[source]

Start reading a source.

Parameters:
  • sample – The audio to process. Its sample format has to match the effect’s.

  • loop – Whether to start the source again when it ends.

Returns:

The effect itself.

stop()[source]

Stop reading the source. The tail is not played out.

deinit()[source]

Release the effect. Later calls other than deinit raise ValueError.

class audiodelays.PitchShift(*, semitones=0, mix=1, window=1024, overlap=128, buffer_size=512, sample_rate=8000, bits_per_sample=16, samples_signed=True, channel_count=1)[source]

Bases: object

A pitch shifter that reads the source through an overlapping window.

Where GranularPitchShift plays many grains, this plays one window at a time, which costs less. freeze holds the window so a note sustains.

Parameters:
  • semitones – How far to shift the pitch, in semitones. Negative is down. The default is 0.

  • mix – The balance from the dry signal (0.0) to the shifted one (1.0). The default is 1.

  • window – The size of the window in bytes, at least one frame. The default is 1024.

  • overlap – How many bytes the windows overlap by. The default is 128.

  • buffer_size – How many bytes the effect hands out in each block. The default is 512.

  • sample_rate – Frames per second, 1 or more. The default is 8000.

  • bits_per_sample – 8 or 16. The default is 16.

  • samples_signed – Whether samples are signed. The default is True.

  • channel_count – 1 or 2. The default is 1.

Raises:
  • ValueError – window is shorter than one frame.

  • ValueError – channel_count is not 1 or 2, sample_rate is below 1, or bits_per_sample is not 8 or 16.

semitones

How far to shift the pitch, in semitones.

mix

The balance from the dry signal (0.0) to the shifted one (1.0).

freeze

Whether the window is held, so the sound sustains.

sample_rate

Frames per second. Writable, to 1 or more.

property bits_per_sample

Size of one sample in bits: 8 or 16.

property channel_count

Number of channels: 1 or 2.

property playing

Whether a source is playing.

play(sample, *, loop=False)[source]

Start reading a source.

Parameters:
  • sample – The audio to process. Its sample format has to match the effect’s.

  • loop – Whether to start the source again when it ends.

Returns:

The effect itself.

stop()[source]

Stop reading the source. The tail is not played out.

deinit()[source]

Release the effect. Later calls other than deinit raise ValueError.

class audiodelays.MultiTapDelay(*, max_delay_ms=500, delay_ms=250, decay=Ellipsis, mix=Ellipsis, taps=None, buffer_size=512, sample_rate=8000, bits_per_sample=16, samples_signed=True, channel_count=1)[source]

Bases: object

A delay with several taps, each at its own position and level.

A tap is read from the delay line at a fraction of delay_ms, and its level scales what is heard there.

Parameters:
  • max_delay_ms – The longest delay the effect can be set to, 1 to 4000. It sizes the delay line, so it can only be given here. The default is 500.

  • delay_ms – The delay in milliseconds, up to max_delay_ms. The default is 250.

  • decay – How much of the output feeds back, 0.0 to 1.0. The default is 0.7.

  • mix – The balance from the dry signal (0.0) to the taps (1.0). The default is 0.25.

  • taps – The taps: a sequence of positions, or of (position, level) pairs, each from 0.0 to 1.0, where a position is a fraction of delay_ms. A bare position has a level of 1. None, the default, is no taps.

  • buffer_size – How many bytes the effect hands out in each block. The default is 512.

  • sample_rate – Frames per second, 1 or more. The default is 8000.

  • bits_per_sample – 8 or 16. The default is 16.

  • samples_signed – Whether samples are signed. The default is True.

  • channel_count – 1 or 2. The default is 1.

Raises:
  • ValueError – max_delay_ms is not 1 to 4000, taps is empty, or a pair is not two values.

  • TypeError – taps is not iterable.

  • ValueError – channel_count is not 1 or 2, sample_rate is below 1, or bits_per_sample is not 8 or 16.

delay_ms

The delay in milliseconds.

decay

How much of the output feeds back, 0.0 to 1.0.

mix

The balance from the dry signal (0.0) to the taps (1.0).

taps

The taps. Reading gives (position, level) pairs, or None for no taps; any iterable of positions or pairs can be set.

sample_rate

Frames per second. Writable, to 1 or more.

property bits_per_sample

Size of one sample in bits: 8 or 16.

property channel_count

Number of channels: 1 or 2.

property playing

Whether a source is playing.

play(sample, *, loop=False)[source]

Start reading a source.

Parameters:
  • sample – The audio to process. Its sample format has to match the effect’s.

  • loop – Whether to start the source again when it ends.

Returns:

The effect itself.

stop()[source]

Stop reading the source. The tail is not played out.

deinit()[source]

Release the effect. Later calls other than deinit raise ValueError.

audiofreeverb

Generated from audiofreeverb.pyi; the file reads on its own.

CircuitPython’s Freeverb reverb.

Freeverb is an audio source that reads another source and adds a room around it, with eight comb filters and four all-pass filters per channel. Its line lengths are fixed in the code. To choose your own network, see audioverb.Tank. The class is CircuitPython’s own and takes the same arguments on every port.

class audiofreeverb.Freeverb(*, roomsize=Ellipsis, damp=Ellipsis, pre_filter=None, post_filter=None, mix=Ellipsis, buffer_size=512, sample_rate=8000, bits_per_sample=16, samples_signed=True, channel_count=1)[source]

Bases: object

A reverb.

Parameters:
  • roomsize – The size of the room, 0 to 1. The default is 0.5. A synthio.BlockInput.

  • damp – How quickly the high frequencies die away, 0 to 1. The default is 0.5. A synthio.BlockInput.

  • pre_filter – A synthio.Biquad, or a sequence of them, run on the signal before the reverb. None for none.

  • post_filter – The same, run after the reverb.

  • mix – How much of the reverberated signal goes out, 0 to 1. The default is 0.5. 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 – Must be 16.

  • samples_signed – Must be True.

  • 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, bits_per_sample is not 16 or samples_signed is False.

  • MemoryError – The comb and all-pass lines do not fit.

deinit()[source]

Free the effect. Later calls other than deinit raise ValueError.

sample_rate

Frames per second. Writable, to 1 or more.

property bits_per_sample

Size of one sample in bits.

property channel_count

Number of channels: 1 or 2.

property playing

True while a source is playing through the effect.

roomsize

The size of the room, 0 to 1.

damp

How quickly the high frequencies die away, 0 to 1.

pre_filter

The biquad or biquads run before the reverb.

post_filter

The biquad or biquads run after the reverb.

mix

How much of the reverberated signal goes out, 0 to 1.

play(sample, *, loop=False)[source]

Read from a source and add reverb to it.

Parameters:
  • sample – The audio source.

  • loop – Start the source over when it ends.

stop()[source]

Stop reading the source.

audiospeed

Generated from audiospeed.pyi; the file reads on its own.

CircuitPython’s speed and sample-rate changers.

SpeedChanger plays a source faster or slower, which also moves its pitch. Resampler plays a source at the rate its destination asks for. Both read every frame by position, with no interpolation. The module is CircuitPython’s own and takes the same arguments on every port.

class audiospeed.SpeedChanger(source, rate=None)[source]

Bases: object

Plays a source at a changed speed.

The output has the source’s rate, channel count and bit depth. At a rate of 2.0 the source plays twice as fast, an octave higher; at 0.5 it plays half as fast, an octave lower. The node reports done when its source does.

Parameters:
  • source – The audio source to read.

  • rate – The speed relative to the source, from 0 to 1000. The default, None, is 1.0.

Raises:
rate

The speed relative to the source, from 0 to 1000. It is held in 16.16 fixed point, rounded to the nearest step, so what you read back can differ from what you wrote in the sixth decimal place.

sample_rate

Frames per second, the source’s. Writable, to 1 or more.

property bits_per_sample

Size of one sample in bits, the source’s.

property channel_count

Number of channels, the source’s.

deinit()[source]

Release the node and let go of its source. Every later use raises ValueError.

class audiospeed.Resampler(source)[source]

Bases: object

Plays a source at the sample rate the destination asks for.

Set sample_rate to the destination’s rate and the node reads the source at the ratio of the source’s rate to that. Playing 16 kHz material into an 8 kHz destination consumes two source frames for each frame out. Until a rate is set the ratio is 1.0.

Parameters:

source – The audio source to read.

Raises:

TypeError – source is not an audio source.

property rate

The source frames consumed for each frame out. It is read-only: it is whatever the destination’s sample_rate asked for.

sample_rate

The rate the destination wants, in Hz. Set it to change rate.

property bits_per_sample

Size of one sample in bits, the source’s.

property channel_count

Number of channels, the source’s.

deinit()[source]

Release the node and let go of its source. Every later use raises ValueError.

audioconvolve

Generated from audioconvolve.pyi; the file reads on its own.

Apply an impulse response to a stream, by partitioned FFT.

Convolver convolves its source with a measured impulse response, such as a room, a cabinet or a spring, or with a room it synthesizes itself. It adds one block of latency once an impulse is loaded.

audioconvolve.FRAMES
Type:

Frames in one block, and the size of one partition

audioconvolve.MAX_PARTITIONS

512, so impulses up to MAX_PARTITIONS * FRAMES frames long.

Type:

The most partitions an impulse can take

class audioconvolve.Convolver(impulse=None, impulse_channels=1, sample_rate=48000, max_taps=0, ir_channels=0, gain=None, mix=None, channel_count=2, wet_gain=None)[source]

Bases: object

Convolves a stream with an impulse response, played like any audio sample.

The tail keeps ringing after the source ends, so a room rings out. A convolver with nothing loaded passes its input through. The capacity for the impulse is fixed when the convolver is made, because something downstream may already be pulling from it: size it with max_taps, or give an impulse to size it from.

Parameters:
  • impulse – Optional. The impulse response, as signed 16-bit samples, interleaved when impulse_channels is 2. If given, it is loaded now.

  • impulse_channels – Channels in impulse: 1, which is shared by both audio channels, or 2, which gives each channel its own.

  • sample_rate – Frames per second.

  • max_taps – The longest impulse, in frames, that load and synthesize can later bring. The default is the length of impulse, or 4096 frames when there is none. A longer impulse raises it.

  • ir_channels – Channels the stored impulse has, 1 or 2. The default is impulse_channels.

  • gain – A linear gain on impulse as it is loaded. The default is 1.0.

  • mix – Wet and dry balance, 0.0 to 1.0, clamped, where the dry stays at unity until 0.5 and the wet is already at full level there, as in audiofreeverb. The default is 0.5.

  • channel_count – Audio channels, 1 or 2.

  • wet_gain – A linear gain on the wet signal alone, 0.0 to 4.0, clamped. The default is 1.0.

Raises:

ValueError – A channel count is out of range, impulse is not a whole number of 16-bit frames, or the impulse is too long.

sample_rate

Frames per second. Writable, to 1 or more.

property bits_per_sample

Size of one sample in bits: always 16.

property channel_count

Number of audio channels: 1 or 2.

property taps

The length of the loaded impulse in frames, rounded up to a whole number of partitions. 0 when nothing is loaded.

property latency

Frames of delay the convolver adds: FRAMES once an impulse is loaded, 0 before, since an empty convolver passes its input through.

property room_peak_gain

The most the last synthesize room brings a low full-scale input back, as a linear gain, before wet_gain. A dark room gathers its energy low and reads high. 0.0 after load or before any synthesize.

play(source, /)[source]

Set the stream to convolve, replacing the last one.

Raises:

ValueError – The stream’s channel count differs from this node’s.

set(*, mix=Ellipsis, wet_gain=Ellipsis)[source]

Change options while the node plays.

Parameters:
  • mix – As for the constructor.

  • wet_gain – As for the constructor.

Raises:

TypeError – An unknown option was given.

load(impulse, channels=1, gain=None)[source]

Load an impulse response while the node plays.

Audio in flight is kept: the block being played crossfades from the old impulse to the new one, with no frame dropped or repeated. An empty impulse unloads it.

Parameters:
  • impulse – Signed 16-bit samples, interleaved when channels is 2.

  • channels – Channels in impulse, 1 or 2.

  • gain – A linear gain applied as it is loaded. The default is 1.0.

Raises:

ValueError – channels is out of range, impulse is not a whole number of frames, or it is longer than max_taps.

synthesize(decay=None, damping_hz=None, predelay_ms=None, diffusion_ms=None, seed=1)[source]

Load a synthesized room: decaying noise, normalised to unit energy. The same arguments always give the same room, bit for bit, on every interpreter.

Parameters:
  • decay – The time the room takes to fall by 60 dB, in seconds. The default is 2.0.

  • damping_hz – Rolls the tail’s top off as it decays, in Hz. The default is 0.0, which leaves it bright.

  • predelay_ms – Silence before the room starts, in milliseconds. The default is 0.0.

  • diffusion_ms – Fades the tail in over this many milliseconds rather than starting it at full amplitude, so the room does not sound like a burst of noise. The default is 0.0.

  • seed – Chooses the noise. Different seeds are different rooms.

room_peak_gain_for(decay=None, damping_hz=None, predelay_ms=None, diffusion_ms=None, seed=1)[source]

The room_peak_gain that synthesize would give for the same arguments, worked out without loading anything. Set the wet level from it before calling synthesize, so the audio in flight fades to the new room at its new level.

clear()[source]

Empty the convolver’s memory of past audio, so the room stops ringing.

deinit()[source]

Release the convolver and let go of its source. Every later use raises ValueError.