# SPDX-FileCopyrightText: 2026 Brad Barnett
#
# SPDX-License-Identifier: MIT
"""`AutoPan` - an auto-panner: a pan law under an LFO.
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. Traits frozen 2026-09-08 at Station A before this file
# existed; Rate span re-frozen 2026-09-08 in the fix round (vision 7.2).
# Grade design: the three published centre-attenuation conventions (3.01 /
# 4.5 / 6.02 dB), a per-sample oscillator, and a mono wire.
#
# One processing node: source -> audiomath.Multiply. The modulator is a
# synthio.Synthesizer with two Notes (left / right gain) whose waveform is
# one period of the pan law. Rate is the notes' frequency, so the pull is
# one block of oscillator, not a whole-period RawSample. Depth 0 is
# mix = 0, the bit-exact wire (audiodsp_multiply.c wet/dry pair). A mono
# source gets no node: `output` is the borrowed source.
#
# The Mixer + synthio.LFO route the old class used is rejected: it is not a
# published pan law, it is block-rate, and on CPython it does not move.
#
# What the default surrenders: Rate starts at 2 Hz, not a slow 0.05 Hz
# wander - a 256-frame hold at 0.05 Hz reads under -80 dB, so A3's plant
# cannot fire on the old floor. The oscillator is two synthio Notes, which
# top out at half scale (P12): hard-over is -6 dB against the source.
#
# Cost: one Multiply plus a 1500-point synthio pair. Palette: Multiply
# 0.028 / 0.047 + extra synthio 1500 0.263 / 0.472 + glue 0.0 -> 0.291 /
# 0.519 ms -> P4 <= 6 %, S3 <= 10 %. The old 1 % / 1 % bar counted Multiply
# only: the palette could not price a synthio source. Quoted class ROW
# 2.5 % / 4.5 %. No " - lean" patch.
VENDOR = "PyDevices"
import math
from array import array
from . import _component
try:
import audiomath
except ImportError:
audiomath = None
import synthio
[docs]
class AutoPan(_component.Component):
"""An auto-panner: an LFO sweeps your signal between the speakers, with
a new pan position on every sample, under a pan law.
**The controls.** Rate is the sweep's speed. Depth is how far it
swings: at Depth 1 it reaches each side, where the far speaker is
silent, and at Depth 0 the output is the input. Shape runs the sweep
from a triangle at 0 to a sine at 1. Law is how far the centre dips; at
3.01 dB the power holds steady across the sweep. Centre moves the
middle of the sweep towards one side. Phase moves where the sweep
starts: at 0 it starts on the left. With Sync on, Rate snaps to the
nearest of one, two, four or eight sweeps a beat of the host's tempo;
with no host tempo, Rate stays where the knob is. The Effect controls
page lists what the knobs span.
**Levels.** The sweep sits 6 dB under your source: hard over, the near
speaker plays it at half level. A mono source passes untouched, and
silence in is silence out.
**Timing.** Latency is zero at every setting, and so is the tail:
nothing looks ahead and nothing rings on.
**On a board.** The class needs audiodsp's `audiomath`, and on a board
without it construction raises `ImportError`.
"""
NAME = 'AutoPan'
DISPLAY_NAME = 'Auto Pan'
CATEGORIES = ('Modulation',)
VERSION = '0.1.0'
TIER = _component.AUDIODSP
REQUIRES = ("audiomath",)
CAPABILITIES = ("tempo_sync",)
_SYNC_MACRO = 6
LATENCY_SAMPLES = 0
TAIL_SAMPLES = 0
#: One LFO period as a short waveform. Rate is the note frequency, not
#: this length over f_s. 1500 makes the synthio DDS exact at 2 / 5 / 20 Hz
#: on 48 kHz (375 × 4; A6 extremes land on samples).
TABLE_FRAMES = 1500
#: Centre attenuation of the constant-power law, 10*log10(2) dB.
LAW_POWER_DB = 10.0 * math.log10(2.0)
#: Centre attenuation of the linear / mono-safe law, 20*log10(2) dB.
LAW_LINEAR_DB = 20.0 * math.log10(2.0)
#: Beats per pan cycle when Sync is on, longest first. At 120 BPM these
#: are 2-16 Hz, covering the Rate span without leaving it.
SYNC_BEATS = (1.0, 0.5, 0.25, 0.125)
MACRO_LABELS = ("Rate", "Depth", "Shape", "Law", "Centre", "Phase", "Sync")
MACRO_MODES = {
0: "UNIPOLAR",
1: "UNIPOLAR",
2: "UNIPOLAR",
3: "UNIPOLAR",
4: "BIPOLAR",
5: "BIPOLAR",
6: "TOGGLE",
}
_MACRO_RANGES = (
(2.0, 20.0, "log"),
(0.0, 1.0),
(0.0, 1.0),
(LAW_POWER_DB, LAW_LINEAR_DB),
(-1.0, 1.0),
(-180.0, 180.0),
(0.0, 1.0),
)
_MACRO_UNITS = {0: "Hz", 3: "dB", 5: "degrees"}
PATCHES = {
0: ("Slow Sweep", (0, 127, 127, 0, 64, 64, 0)),
1: ("Quarter Note", (0, 102, 0, 0, 64, 64, 127)),
2: ("Wide Triangle", (38, 127, 0, 0, 64, 64, 0)),
3: ("Narrow Drift", (0, 44, 127, 0, 64, 64, 0)),
4: ("Mono-Safe Sweep", (38, 127, 127, 127, 64, 64, 0)),
5: ("Offset Left", (0, 64, 127, 0, 38, 64, 0)),
6: ("Fast Flutter", (69, 89, 0, 0, 64, 64, 0)),
7: ("Quarter Offset", (0, 127, 127, 0, 64, 95, 127)),
}
def _build(self, rate=2.0, depth=1.0, shape=1.0, law_db=None,
centre=0.0, phase=0.0, sync=0.0, patch=None):
"""No latency-adding option exists; `latency_samples` is 0 ms at
48 kHz at every setting."""
if law_db is None:
law_db = type(self).LAW_POWER_DB
self._table = None
self._q15 = None
self._wave_l = None
self._wave_r = None
self._synth = None
self._note_l = None
self._note_r = None
self._node = None
if self._channel_count == 1:
self._output = self._source
else:
node = audiomath.Multiply(
sample_rate=self._sample_rate,
channel_count=self._channel_count, mix=1.0)
node.play(self._source)
def _release():
stop = getattr(node, "deinit", None)
if stop is not None:
stop()
synth = self._synth
self._synth = None
self._note_l = None
self._note_r = None
if synth is not None:
closer = getattr(synth, "deinit", None)
if closer is not None:
closer()
table = self._table
self._table = None
if table is not None:
closer = getattr(table, "deinit", None)
if closer is not None:
closer()
self._node = self._own(node, deinit=_release)
self._output = node
self._init_macros((rate, depth, shape, law_db, centre, phase, sync),
patch)
[docs]
def reset(self):
"""Clear every node, restore patch 0 and start the LFO again: the
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
if self._node is None:
if index in (0, 6) and self._macros[6] >= 0.5:
self._transport()
return
self._rebuild_table()
def _synced_rate(self, rate_hz):
if self._macros[6] < 0.5:
return rate_hz
transport = self._transport
playing, _position, bpm, _num, _den = transport()
del playing
bpm = float(bpm) if bpm else 120.0
if transport is _component.static_transport:
return rate_hz
beats = type(self).SYNC_BEATS
candidates = [bpm / (60.0 * b) for b in beats]
nearest = candidates[0]
best = abs(nearest - rate_hz)
for hz in candidates[1:]:
error = abs(hz - rate_hz)
if error < best:
nearest, best = hz, error
return nearest
def _macro_engineering(self):
cls = type(self)
rate_hz = _component.macro_value(cls._MACRO_RANGES[0], self._macros[0])
depth = _component.macro_value(cls._MACRO_RANGES[1], self._macros[1])
shape = _component.macro_value(cls._MACRO_RANGES[2], self._macros[2])
law_db = _component.macro_value(cls._MACRO_RANGES[3], self._macros[3])
centre = _component.macro_value(cls._MACRO_RANGES[4], self._macros[4])
phase_deg = _component.macro_value(cls._MACRO_RANGES[5], self._macros[5])
# MIDI 64 on a bipolar ±1 / ±180 span is 0.008 / 1.4°, not 0. Snap
# that one step so constructor Centre/Phase 0 and patch 0 are the
# same table (A6's hard-over lands on a sample).
if abs(centre) < 1.0 / 64.0:
centre = 0.0
if abs(phase_deg) < 180.0 / 64.0:
phase_deg = 0.0
return (self._synced_rate(rate_hz), depth, shape, law_db, centre,
phase_deg)
def _bake_period(self, frames, depth, shape, law_db, centre, phase_deg):
cls = type(self)
forced = getattr(cls, "FORCED_EXPONENT", None)
exponent = (law_db / cls.LAW_POWER_DB) if forced is None else forced
two_pi = 2.0 * math.pi
phase0 = phase_deg / 360.0
wave_l = array("h")
wave_r = array("h")
interleaved = array("h")
append_l = wave_l.append
append_r = wave_r.append
append = interleaved.append
cap = getattr(cls, "DEPTH_CAP", None)
if cap is not None and depth > cap:
depth = cap
never_zero = bool(getattr(cls, "NEVER_ZERO", False))
for index in range(frames):
phase = (index / float(frames) + phase0) % 1.0
triangle = 1.0 - 4.0 * abs(phase - 0.5)
sine = -math.cos(two_pi * phase)
lfo = triangle + shape * (sine - triangle)
pan = centre + depth * lfo
if getattr(cls, "FAULT", None) == "mixer":
pan = max(-1.0, min(1.0, pan))
if pan >= 0.0:
left, right = 1.0, 1.0 - pan
else:
left, right = 1.0 + pan, 1.0
elif pan <= -1.0:
left, right = 1.0, 0.0
elif pan >= 1.0:
left, right = 0.0, 1.0
else:
theta = (pan + 1.0) * (math.pi * 0.25)
left = math.cos(theta) ** exponent
right = math.sin(theta) ** exponent
q_l = _q15(left)
q_r = _q15(right)
if never_zero:
# synthio notes top out at half scale (P12); 1 LSB in the
# waveform is 0 in the PCM and the plant would go green.
floor = int(getattr(cls, "NEVER_ZERO_LSB", 16))
if q_l < floor:
q_l = floor
if q_r < floor:
q_r = floor
append_l(q_l)
append_r(q_r)
append(q_l)
append(q_r)
return wave_l, wave_r, interleaved
def _rebuild_table(self):
if self._node is None:
return
rate_hz, depth, shape, law_db, centre, phase_deg = (
self._macro_engineering())
if depth <= 0.0:
self._node.set(mix=0.0)
return
self._node.set(mix=1.0)
hold = getattr(type(self), "HOLD", None)
if hold:
frames = int(self._sample_rate / rate_hz)
frames = max(4, frames - (frames % 4))
_wave_l, _wave_r, raw = self._bake_period(
frames, depth, shape, law_db, centre, phase_deg)
held = array("h")
period = len(raw) // 2
for index in range(period):
src = min((index // hold) * hold, period - 1)
held.append(raw[src * 2])
held.append(raw[src * 2 + 1])
self._q15 = held
self._modulate_raw(held)
return
frames = type(self).TABLE_FRAMES
wave_l, wave_r, interleaved = self._bake_period(
frames, depth, shape, law_db, centre, phase_deg)
self._q15 = interleaved
self._wave_l = wave_l
self._wave_r = wave_r
self._modulate_synth(rate_hz, wave_l, wave_r)
def _modulate_raw(self, values):
import audiocore
sample = audiocore.RawSample(
values, sample_rate=self._sample_rate, channel_count=2)
previous = self._table
self._table = sample
self._node.modulate(sample)
if previous is not None:
closer = getattr(previous, "deinit", None)
if closer is not None:
closer()
def _modulate_synth(self, rate_hz, wave_l, wave_r):
synth = self._synth
if synth is None:
synth = synthio.Synthesizer(
sample_rate=self._sample_rate, channel_count=2)
# Since CircuitPython 10.3.0, panning > 0 attenuates the LEFT
# channel, so -1 lands a note on the left column alone and +1 on
# the right, on every target (audiodsp 4ec5718). The pre-10.3.0
# pairing was the reverse and put each gain on the wrong side.
#
# A fresh note renders at level 0 until its output crosses zero
# (the same 10.3.0 change), and a gain table never does, so left
# alone the first block is silent and the gain then steps in -
# a click on whatever is already playing. The notes start on a
# silent waveform for one block, which opens the gate at its
# first sample (see `_component.open_level_gates`), and take
# their tables after it.
silent = array("h", bytes(2 * len(wave_l)))
note_l = synthio.Note(
frequency=rate_hz, waveform=silent, panning=-1.0)
note_r = synthio.Note(
frequency=rate_hz, waveform=silent, panning=1.0)
synth.press((note_l, note_r))
import audiocore
pull = getattr(audiocore, "get_buffer", None)
if pull is not None:
pull(synth)
note_l.waveform = wave_l
note_r.waveform = wave_r
self._synth = synth
self._note_l = note_l
self._note_r = note_r
self._node.modulate(synth)
return
self._note_l.waveform = wave_l
self._note_r.waveform = wave_r
self._note_l.frequency = rate_hz
self._note_r.frequency = rate_hz
def _q15(gain):
if gain <= 0.0:
return 0
if gain >= 1.0:
return 32767
return int(gain * 32767.0 + 0.5)