audioeffects.combfilter
CombFilter - a delay line short enough to be a pitch, fed back on
itself.
The player’s text is the class docstring; the CLAIMS table in the class’s
test file ties its claim sentences to tests.
- audioeffects.combfilter.MAX_DELAY_MS = 60.0
The line, in milliseconds. 20 Hz wants 50 ms and the node keeps one frame of headroom below the line’s length (
audiodsp_feedback_delay.c:142-150), so a 50 ms line would tune the bottom of the range to 20.02 Hz. 60 ms is the next round number that clears it; the cost is RAM, 11.5 KB of stereo int16 at 48 kHz, allocated once.
- audioeffects.combfilter.TONE_OFF_HZ = 24000.0
The top of the Tone travel means off, not “a low-pass at 24 kHz”. The node’s one-pole coefficient at 24 kHz on a 48 kHz graph is 0.957, not 1, so it would still shade the top of every pass;
damping_hz = 0is the node’s own “no filter at all” (audiodsp_feedback_delay.c:31-38). A macro at 127/127 maps to exactly this value, so the off position is exact.
- audioeffects.combfilter.FLAT_DB = 0.2
A trim under this is built as a wire rather than a pass of arithmetic that must come back byte-identical. MIDI 64 is the exact centre of a BIPOLAR span since audiocomponents#87, so the detent itself is 0.000 dB; what this floor still covers is the codes either side of it, which a knob passes through.
LowPassuses the same floor, for the same reason.
- audioeffects.combfilter.MIX_UNITY_SNAP = 0.02
The Mix macro snaps to exactly 1.0 inside this. Same grid, worse consequence: 64/127 of a 0..2 span is 1.0079, which drops the dry leg to 0.9921, and the feedforward comb’s null at Feedback 0 stops being total - -42 dB instead of silence. The snap is 1.3 MIDI steps wide and inaudible; the null it protects is a stated trait.
- audioeffects.combfilter.TRIM_CORNER_HZ = 5.0
The trim is one high shelf at a subsonic corner, which is a broadband gain everywhere above it.
LowPassmeasured this node at that corner flat to 0.010 dB from 50 Hz to 15 kHz at 48/44.1/22.05 kHz and -12..+12 dB; a 10 Hz corner reads 0.95 dB out at 20 Hz, which is why the corner is 5.
- audioeffects.combfilter.TRIM_TAIL_S = 1.5
How long the trim can keep a non-zero output after its input stops, in seconds, while it is in circuit. The shelf is fixed point with 12 fractional state bits (
audiodsp_biquad.c:163-185at audiodsp v0.6.2) and a pole pair near z = 1, and its rounding carries the last LSB past the linear decay its poles give, so this term is measured, not derived: over every active Trim step, DC at twelve levels and both signs, 5 and 40 Hz sines stopped at eight phases, and noise, 15 621 cells, none held and the longest ran 40 041 frames at 48 kHz (0.834 s; 0.825 s at 44.1, 0.818 s at 22.05; measured 2026-09-28). 1.5 s is 1.8 times that. The comb’s lap bound counts from where the trim stops.
- class audioeffects.combfilter.CombFilter(source, *options, **keywords)[source]
Bases:
ComponentA tuned comb: a delay line short enough to be a pitch, fed back on itself, so noise turns into a note and a chord turns metallic.
Frequency. Frequency is the note the comb rings at, tuned between samples. From 55 Hz to 3.52 kHz the first repeat lands within 5 cents of the note you asked for, and at 880 Hz it does at 48 kHz, 44.1 kHz and 22.05 kHz, and in mono. While it rings, it rings on that pitch, and then it stops.
Feedback. Feedback sets how tall the resonances stand: at 200 Hz the peak is 1/(1-Feedback) and the null 1/(1+Feedback), within 0.2 dB. At Feedback 0 it is the feedforward comb, with nulls more than 60 dB down and peaks 6 dB up, within 0.1 dB.
Mix. Mix 0 is a wire, 1 is dry plus comb, and 2 is the comb alone. Mix 0 is the source sample for sample, whatever Trim is set to.
Tone. Tone is a low-pass inside the loop, darkening the repeats. Its top stop is off, and turning it off after it has been in leaves nothing behind.
Trim. Trim sits in front of the comb, so turning it down makes room for the resonance before the gain rather than after.
Glide. Glide slides the tuning, so turning Frequency bends the note rather than clicking.
Level. A comb gains, so a loud input can reach the rail by design. Keep the input under -24 dBFS and the defaults and patches stay off the rails. Feedback or Trim at its top can still push the output onto the rails.
reset()empties the line.Latency and tail. It adds no latency at any setting. The tail always reaches exact zero, and
tail_samplessays when, for the settings as they stand: 3219 frames at the defaults at 48 kHz.Patches. Each patch tunes the comb to a different note. The Effect controls page lists what the knobs span and the patches.
It needs
audioechoandaudiobiquad, so a stock CircuitPython board can’t run it.- NAME = 'CombFilter'
The stable provider name
audioeffects.create()discovers.
- TIER = 'audiodsp'
STOCK or AUDIODSP, with REQUIRES naming the audiodsp-own modules an AUDIODSP class needs.
- Type:
roadmap §3
- CAPABILITIES = ()
The contract’s static reads.
CAPABILITIESnames"tempo_sync"if and only if the class readsself._transport().
- TAIL_SAMPLES = None
The class-level declaration stays
None; the instance’stail_samplesis finite at every setting (2026-09-28), because the bound depends on the setting.The comb can ring at 1 LSB for about 500 frames past
tail_samples, the last of its decay.
- INPUT_CEILING_DBFS = -24
The defaults and every patch play the ceiling kit’s materials clean at this level; at -18 dBFS, patch 1 rails on a DC step.
- CLIPS_AT_TOP = (1, 4)
the rail check skips them.
- Type:
Settings that clip by design
- MACRO_LABELS = ('Frequency', 'Feedback', 'Mix', 'Tone', 'Trim', 'Glide')
Knob names, one per macro index; one mode per label; the private engineering spans behind them; and the patches on the 0-127 grid.
- PATCHES = {0: ('Metallic', (74, 94, 64, 127, 64, 6)), 1: ('Ringing Pitch', (57, 123, 64, 127, 53, 6)), 2: ('Soft Ripple', (41, 40, 32, 127, 64, 6)), 3: ('Dark Resonator', (48, 114, 64, 45, 42, 6)), 4: ('Single Slap', (24, 0, 64, 127, 64, 6)), 5: ('Filter Only', (94, 107, 127, 127, 64, 6))}
Named for settings, never for products; every value is
macro_of()of the setting in the comment beside it.
- reset()[source]
Clear every node this class built, tail first, and restore patch 0. The borrowed source is never named here.
- property tail_samples
Frames until the output is exactly zero once the input stops, as an upper bound for the settings as they stand:
laps_to_zerolaps of the longest line the read head may be at, each one frame longer for the interpolated read and the Tone low-pass’s memory longer, plusTRIM_TAIL_Swhile the trim is in circuit. Finite at every setting.