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:
|
|
|
|---|---|---|
constructor |
|
|
block inputs |
|
|
fixed at construction |
|
those, plus |
methods |
|
|
read-only |
|
|
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.PEAKING_EQ
boost or cut a band around
frequencybygain_db. This is 4.- Type:
A
Biquadmode
- audiobiquad.LOW_SHELF
boost or cut everything below
frequencybygain_db. This is 5.- Type:
A
Biquadmode
- audiobiquad.HIGH_SHELF
boost or cut everything above
frequencybygain_db. This is 6.- Type:
A
Biquadmode
- audiobiquad.MODES
The seven mode numbers,
LOW_PASStoHIGH_SHELF, in order. They are numbered exactly assynthio.FilterModenumbers its modes, so either can be handed to either.
- audiobiquad.FRAMES
- Type:
Frames in one block when
buffer_sizeis not given
- 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:
objectOne filter section.
Every argument is a keyword.
frequency,Q,gain_dbandmixare block inputs: a number, or asynthio.LFOorsynthio.Maththat is read once a block, so an LFO onfrequencyarrives about a block late.When
frequency,Q,gain_dbormodechanges 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_SHELFandHIGH_SHELF. The default isLOW_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_SHELFandHIGH_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 –
modeis not one of the seven,channel_countis not 1 or 2,sample_rateis below 1, orbuffer_sizeis not whole frames from one to 256.
- mode
The filter’s mode. Setting it raises
ValueErrorfor 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 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.
- deinit()[source]
Release the node. Later calls other than
deinitraiseValueError.
- class audiobiquad.AllPass(*, stages=4, frequency=1000, feedback=0, mix=1, sample_rate=48000, channel_count=2, buffer_size=None)[source]
Bases:
objectA cascade of first-order all-pass stages.
frequencyreally is the frequency at which one stage’s phase passes minus 90 degrees, so nothing has to be pre-warped. Withmixat 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,feedbackandmixare block inputs, as forBiquad.stagessizes 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 –
stagesis out of range,channel_countis not 1 or 2,sample_rateis below 1, orbuffer_sizeis 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 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.
- deinit()[source]
Release the node. Later calls other than
deinitraiseValueError.
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_dbandsustain_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:
objectA 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_GATEandDYN_TRANSIENT. The default isDYN_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_TRANSIENTonly: the gain in dB for the start of a note. The default is 0.sustain_gain_db –
DYN_TRANSIENTonly: 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_hzmakes 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_EXPANDandDYN_GATEpull 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, withtransient_dual: the sustain section’s fast attack, in milliseconds. The default is 1.sustain_fast_release_ms –
DYN_TRANSIENT, withtransient_dual: the sustain section’s fast release, in milliseconds. The default is 200.sustain_slow_attack_ms –
DYN_TRANSIENT, withtransient_dual: the sustain section’s slow attack, in milliseconds. The default is 25.sustain_slow_release_ms –
DYN_TRANSIENT, withtransient_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_detectorinDYN_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_countis not 1 or 2, ordetectoris 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.
- 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_msorchannel_countallocates what it needs before anything changes.- Raises:
ValueError – As for the constructor.
TypeError – An unknown option was given.
- deinit()[source]
Release the node. Later calls other than
deinitraiseValueError.
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:
objectA delay with a processed feedback loop.
Every argument is a keyword.
sample_rate,max_delay_msandchannel_countsize the delay line and the audio, so they can only be given here; every other option can be changed withset. A keyword that is not one of these raisesTypeError.- 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 ordelay_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_msthat 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_mstakes 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_feedit 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_msis not above 0,channel_countis not 1 or 2, orwow_shapeis not a power-of-two count from 2 to 4096 int16 samples.TypeError – An unknown option was given, or both
delay_msanddelay_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.
- 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_shapeis not a power-of-two count from 2 to 4096 int16 samples.TypeError – An unknown option was given, or both
delay_msanddelay_frames.sample_rate,max_delay_msandchannel_countare ignored here, not applied.
- deinit()[source]
Release the node. Later calls other than
deinitraiseValueError.
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:
objectA waveshaper with oversampling, played like any audio sample.
The shaping happens at
oversampletimes 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_countandoversampleare fixed when the node is made, except thatsetcan replace the curve. The rest can be given here or toset.curveis 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
mixandpost_gainof 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 –
curveis missing, shorter than two points or not a whole number of 16-bit values;channel_countis not 1 or 2; oroversampleis 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.
- 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_countandoversampleare 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 –
curveis shorter than two points or not a whole number of 16-bit values.TypeError – An unknown option was given.
- 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:
objectA zero-order hold in which
numsource frames carrydennew 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
numequalsdenthe node is a wire, byte for byte. Itslatencyis 0: what a hold displaces is an event landing on a frame it drops, up toceil(num / den) - 1frames, 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.numcan 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 –
sourceis 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.
- 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:
objectA 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_countandbuffer_sizecan only be given here; the rest can be given here or toset.- 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
modulateinput moves the cutoff, of either sign. The default is 10.ramp_ms – How long a change of
cutoff_hz,resonance,drive,passband_compormixtakes 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.polesandoversamplealways land at once.cutoff – A stream to read the cutoff from, as for
modulate.
- Raises:
ValueError –
sample_rateis less than 1,channel_countis not 1 or 2, orbuffer_sizeis 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.
- 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_msset, 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; usemodulatefor 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
vof full scale the cutoff iscutoff_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 ascutoff_hzsets it.- Parameters:
cutoff – The stream, mono or stereo, or None to disconnect it.
- Raises:
TypeError – An input other than
cutoffwas named.ValueError – The stream is not mono or stereo.
- 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:
objectA plate reverberator, played like any audio sample.
Construction fixes the allocation:
sample_rate,channel_countandmax_predelay_ms. It also takes the network,delaysandtaps.setmoves every other option while the node plays and without emptying the lines; giving itdelaysortapscuts a new network, which does empty them. Every filter is out of the path at zero, so aTank()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.FeedbackDelayandaudioconvolve.Convolverdo the same.delaysis 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.tapsis 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 tosample_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_mscan 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_rateis less than 1,channel_countis not 1 or 2,max_predelay_msis negative,delaysis not twelve lengths of at least 4 frames that fit, ortapsis 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.
- 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
delaysortapscuts 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_countormax_predelay_ms, which are fixed when the node is made.ValueError –
delaysortapsare not valid, as for the constructor.
- 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:
objectScales 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_countis 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
widthwas 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:
objectThe way
Distortionshapes 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:
objectA 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 thefilterproperty.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_countis not 1 or 2,sample_rateis less than 1, orbits_per_sampleis not 8 or 16.TypeError –
filterholds something that is not asynthio.Biquad.
- deinit()[source]
Free the filter. Later calls other than
deinitraiseValueError.
- 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.
- 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:
objectA 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_countis not 1 or 2,sample_rateis less than 1, orbits_per_sampleis not 8 or 16.
- deinit()[source]
Free the effect. Later calls other than
deinitraiseValueError.
- 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.
- 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:
objectA 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 isDistortionMode.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_countis not 1 or 2,sample_rateis less than 1, orbits_per_sampleis not 8 or 16.
- deinit()[source]
Free the effect. Later calls other than
deinitraiseValueError.
- 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
DistortionModein use.
- soft_clip
Whether the output is softly clipped.
- mix
How much of the distorted signal goes out, 0 to 1.
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:
objectA single-tap echo with feedback.
The delay line repeats the source, each repeat
decaytimes as loud as the one before.filteris applied to the signal inside the feedback loop, so each repeat is filtered again. Withfreq_shifton, a change todelay_mswhile 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_msshifts 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_msis not 1 to 4000.ValueError –
channel_countis not 1 or 2,sample_rateis below 1, orbits_per_sampleis 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_msshifts 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.
- deinit()[source]
Release the effect. Later calls other than
deinitraiseValueError.
- 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:
objectA chorus: the source mixed with slightly detuned, delayed copies of itself.
voicessets 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_msis not 1 to 4000.ValueError –
channel_countis not 1 or 2,sample_rateis below 1, orbits_per_sampleis 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.
- deinit()[source]
Release the effect. Later calls other than
deinitraiseValueError.
- 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:
objectA flanger: a short, swept delay mixed with the source, with feedback.
A low-frequency oscillator sweeps the delay from
min_delay_msup towardsmax_delay_ms, by as much of the span asdepthsays.- 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_msis not 1 to 100.ValueError –
channel_countis not 1 or 2,sample_rateis below 1, orbits_per_sampleis 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
mixwalks 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.
- deinit()[source]
Release the effect. Later calls other than
deinitraiseValueError.
- 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:
objectA 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_sizeis below 2 ordensityis not 1 to 8.ValueError –
channel_countis not 1 or 2,sample_rateis below 1, orbits_per_sampleis 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.
- deinit()[source]
Release the effect. Later calls other than
deinitraiseValueError.
- 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:
objectA pitch shifter that reads the source through an overlapping window.
Where
GranularPitchShiftplays many grains, this plays one window at a time, which costs less.freezeholds 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 –
windowis shorter than one frame.ValueError –
channel_countis not 1 or 2,sample_rateis below 1, orbits_per_sampleis 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.
- deinit()[source]
Release the effect. Later calls other than
deinitraiseValueError.
- 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:
objectA 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 ofdelay_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_msis not 1 to 4000,tapsis empty, or a pair is not two values.TypeError –
tapsis not iterable.ValueError –
channel_countis not 1 or 2,sample_rateis below 1, orbits_per_sampleis 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.
- deinit()[source]
Release the effect. Later calls other than
deinitraiseValueError.
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:
objectA 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_countis not 1 or 2,sample_rateis less than 1,bits_per_sampleis not 16 orsamples_signedis False.MemoryError – The comb and all-pass lines do not fit.
- deinit()[source]
Free the effect. Later calls other than
deinitraiseValueError.
- 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.
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:
objectPlays a source at a changed speed.
The output has the source’s rate, channel count and bit depth. At a
rateof 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:
TypeError –
sourceis not an audio source.ValueError –
rateis outside 0 to 1000.
- 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:
objectPlays a source at the sample rate the destination asks for.
Set
sample_rateto 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 –
sourceis 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_rateasked for.
- 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 * FRAMESframes 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:
objectConvolves 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 animpulseto size it from.- Parameters:
impulse – Optional. The impulse response, as signed 16-bit samples, interleaved when
impulse_channelsis 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
loadandsynthesizecan later bring. The default is the length ofimpulse, or 4096 frames when there is none. A longerimpulseraises it.ir_channels – Channels the stored impulse has, 1 or 2. The default is
impulse_channels.gain – A linear gain on
impulseas 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,
impulseis 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:
FRAMESonce an impulse is loaded, 0 before, since an empty convolver passes its input through.
- property room_peak_gain
The most the last
synthesizeroom brings a low full-scale input back, as a linear gain, beforewet_gain. A dark room gathers its energy low and reads high. 0.0 afterloador before anysynthesize.
- 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
channelsis 2.channels – Channels in
impulse, 1 or 2.gain – A linear gain applied as it is loaded. The default is 1.0.
- Raises:
ValueError –
channelsis out of range,impulseis not a whole number of frames, or it is longer thanmax_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_gainthatsynthesizewould give for the same arguments, worked out without loading anything. Set the wet level from it before callingsynthesize, so the audio in flight fades to the new room at its new level.
- deinit()[source]
Release the convolver and let go of its source. Every later use raises
ValueError.