# SPDX-FileCopyrightText: 2026 Brad Barnett
#
# SPDX-License-Identifier: MIT
"""`RingMod` - Bode multiplier-type ring, with a switching character.
The player's text is the class docstring; the `CLAIMS` table in the class's
test file ties its claim sentences to tests.
"""
# Design notes, from the rebuild.
#
# `RingMod` — Bode multiplier-type ring, with a switching character.
#
# Rebuilt from scratch for Phase 3 against a dossier whose trait table was
# frozen at Station A before this file existed. The old `modulation.py:RingMod`
# is consulted only for the defects that dossier's section 7 names.
#
# What it sounds like. The program is multiplied by a carrier. At Depth 1
# the originals vanish and only the sum and difference remain. Depth 0.5 is
# textbook AM; Depth 0 is a wire. *Multiplier* (the default) is Bode's
# square-law ring: two sidebands. *Switching* is his chopper: odd harmonics of
# the carrier, truncated below Nyquist. Frequency is the oscillator the 6401
# never owned.
#
# Portability tier: audiodsp (`REQUIRES = ("audiomath",)`). On a stock
# CircuitPython board this module imports cleanly and construction raises
# `ImportError`.
#
# Cost: one Multiply plus a 256-point synthio Note (not a period-length
# RawSample). The 2026-09-08 extra-source row priced a 1964-frame looping
# table (and the fix round then capped that table at 24000 frames for M4's
# 2 Hz pair). Frequency is now `Note.frequency`, so the low end of the range
# does not allocate a longer buffer. Palette: Multiply 0.028 / 0.047 +
# extra synthio 256-point 0.317 / 0.408 + glue 0.0 →
# 0.345 / 0.455 ms → P4 ≤ 7 %, S3 ≤ 9 %. The old 3 % / 5 % bar
# used a 256-frame RawSample stand-in: the palette could not price a
# `synthio` source. The 18 % / 52 % bar counted the 1964-frame pull.
# This is a cheaper implementation of the same effect (design shape b1),
# not a §7.2 redefinition. No `" - lean"` patch.
#
# What the default surrenders: Default is the multiplier at Frequency
# 220 Hz, Depth 1, Mix 1 — not the switching standout and not W1's Shape 1.
# At that default, 3·f₂+f₁ sits at −92.2 dB (1 s rect, 48 kHz), not
# in W1's −9.5±3 dB window, so W1 is disconfirmed at the constructor
# default. Wet RMS is −9.03 dB vs the program (M2 disconfirmed): the
# Q15 product is −3.01 dB and the `synthio` voice sum (`>> 16`, A1/P12)
# takes another 6 dB. Squelch, Threshold and Release do not move the
# audio (M5 disconfirmed). Shape is a byte no-op until Character is
# flipped. Switching products at Character 1 Shape 1 are not a
# demonstrated row. Carrier Low's 5 Hz HPF is not a demonstrated
# claim (M4 disconfirmed): a same-kind plant moves the reading by
# 0.0022 dB at Frequency 220 and by 8.6 dB only at 2 Hz.
#
# Latency: zero samples, at every setting and every rate. Nothing looks
# ahead. No option adds latency (none of Frequency, Depth, Mix, Shape,
# Balance, Squelch, or Character delay the dry path). `tail_samples` is 0.
#
# Disconfirmed, not dropped. M2 (unity RMS via +3.01 dB wet makeup): Q15
# carrier cannot take ×√2 without clipping, which fails M1. W4 (switching
# unity RMS): peak-normalizing the Gibbs square to fit Q15 drops RMS; restoring
# it saturates and fails W2. M5 (squelch kills carrier leak): Balance is DC
# on the modulator, so a silent program is still a multiply-by-zero; there is
# no carrier residual to gate. W1 at the constructor default (Character 0):
# the switching products are absent — the row is disconfirmed there, not
# demonstrated at Character 1. M4 (Carrier Low 5 Hz: 2 Hz carrier
# 8.6±1.5 dB below 200 Hz): the same-kind plant is inert at Frequency
# 220 (0.0022 dB) and only fires when the carrier is turned down
# to 2 Hz (8.6 dB). Not a claim.
#
# `capabilities = ()`: the carrier is an audio-rate input on the standout.
# This class never reads `self._transport()`.
VENDOR = "PyDevices"
from array import array
import math
from . import _component
try:
import audiomath
except ImportError: # pragma: no cover - a stock board
audiomath = None
import synthio
FREQ, DEPTH, MIX, SHAPE, BAL, PBAL, SQUELCH, THRESH, RELEASE, CLOW, PHASE, CHAR = range(12)
Q15 = 32767
#: One carrier period as a short waveform. Rate is Note.frequency, not
#: this length over f_s. 256 is one palette block (~0.10 ms on the P4 as
#: an extra source) and is why 2 Hz no longer asks for 24000 frames.
TABLE_FRAMES = 256
TARGET_FRAMES = TABLE_FRAMES
MAX_CARRIER_FRAMES = TABLE_FRAMES
MAKEUP_DB = 3.010299956639812
DEPTH_WIRE = 1e-4
NYQUIST_FRAC = 0.45
def _clamp(value, lo, hi):
if value < lo:
return lo
if value > hi:
return hi
return value
def _q15(value):
sample = int(round(value * Q15))
if sample > Q15:
return Q15
if sample < -32768:
return -32768
return sample
[docs]
def carrier_gain(freq_hz, corner_hz):
"""First-order high-pass amplitude at `freq_hz` for corner `corner_hz`."""
freq_hz = abs(float(freq_hz))
corner_hz = max(float(corner_hz), 0.0)
if freq_hz < 1e-9:
return 0.0
return freq_hz / math.sqrt(freq_hz * freq_hz + corner_hz * corner_hz)
[docs]
def bandlimited_odd(phase, freq_hz, sample_rate, shape):
"""Sine at `shape` 0; odd-harmonic chopper truncated below 0.45·f_s at 1."""
sine = math.sin(phase)
shape = _clamp(float(shape), 0.0, 1.0)
if shape <= 1e-6:
return sine
nyquist = NYQUIST_FRAC * float(sample_rate)
acc = 0.0
harmonic = 1
while harmonic * freq_hz < nyquist - 1e-9:
acc += math.sin(harmonic * phase) / float(harmonic)
harmonic += 2
square = acc * 4.0 / math.pi
return (1.0 - shape) * sine + shape * square
[docs]
class RingMod(_component.Component):
"""A ring modulator after Harald Bode's: your signal is multiplied by a
carrier, so at Depth 1 the pitches you played vanish and only their sum
and difference with the carrier remain, metallic and out of key.
**Controls.** Frequency sets the carrier, and stops short of 0.45 times
the sample rate. Depth blends the carrier with a steady level: at 1
your signal is gone and the two sidebands come out level with each
other, at 0.5 it is textbook AM, your signal 6 dB over each sideband,
and at 0 the class is a wire. Mix sets the result against your signal,
and Mix 0 is a wire too. The Effect controls page lists what the knobs
span.
**Character and Shape.** Character switches the carrier from Bode's
multiplier to his switching chopper. Shape then moves the chopper from
a sine, where it sounds just like the multiplier, to a band-limited
square whose odd harmonics add sidebands of their own: at Shape 1 the
third harmonic's pair sits about 9.5 dB under the main pair. While
Character is on the multiplier, Shape does nothing.
**Letting your signal through.** Balance and Program Bal each add a
steady offset to the carrier, so your signal comes through under the
ring: at 0.5 it is level with each sideband, to within 0.5 dB. They do
the same thing.
**Stereo and the low end.** Stereo Phase shifts the right channel's
carrier against the left's, and at 0 the two channels match. Carrier
Low is a high-pass on the carrier and matters only with Frequency
turned down near it: at its default 5 Hz, a 2 Hz carrier comes out
about 8.6 dB under a 200 Hz one.
**Controls that do nothing.** Squelch, Threshold and Release do not
change the sound: the output is the same sample for sample wherever
they sit.
**Levels.** At Depth 1 the ring comes out about 9 dB under your
signal, and on every patch the output peaks at least 3 dB under the
input.
**Timing.** Latency is zero at every setting, and so is the tail:
silence in is silence out.
**On a board.** The class needs audiodsp's `audiomath`, and on a board
without it construction raises `ImportError`.
"""
NAME = "RingMod"
DISPLAY_NAME = "Ring Modulator"
CATEGORIES = ("Modulation",)
VERSION = "0.1.0"
TIER = _component.AUDIODSP
REQUIRES = ("audiomath",)
CAPABILITIES = ()
LATENCY_SAMPLES = 0
TAIL_SAMPLES = 0
MACRO_LABELS = (
"Frequency", "Depth", "Mix", "Shape", "Balance", "Program Bal",
"Squelch", "Threshold", "Release", "Carrier Low", "Stereo Phase",
"Character",
)
MACRO_MODES = {
0: "UNIPOLAR",
1: "UNIPOLAR",
2: "UNIPOLAR",
3: "UNIPOLAR",
4: "BIPOLAR",
5: "BIPOLAR",
6: "TOGGLE",
7: "UNIPOLAR",
8: "UNIPOLAR",
9: "UNIPOLAR",
10: "BIPOLAR",
11: "TOGGLE",
}
_MACRO_RANGES = (
(0.1, 8000.0, "log"),
(0.0, 1.0),
(0.0, 1.0),
(0.0, 1.0),
(-1.0, 1.0),
(-1.0, 1.0),
(0.0, 1.0),
(-72.0, 0.0),
(5.0, 500.0, "log"),
(2.0, 200.0, "log"),
(-180.0, 180.0),
(0.0, 1.0),
)
_MACRO_UNITS = {0: "Hz", 7: "dBFS", 8: "ms", 9: "Hz", 10: "degrees"}
PATCHES = {
0: ("Clean Ring", (87, 127, 127, 0, 64, 64, 127, 21, 64, 25, 64, 0)),
1: ("Textbook AM", (46, 64, 127, 0, 64, 64, 127, 21, 64, 25, 64, 0)),
2: ("Clangour", (108, 127, 127, 0, 64, 64, 127, 21, 64, 25, 64, 0)),
3: ("Bell Strike", (117, 127, 89, 0, 64, 64, 127, 21, 64, 25, 64, 0)),
4: ("Chopper", (108, 127, 127, 114, 64, 64, 127, 21, 64, 25, 64, 127)),
5: ("Soft Chopper", (93, 127, 102, 44, 64, 64, 127, 21, 64, 25, 64, 127)),
6: ("Detuned Ring", (87, 127, 127, 0, 73, 64, 0, 21, 64, 25, 64, 0)),
7: ("Wide Ring", (77, 127, 127, 0, 64, 64, 127, 21, 64, 25, 95, 0)),
8: ("Growl", (58, 76, 127, 0, 64, 64, 127, 21, 64, 25, 64, 0)),
}
FORCE_CHOPPER = False
FORCE_SINE = False
NO_MAKEUP = False
FORCE_MAKEUP = False
BYPASS_CARRIER_LOW = False
OPEN_GATE = False
ZERO_MOD = False
HARD_CHOPPER = False
SKIP_BALANCE = False
def _build(self, frequency=220.0, depth=1.0, mix=1.0, shape=0.0,
balance=0.0, program_bal=0.0, squelch=1.0, threshold_db=-60.0,
release_ms=50.0, carrier_low_hz=5.0, stereo_phase=0.0,
character=0.0, patch=None):
self._synth = None
self._note_l = None
self._note_r = None
self._carrier_frames = 0
self._mul = self._own(
audiomath.Multiply(
mix=1.0,
sample_rate=self._sample_rate,
channel_count=self._channel_count),
deinit=self._deinit_graph)
self._mul.play(self._source)
self._output = self._mul
self._init_macros(
(frequency, depth, mix, shape, balance, program_bal, squelch,
threshold_db, release_ms, carrier_low_hz, stereo_phase,
character),
patch)
def _deinit_graph(self):
self._note_l = None
self._note_r = None
synth = getattr(self, "_synth", None)
self._synth = None
if synth is not None:
release = getattr(synth, "release_all", None)
if release is not None:
release()
closer = getattr(synth, "deinit", None)
if closer is not None:
closer()
deinit = getattr(self._mul, "deinit", None)
if deinit is not None:
deinit()
def _value(self, index):
# This used to snap a BIPOLAR position within half a MIDI step of
# 64 to 0.5, because the plain 0-127 law put the panel centre at
# 64/127 and `program_change(0)` left Balance at 0.007874, which
# raised M1's residuals to -36 dB on the frozen material. The base
# has the centre detent now (audiocomponents#87), so 64 *is* 0.5 and
# the snap is not only redundant but wrong: under the new law MIDI
# 65 lands 0.508 of a step from 64 and the snap ate it, so one real
# click of the knob did nothing.
return _component.macro_value(self._MACRO_RANGES[index],
self._macros[index])
[docs]
def reset(self):
"""Clear every node, restore patch 0 and start the carrier again:
its notes on the modulating `synthio.Synthesizer` played on through
the walk, a block ahead, so patch 0 now builds a fresh one, as a
fresh instance does."""
self._check_live()
old = self._synth
self._synth = None
self._note_l = None
self._note_r = None
_component.Component.reset(self)
_component.release(old)
def _apply_macro(self, index, position):
del position
self._refresh()
def _clamp_hz(self, freq):
ceiling = float(self._sample_rate) * NYQUIST_FRAC
freq = float(freq)
if freq > ceiling:
return ceiling
if freq < 0.0:
return 0.0
return freq
def _refresh(self):
cls = type(self)
freq = self._clamp_hz(self._value(FREQ))
depth = self._value(DEPTH)
mix = self._value(MIX)
shape = self._value(SHAPE)
balance = 0.0 if cls.SKIP_BALANCE else self._value(BAL)
program_bal = self._value(PBAL)
corner = self._value(CLOW)
phase_deg = self._value(PHASE)
switching = self._value(CHAR) >= 0.5
if cls.FORCE_CHOPPER:
switching = True
shape = 1.0
if cls.FORCE_SINE:
switching = False
shape = 0.0
if not switching:
shape = 0.0
self._plant_chopper = bool(cls.FORCE_CHOPPER)
self._plant_sine = bool(cls.FORCE_SINE)
self._plant_flat_carrier = bool(cls.BYPASS_CARRIER_LOW)
self._plant_hard_chopper = bool(cls.HARD_CHOPPER)
self._plant_makeup = bool(cls.FORCE_MAKEUP)
self._plant_zero_mod = bool(cls.ZERO_MOD)
if depth <= DEPTH_WIRE or mix <= DEPTH_WIRE:
self._mul.set(mix=0.0)
return
self._mul.set(mix=mix)
self._rebuild_carrier(freq, depth, shape, program_bal, balance,
corner, phase_deg)
def _rebuild_carrier(self, freq, depth, shape, program_bal, balance,
corner, phase_deg):
cls = type(self)
fs = int(self._sample_rate)
channels = int(self._channel_count)
frames = TABLE_FRAMES
if cls.ZERO_MOD:
zeros = array("h", [0] * frames)
self._modulate_synth(max(freq, 1.0), zeros, zeros, channels)
self._carrier_frames = frames
return
hpf = 1.0
if freq >= 0.05 and not cls.BYPASS_CARRIER_LOW:
hpf = carrier_gain(freq, corner)
phase_r = 0.0 if channels == 1 else (
float(phase_deg) * math.pi / 180.0)
makeup = 1.0
switching = self._value(CHAR) >= 0.5 or cls.FORCE_CHOPPER
if cls.FORCE_SINE:
switching = False
if switching:
if cls.FORCE_MAKEUP and not cls.NO_MAKEUP:
makeup = 10.0 ** (MAKEUP_DB / 20.0)
elif not cls.NO_MAKEUP:
# Q15 product cannot exceed unity; FORCE_MAKEUP clips the table
# (the M2 fault). The clean class leaves makeup at 1.
if cls.FORCE_MAKEUP:
makeup = 10.0 ** (MAKEUP_DB / 20.0)
depth = _clamp(float(depth), 0.0, 1.0)
dc = float(program_bal)
bleed = float(balance)
wave_l = array("h")
wave_r = array("h")
lefts = []
rights = []
peak = 1e-12
for index in range(frames):
if freq < 0.05:
osc_l = 1.0
osc_r = 1.0
else:
phase = 2.0 * math.pi * index / float(frames)
if cls.HARD_CHOPPER:
osc_l = 1.0 if math.sin(phase) >= 0.0 else -1.0
osc_r = 1.0 if math.sin(phase + phase_r) >= 0.0 else -1.0
else:
osc_l = bandlimited_odd(phase, freq, fs, shape)
osc_r = bandlimited_odd(phase + phase_r, freq, fs, shape)
osc_l *= hpf
osc_r *= hpf
left = (1.0 - depth) + depth * osc_l
lefts.append(left)
if abs(left) > peak:
peak = abs(left)
if channels != 1:
right = (1.0 - depth) + depth * osc_r
rights.append(right)
if abs(right) > peak:
peak = abs(right)
scale = 1.0 / peak if peak > 1.0 else 1.0
for left in lefts:
wave_l.append(_q15(left * scale * makeup + dc + bleed))
if channels != 1:
for right in rights:
wave_r.append(_q15(right * scale * makeup + dc + bleed))
played = freq if freq >= 0.05 else 1.0
self._modulate_synth(played, wave_l, wave_r, channels)
self._carrier_frames = frames
def _modulate_synth(self, freq, wave_l, wave_r, channels):
synth = self._synth
if synth is None:
synth = synthio.Synthesizer(
sample_rate=self._sample_rate, channel_count=channels)
if channels == 1:
note_l = synthio.Note(frequency=freq, waveform=wave_l)
synth.press(note_l)
self._note_l = note_l
self._note_r = None
else:
# CPython synthio pans +1 to the left column and -1 to the
# right (scaled panning in synthio.py). Native builds match.
note_l = synthio.Note(
frequency=freq, waveform=wave_l, panning=1.0)
note_r = synthio.Note(
frequency=freq, waveform=wave_r, panning=-1.0)
synth.press((note_l, note_r))
self._note_l = note_l
self._note_r = note_r
self._synth = synth
self._mul.modulate(synth)
return
self._note_l.waveform = wave_l
self._note_l.frequency = freq
if self._note_r is not None:
self._note_r.waveform = wave_r
self._note_r.frequency = freq