# SPDX-FileCopyrightText: 2026 Brad Barnett
#
# SPDX-License-Identifier: MIT
"""`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`.
"""
VENDOR = "PyDevices"
import math
import audiocore
from . import _component
try:
import audiodelays
import audiomixer
import audioroute
except ImportError: # pragma: no cover - a stock board
audiodelays = audiomixer = audioroute = None
PITCH_I = 0
VOICE_I = (1, 2, 3)
LEVEL_I = (4, 5, 6)
DETUNE_I = 7
SPREAD_I = 8
MIX_I = 9
#: Frames a mixer pull hands out, and so what every node and tap takes per
#: pull.
BLOCK = 256
#: 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.
LEVEL_TOP_DB = 0.0
LEVEL_FLOOR_DB = -40.0
LEVEL_OFF_DB = LEVEL_FLOOR_DB - (LEVEL_TOP_DB - LEVEL_FLOOR_DB) / 126.0
DETUNE_MAX_CENTS = 25.0
WINDOW_MIN_MS = 5.0
WINDOW_MAX_MS = 60.0
#: 1024 frames at 48 kHz.
WINDOW_DEFAULT_MS = 1024.0 / 48.0
#: The constructor's macro defaults, which NaN falls back to (patch 0).
DEFAULTS = (0.0, 4.0, 7.0, -12.0, -6.0, -6.0, -9.0, 0.0, 0.0, 1.0)
#: The shifter reads its line at `floor(256 * 2^(semitones / 12))` 256ths
#: of a frame per frame.
STEPS = 256
[docs]
def ratio_step(semitones):
"""The shifter's nearest read-rate step, in 256ths, to an interval."""
return int(math.floor(STEPS * 2.0 ** (semitones / 12.0) + 0.5))
[docs]
def step_semitones(step):
"""The interval at the centre of read-rate step `step`: the node's
floor lands on `step` from it, with half a step to spare either way,
in single precision as in double."""
return 12.0 * math.log((step + 0.5) / STEPS) / math.log(2.0)
[docs]
def whole(value):
"""A Pitch or Voice value as the whole semitone it plays."""
return int(math.floor(value + 0.5))
[docs]
def mix_gains(mix):
"""(dry, voice) gain at Mix `mix`: the dry at unity up to 1, then
2 - Mix; each voice at Mix, capped at 1."""
mix = min(2.0, max(0.0, mix))
return (1.0 if mix <= 1.0 else 2.0 - mix), min(mix, 1.0)
[docs]
def level_gain(db):
"""A Level in dB as a gain; 0 for the bottom step, which is off."""
if db < LEVEL_FLOOR_DB:
return 0.0
return 10.0 ** (db / 20.0)
def _number(value, default):
try:
value = float(value)
except (TypeError, ValueError):
raise ValueError("expected a number, not %r" % (value,))
if value != value:
return default
return value
[docs]
class Harmonizer(_component.Component):
"""Three 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_samples` covers 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'
DISPLAY_NAME = 'Harmonizer'
CATEGORIES = ('Pitch Shift',)
VERSION = '0.1.0'
TIER = _component.AUDIODSP
REQUIRES = ("audioroute",)
CAPABILITIES = ()
LATENCY_SAMPLES = 0
TAIL_SAMPLES = None
#: 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).
INPUT_CEILING_DBFS = -12.1
MACRO_LABELS = ("Pitch", "Voice 1", "Voice 2", "Voice 3", "Level 1",
"Level 2", "Level 3", "Detune", "Spread", "Mix")
MACRO_MODES = {0: "BIPOLAR", 1: "BIPOLAR", 2: "BIPOLAR", 3: "BIPOLAR",
4: "UNIPOLAR", 5: "UNIPOLAR", 6: "UNIPOLAR",
7: "UNIPOLAR", 8: "UNIPOLAR", 9: "UNIPOLAR"}
_MACRO_RANGES = (
(-12.0, 12.0), # 0 Pitch, semitones
(-12.0, 12.0), # 1 Voice 1, semitones
(-12.0, 12.0), # 2 Voice 2
(-12.0, 12.0), # 3 Voice 3
(LEVEL_OFF_DB, LEVEL_TOP_DB), # 4 Level 1, dB; MIDI 0 = off
(LEVEL_OFF_DB, LEVEL_TOP_DB), # 5 Level 2
(LEVEL_OFF_DB, LEVEL_TOP_DB), # 6 Level 3
(0.0, DETUNE_MAX_CENTS), # 7 Detune, cents
(0.0, 1.0), # 8 Spread
(0.0, 2.0), # 9 Mix; dry at unity to 1
)
_MACRO_UNITS = {
0: "semitones", 1: "semitones", 2: "semitones", 3: "semitones",
4: "dB", 5: "dB", 6: "dB", 7: "cents",
}
#: `_component.macro_of` of the card's settings: +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.
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)),
}
def _build(self, pitch=0.0, voice1=4.0, voice2=7.0, voice3=-12.0,
level1_db=-6.0, level2_db=-6.0, level3_db=-9.0,
detune_cents=0.0, spread=0.0, mix=1.0,
window_ms=WINDOW_DEFAULT_MS, patch=None):
grid = self._grid((pitch, voice1, voice2, voice3, level1_db,
level2_db, level3_db, detune_cents, spread, mix))
window_ms = _number(window_ms, WINDOW_DEFAULT_MS)
self._window_ms = min(WINDOW_MAX_MS, max(WINDOW_MIN_MS, window_ms))
rate = self._sample_rate
channels = self._channel_count
self._ready = False
self._armed = False
#: Which voices play their shifter; the others play their tap, silenced.
self._on = [True, True, True]
self._puller = None
# The borrowed source's only reader: a width-1 MidSide is the source
# byte for byte, in whole 256-frame blocks whatever buffers the
# source hands out. At Mix 0 the output is this node, and the
# Splitter reads it too, so routing around the graph and back never
# skips or repeats a source frame.
self._head = self._own(audioroute.MidSide(
self._source, width=1.0, sample_rate=rate,
channel_count=channels), reset=False)
# A MidSide with no source hands out one block of zeros per pull.
# The Splitter reads it while the voices are armed (`_arm`), so
# arming takes nothing from the source.
self._hush = self._own(audioroute.MidSide(
width=1.0, sample_rate=rate, channel_count=channels),
reset=False)
self._in = self._own(audioroute.Port(self._hush), reset=False)
split = self._own(audioroute.Splitter(self._in, taps=4),
reset=False)
self._taps = [split.tap(i) for i in range(4)]
# Three shifters, each on its own tap: each voice is its own
# machine, with its own line and its own splice rate.
frames = self._window_frames()
self._frames = frames
self._overlap = frames // 16
self._shifters = []
for k in range(3):
shifter = self._own(self._shifter(frames, self._overlap))
shifter.play(self._taps[k + 1], loop=True)
self._shifters.append(shifter)
# Each mixer voice plays a Port, so switching a voice between its
# shifter and its silenced tap re-points the port and primes nothing.
self._ports = [self._own(audioroute.Port(self._taps[0]),
reset=False)]
for k in range(3):
self._ports.append(self._own(audioroute.Port(self._shifters[k]),
reset=False))
# What a voice that is off plays: its tap, held at level 0 for good.
self._drains = []
self._feeds = []
for k in range(3):
feed = self._own(audioroute.Port(self._hush), reset=False)
drain = self._own(audiomixer.Mixer(
voice_count=1, **self._pcm(1024 * channels)), reset=False)
drain.voice[0].level = 0.0
drain.voice[0].play(feed, loop=True)
# Its play() primed a block of the hush; one pull drops it, so
# the drain holds nothing when it first reads its tap.
drop = audiomixer.Mixer(voice_count=1, **self._pcm(16))
drop.voice[0].play(drain)
drop.voice[0].stop()
drop.deinit()
self._feeds.append(feed)
self._drains.append(drain)
# Not reset by the walk: no voice holds a block between two pulls.
self._mixer = self._own(audiomixer.Mixer(
voice_count=4, **self._pcm(1024 * channels)), reset=False)
# A voice's play() primes a block; with the Splitter on the hush it
# is zeros, and one pull drops it.
for i in range(4):
self._mixer.voice[i].play(self._ports[i], loop=True)
# The output: a width-1 MidSide, byte for byte, whose reset forwards
# nothing, so a host's reset of the output never reaches the Mixer.
self._tail = self._own(audioroute.MidSide(
self._mixer, width=1.0, sample_rate=rate,
channel_count=channels), reset=False)
self._output = self._tail
self._pull()
self._init_macros(tuple(
_component.macro_value(self._MACRO_RANGES[i],
_component.position_of_midi(
self._mode(i), grid[i]))
for i in range(10)))
# Land each knob exactly on its step, as patch 0 does.
for i in range(10):
self._macros[i] = _component.position_of_midi(self._mode(i),
grid[i])
# A constructor patch lands before the voices are first armed, so
# their level gates open at the patch's levels.
if patch is not None:
self.program_change(patch)
self._ready = True
self._refresh()
def _grid(self, asked):
"""Each constructor value as its knob's nearest MIDI step: NaN is
the default, anything past a stop is that stop, and a Level below
-40 dB is off."""
grid = []
for i in range(10):
value = _number(asked[i], DEFAULTS[i])
span = self._MACRO_RANGES[i]
if i in LEVEL_I and value < LEVEL_FLOOR_DB:
grid.append(0)
continue
low = LEVEL_FLOOR_DB if i in LEVEL_I else span[0]
value = min(span[1], max(low, value))
grid.append(_component.macro_of(span, value, self._mode(i)))
return grid
# -- the parts; each a method, so a test can plant a fault in one -----
def _window_frames(self):
"""The window in frames, from milliseconds at the running rate."""
return max(1, int(self._window_ms * self._sample_rate / 1000.0
+ 0.5))
def _shifter(self, frames, overlap):
width = 2 * self._channel_count
return audiodelays.PitchShift(
semitones=0.0, mix=1.0, window=frames * width,
overlap=overlap * width, **self._pcm(BLOCK * width))
def _voice_source(self, k):
"""What voice `k` (0, 1, 2) plays while it is on: its shifter."""
return self._shifters[k]
def _off_source(self, k):
"""What voice `k` plays while it is off: its tap through a
one-voice mixer that has only ever been at level 0. The voice reads
the tap, which keeps the split even and does not pull its shifter,
and plays silence from the first frame; the bare tap would play the
dry at the voice's old level until the voice's level gate closed.
The mixer's own voice never plays again, so nothing is primed from
the live tap when a voice goes off."""
self._feeds[k].play(self._taps[k + 1])
return self._drains[k]
def _empty(self, k):
"""Empty voice `k`'s line before it comes back on."""
audiocore.reset_buffer(self._shifters[k])
def _semitones(self, k):
"""What voice `k` (0, 1, 2) asks for: Pitch + Voice + its share of
Detune (voice 1 down, voice 2 up, voice 3 none)."""
detune = self._value(DETUNE_I) / 100.0
share = (-detune, detune, 0.0)[k]
return (whole(self._value(PITCH_I))
+ whole(self._value(VOICE_I[k])) + share)
def _node_semitones(self, asked):
"""The nearest step the node can play, handed over at its centre."""
return step_semitones(ratio_step(asked))
def _level(self, k):
return level_gain(self._value(LEVEL_I[k]))
def _dry_level(self):
return mix_gains(self._value(MIX_I))[0]
def _voice_level(self, k):
return self._level(k) * mix_gains(self._value(MIX_I))[1]
def _pans(self):
spread = min(1.0, max(0.0, self._value(SPREAD_I)))
return (0.0, -spread, spread, 0.0)
# -- the controls ----------------------------------------------------
def _value(self, index):
return _component.macro_value(self._MACRO_RANGES[index],
self._macros[index])
def _apply_macro(self, index, position):
del index, position
if self._ready:
self._refresh()
def _apply_positions(self, positions, patch_index):
"""Apply a patch (or a rack's restore) whole, then set the graph
once."""
ready = self._ready
self._ready = False
try:
_component.Component._apply_positions(self, positions,
patch_index)
finally:
self._ready = ready
if ready:
self._refresh()
[docs]
def reset(self):
"""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)."""
self._check_live()
self._clear_nodes()
self._stranded = False
# The voices are armed again, as the constructor arms them, the
# next time the output reaches the mixer.
self._armed = False
if self._reset_to is None:
self.program_change(0)
else:
self._restore(self._reset_to)
def _refresh(self):
for k in range(3):
self._shifters[k].semitones = self._node_semitones(
self._semitones(k))
self._route()
def _wanted(self, k):
return self._level(k) > 0.0
def _levels(self):
voices = self._mixer.voice
pans = self._pans()
voices[0].level = self._dry_level()
for k in range(3):
voices[k + 1].level = self._voice_level(k)
if self._channel_count == 2:
for i in range(4):
voices[i].panning = pans[i]
def _route(self):
"""Mix 0 hands out the source; anything else plays the mixer, armed
again if the graph was left or reset."""
if self._macros[MIX_I] <= 0.0:
self._route_around(self._head)
return
if self._rejoin() or not self._armed:
self._arm()
else:
self._switch()
self._output = self._tail
def _switch(self):
"""Turn voices on and off. A voice going off plays its tap through
a mixer held at level 0, so the split stays even, its shifter is
not pulled and the dry never leaks at the voice's old level; a
voice coming back empties its shifter's line, plays it, then takes
its level."""
voices = self._mixer.voice
for k in range(3):
wanted = self._wanted(k)
if wanted == self._on[k]:
continue
if wanted:
self._empty(k)
self._ports[k + 1].play(self._voice_source(k))
else:
voices[k + 1].level = 0.0
self._ports[k + 1].play(self._off_source(k))
self._on[k] = wanted
self._levels()
def _arm(self):
"""Arm the voices, the same way every time: with the Splitter on
the hush and every voice on its shifter, one pull of the mixer opens
the voices' level gates on zeros and leaves no voice and no shifter
holding a block. Then every line is emptied, which also puts its
splice where a new node's starts, the Splitter goes back to the
source and the voices that are off go to their taps. So a reset, a
return from Mix 0 and a voice turned back on all start their
shifters exactly as the constructor does."""
self._levels()
self._in.play(self._hush)
for k in range(3):
self._ports[k + 1].play(self._voice_source(k))
self._pull()
for k in range(3):
audiocore.reset_buffer(self._shifters[k])
self._in.play(self._head)
for k in range(3):
self._on[k] = self._wanted(k)
if not self._on[k]:
self._ports[k + 1].play(self._off_source(k))
self._armed = True
def _pull(self):
"""Pull one block from the mixer and drop it.
Where `audiocore.get_buffer` is compiled out (CircuitPython's
default board builds), a voice of a one-voice mixer of our own
plays `_tail` and stops: its `play()` primes one block, which pulls
the mixer once. `_tail` forwards no reset, so the play rewinds
nothing behind it."""
pull = getattr(audiocore, "get_buffer", None)
if pull is not None:
pull(self._mixer)
return
if self._puller is None:
# Nothing ever pulls this mixer, so its own buffers are the
# smallest that hold a stereo frame.
self._puller = self._own(audiomixer.Mixer(
voice_count=1, **self._pcm(16)), reset=False)
voice = self._puller.voice[0]
voice.play(self._tail)
voice.stop()
@property
def tail_samples(self):
"""The shifters' lines, every one overwritten, and a block."""
self._check_live()
return self._tail_bound()
def _tail_bound(self):
if self._macros[MIX_I] <= 0.0:
return 0
if not (self._wanted(0) or self._wanted(1) or self._wanted(2)):
return 0
return self._frames + self._overlap + BLOCK
@property
def window_ms(self):
"""The window the instance was built with, in milliseconds."""
self._check_live()
return self._window_ms