audioeffects.harmonizer
Harmonizer - a harmony of pitch-shifted voices.
The player’s text is the class docstring; the CLAIMS table in the class’s
test file ties its claim sentences to tests. How the graph works is told
where it is built, in Harmonizer._build.
- audioeffects.harmonizer.BLOCK = 256
Frames a mixer pull hands out, and so what every node and tap takes per pull.
- audioeffects.harmonizer.LEVEL_TOP_DB = 0.0
The Level span, in dB. MIDI 1 is -40 dB and 127 is 0 dB, 40/126 dB a step; MIDI 0 sits one step below -40 and turns the voice off.
- audioeffects.harmonizer.WINDOW_DEFAULT_MS = 21.333333333333332
1024 frames at 48 kHz.
- audioeffects.harmonizer.DEFAULTS = (0.0, 4.0, 7.0, -12.0, -6.0, -6.0, -9.0, 0.0, 0.0, 1.0)
The constructor’s macro defaults, which NaN falls back to (patch 0).
- audioeffects.harmonizer.STEPS = 256
The shifter reads its line at
floor(256 * 2^(semitones / 12))256ths of a frame per frame.
- audioeffects.harmonizer.ratio_step(semitones)[source]
The shifter’s nearest read-rate step, in 256ths, to an interval.
- audioeffects.harmonizer.step_semitones(step)[source]
The interval at the centre of read-rate step
step: the node’s floor lands onstepfrom it, with half a step to spare either way, in single precision as in double.
- audioeffects.harmonizer.whole(value)[source]
A Pitch or Voice value as the whole semitone it plays.
- audioeffects.harmonizer.mix_gains(mix)[source]
(dry, voice) gain at Mix
mix: the dry at unity up to 1, then 2 - Mix; each voice at Mix, capped at 1.
- audioeffects.harmonizer.level_gain(db)[source]
A Level in dB as a gain; 0 for the bottom step, which is off.
- class audioeffects.harmonizer.Harmonizer(source, *options, **keywords)[source]
Bases:
ComponentThree pitch shifters, each a fixed interval from your note, blended under the dry: the rig of three Eventide H910s played from one keyboard, so one singer is three-part harmony.
The controls. Voice 1 to Voice 3 set each voice’s interval in whole semitones, and Pitch moves all three together. Level 1 to Level 3 set each voice’s level, and the bottom step turns the voice off. Detune pulls voice 1 down and voice 2 up. Spread pans voice 1 left and voice 2 right; the dry and voice 3 stay in the centre. Mix holds the dry at unity up to 1 while the voices rise to their Levels; from 1 to 2 the dry fades, and at 2 the voices play alone. Constructor values land on the nearest of each knob’s 128 steps;
window_ms, 5 to 60 ms (21.33 by default), is fixed for good. The Effect controls page lists what the knobs span.What you hear. Each voice is its own machine: turning one on or off never changes the dry or the other voices. Each voice sits on the closest pitch its shifter can make: within 3.4 cents of its interval from unison up, 6.8 cents down to an octave below and 13.7 cents below that. So Detune moves in steps of about 7 cents near unison, and voices 1 and 2 sit evenly apart only to within a step. Detune is a steady offset, not a chorus: a voice holds its pitch. Each voice glitches as it splices, more often the further it is shifted and the shorter the window: at the default window a fifth up splices every 43 ms, at any sample rate, where the first channel is silent. Where it is not, each splice moves by up to a fiftieth of a second to land in phase, so the splices come sooner. A voice at exact unison never splices: it is a fixed short delay, and it combs with the dry. A voice you turn back on starts from silence, not with a scrap of what it played before.
Limits. It moves notes by fixed intervals and does not listen for the key. Each voice rounds off peaks above about -1.4 dBFS. The voices add to the dry: at patch 0 an input that peaks at or below 13 900 (-7.4 dBFS) cannot reach full scale. Patch 6 is patch 0 without the octave below, for a board that cannot run three voices in time. The shifter reads its line without interpolation, which you may hear as grit on a shifted voice. On a mono source Spread does nothing. An interval move leaves each voice’s splice where it was. A control that jumps makes the output step: move it in small steps from the host if you need it smooth.
Wire, latency, tail. At Mix 0 the output is the input, byte for byte. There is no latency: the dry is a wire, and each shifted voice trails it by between the crossfade, a sixteenth of the window, and the whole window.
tail_samplescovers the window, the crossfade and one block, and is 0 at Mix 0 or with every voice off.reset()empties the three lines, starts their splices where a new instance’s start, and returns to patch 0. On CircuitPython’s own pitch shifter a reset does not restart the splices. The class never reads the host’s tempo.- NAME = 'Harmonizer'
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().
- INPUT_CEILING_DBFS = -12.1
The loudest sum over every setting is the dry at unity and all three Levels at 0 dB at Mix 1: 4.0 times the input (patch 1 with Level 3 at 0 dB sums 3.44), so -12.1 dBFS keeps it inside full scale (4.0 times is 12.04 dB, and -12.0 would leave the sum 0.5 % over).
- MACRO_LABELS = ('Pitch', 'Voice 1', 'Voice 2', 'Voice 3', 'Level 1', 'Level 2', 'Level 3', 'Detune', 'Spread', 'Mix')
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: ('Third and fifth above, octave below', (64, 85, 101, 0, 108, 108, 99, 0, 0, 64)), 1: ('Octave below, doubled', (64, 0, 0, 64, 118, 118, 0, 71, 64, 64)), 2: ('Wide unison', (64, 64, 64, 64, 108, 108, 0, 71, 127, 64)), 3: ('Fourths and fifths', (64, 90, 101, 127, 99, 99, 89, 0, 64, 64)), 4: ('Octave up and down', (64, 127, 0, 64, 108, 108, 0, 0, 64, 64)), 5: ('Minor triad, voices alone', (64, 80, 101, 64, 108, 108, 108, 0, 64, 127)), 6: ('Third and fifth - lean', (64, 85, 101, 0, 108, 108, 0, 0, 0, 64))}
+3/+4/+5/+7/+12 are 80/85/90/101/127 and -12 is 0; -3/-6/-9/-12 dB are 118/108/99/89 and off is 0; 14 cents is 71; Spread 0.5 and Mix 1 are 64.
- Type:
_component.macro_ofof the card’s settings
- reset()[source]
Empty the three lines, return their splices to a new node’s start, and restore patch 0 (or, under a rack, what the rack built this with).
- property tail_samples
The shifters’ lines, every one overwritten, and a block.
- property window_ms
The window the instance was built with, in milliseconds.