Source code for audioeffects.phaser

# SPDX-FileCopyrightText: 2026 Brad Barnett
#
# SPDX-License-Identifier: MIT

"""`Phaser` - four first-order all-pass stages swept the way a Phase 90 is.

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.
#
# Rebuilt from scratch for Phase 3 against its dossier, traits frozen at
# Station A on 2026-09-08 before this file existed. The old
# `modulation.py:Phaser` is not consulted except for the eight defects the
# dossier's section 7 names.
#
# What it sounds like. Two notches a fixed ratio apart (one per pair of
# stages) slide up and down together on a triangle, linear in hertz, never
# deeper than the 24 kΩ that sits across the JFET. Mix 0.5 is the script
# logo's equal sum, where those notches are holes; Feedback is the later
# block-logo resistor, a mid hump between them. Drive is a cubic into the
# cascade, a proxy for the JFET living inside the stage - it is not the
# channel's `v_ds` in the coefficient.
#
# The drive table fills int16, and the scale is carried in `post_gain`.
# `y = x - x3/3` peaks at 2/3 by construction, so a table holding it
# directly used 66.7 % of the range and threw away half a bit of the only
# resolution a lookup table has (audiocomponents#77). `CURVE_SCALE` is that
# 2/3, it goes into the shaper's `post_gain`, and the class's level does not
# move: measured, identical wet RMS and identical peak at -26, -14 and -6
# dBFS. It is generated by `tools/curves/phaser_curve.py`, which refuses a
# table under 95 % of the range.
#
# What the default surrenders: Drive 0.3 is on at construction. Feedback's
# inter-notch peak then misses the 5 dB bar (600–1800 Hz rise −0.633 dB at
# 48 kHz) and the notch floor is not monotone (0.5→0.7 −1.204 dB). Both hold
# at Drive 0. The floor's 0.5→0.7 step also deepens at 22.05 kHz with Drive 0
# (−1.286 dB).
#
# Patch 8 is `Phaser - lean`: Drive 0, AllPass only.
#
# Portability tier: audiodsp (`REQUIRES = ("audiobiquad", "audioshaper")`).
# The ported `audiofilters.Phaser` holds a DC residue after silence and will
# not take feedback 0 (dossier B.1, F.1, F.4). On a stock CircuitPython board
# this module imports and construction raises `ImportError`.
#
# Cost: AllPass-6 0.248 / 0.423 + Waveshaper ×1 0.223 / 0.410 +
# extra synthio 256-point 0.317 / 0.408 + glue 0.0 →
# 0.788 / 1.241 ms → P4 ≤ 15 %, S3 ≤ 24 %. The old 9 % / 16 % bar
# omitted the LFO: the palette could not price a `synthio` source. Lean
# patch 8 is AllPass alone → 5 / 8 %. Both figures predate the input
# guard (an `audiofilters.Filter` with no filter, a block copy), which keeps
# a Drive or Mix move from replaying the source: on the desktop it adds about
# 1 µs to a 19 µs block. The boards are not re-taken with it yet.
#
# Latency: zero samples at every setting. Drive is `oversample=1` (group
# delay 0). No lookahead, partition or window is offered, so there is no
# latency-adding option to default off and none to name in milliseconds.
#
# `capabilities = ("tempo_sync",)`: Sync on reads `self._transport()` and
# locks Rate to Division in bars of the host's time signature (numerator x 4
# / denominator quarter notes), and `transport_changed()` follows a move of
# the tempo or the time signature.
#
# This class lives in `phaser.py` and is what the package serves.

VENDOR = "PyDevices"

from array import array
import math

from . import _component

try:
    import audiobiquad
except ImportError:                     # pragma: no cover - a stock board
    audiobiquad = None

try:
    import audioshaper
except ImportError:                     # pragma: no cover - a stock board
    audioshaper = None

import audiofilters
import synthio


#: Appendix A: pinch-off f_b with R5 = 24 kΩ, C2 = 47 nF.
FB_FLOOR_HZ = 141.1
#: tan(22.5°): notch 1 sits here relative to a stage's f_b.
TAN_22_5 = math.tan(math.radians(22.5))
#: Half the S3 typical-unit Hertz swing (328.0 … 2997.7 Hz) at Depth 1.
HALF_SWING_HZ = (2997.7 - 328.0) / 2.0

STAGES_CHOICES = (4, 6, 8, 10, 12)
DIVISION_BARS = (4.0, 2.0, 1.0, 0.5, 1.0 / 3.0, 0.25, 0.125)

WAVEFORM_POINTS = 256
CURVE_POINTS = 1024

# BEGIN PHASER_CURVE
#: What the table's full scale stands for. The curve is
#: normalised to its own extreme so it fills int16
#: (audiocomponents#77) and this carries the scale back
#: out in the shaper's `post_gain`.
CURVE_SCALE = 0.666666667
CURVE_BYTES = (
    b"\x01\x80\x01\x80\x02\x80\x03\x80\x04\x80\x06\x80\x08\x80\x0a\x80"
    b"\x0d\x80\x10\x80\x14\x80\x18\x80\x1c\x80\x20\x80\x25\x80\x2b\x80"
    b"\x31\x80\x37\x80\x3d\x80\x44\x80\x4b\x80\x53\x80\x5b\x80\x63\x80"
    b"\x6c\x80\x75\x80\x7e\x80\x88\x80\x92\x80\x9c\x80\xa7\x80\xb2\x80"
    b"\xbd\x80\xc9\x80\xd5\x80\xe2\x80\xef\x80\xfc\x80\x0a\x81\x17\x81"
    b"\x26\x81\x34\x81\x43\x81\x53\x81\x62\x81\x72\x81\x83\x81\x93\x81"
    b"\xa4\x81\xb6\x81\xc7\x81\xd9\x81\xec\x81\xfe\x81\x12\x82\x25\x82"
    b"\x39\x82\x4d\x82\x61\x82\x76\x82\x8b\x82\xa0\x82\xb6\x82\xcc\x82"
    b"\xe2\x82\xf9\x82\x10\x83\x27\x83\x3f\x83\x57\x83\x70\x83\x88\x83"
    b"\xa1\x83\xba\x83\xd4\x83\xee\x83\x08\x84\x23\x84\x3e\x84\x59\x84"
    b"\x75\x84\x90\x84\xad\x84\xc9\x84\xe6\x84\x03\x85\x21\x85\x3e\x85"
    b"\x5c\x85\x7b\x85\x99\x85\xb8\x85\xd8\x85\xf7\x85\x17\x86\x37\x86"
    b"\x58\x86\x79\x86\x9a\x86\xbb\x86\xdd\x86\xff\x86\x22\x87\x44\x87"
    b"\x67\x87\x8a\x87\xae\x87\xd2\x87\xf6\x87\x1a\x88\x3f\x88\x64\x88"
    b"\x8a\x88\xaf\x88\xd5\x88\xfb\x88\x22\x89\x49\x89\x70\x89\x97\x89"
    b"\xbf\x89\xe7\x89\x0f\x8a\x37\x8a\x60\x8a\x89\x8a\xb3\x8a\xdc\x8a"
    b"\x06\x8b\x30\x8b\x5b\x8b\x86\x8b\xb1\x8b\xdc\x8b\x08\x8c\x34\x8c"
    b"\x60\x8c\x8c\x8c\xb9\x8c\xe6\x8c\x13\x8d\x41\x8d\x6e\x8d\x9d\x8d"
    b"\xcb\x8d\xfa\x8d\x28\x8e\x58\x8e\x87\x8e\xb7\x8e\xe7\x8e\x17\x8f"
    b"\x47\x8f\x78\x8f\xa9\x8f\xda\x8f\x0c\x90\x3e\x90\x70\x90\xa2\x90"
    b"\xd5\x90\x08\x91\x3b\x91\x6e\x91\xa2\x91\xd6\x91\x0a\x92\x3e\x92"
    b"\x73\x92\xa8\x92\xdd\x92\x12\x93\x48\x93\x7e\x93\xb4\x93\xea\x93"
    b"\x21\x94\x58\x94\x8f\x94\xc6\x94\xfe\x94\x36\x95\x6e\x95\xa6\x95"
    b"\xdf\x95\x17\x96\x50\x96\x8a\x96\xc3\x96\xfd\x96\x37\x97\x71\x97"
    b"\xac\x97\xe7\x97\x21\x98\x5d\x98\x98\x98\xd4\x98\x10\x99\x4c\x99"
    b"\x88\x99\xc5\x99\x01\x9a\x3e\x9a\x7c\x9a\xb9\x9a\xf7\x9a\x35\x9b"
    b"\x73\x9b\xb1\x9b\xf0\x9b\x2f\x9c\x6e\x9c\xad\x9c\xec\x9c\x2c\x9d"
    b"\x6c\x9d\xac\x9d\xed\x9d\x2d\x9e\x6e\x9e\xaf\x9e\xf0\x9e\x32\x9f"
    b"\x73\x9f\xb5\x9f\xf7\x9f\x39\xa0\x7c\xa0\xbe\xa0\x01\xa1\x44\xa1"
    b"\x88\xa1\xcb\xa1\x0f\xa2\x53\xa2\x97\xa2\xdb\xa2\x20\xa3\x64\xa3"
    b"\xa9\xa3\xef\xa3\x34\xa4\x79\xa4\xbf\xa4\x05\xa5\x4b\xa5\x91\xa5"
    b"\xd8\xa5\x1f\xa6\x65\xa6\xac\xa6\xf4\xa6\x3b\xa7\x83\xa7\xcb\xa7"
    b"\x13\xa8\x5b\xa8\xa3\xa8\xec\xa8\x35\xa9\x7e\xa9\xc7\xa9\x10\xaa"
    b"\x5a\xaa\xa3\xaa\xed\xaa\x37\xab\x81\xab\xcc\xab\x16\xac\x61\xac"
    b"\xac\xac\xf7\xac\x42\xad\x8e\xad\xda\xad\x25\xae\x71\xae\xbe\xae"
    b"\x0a\xaf\x56\xaf\xa3\xaf\xf0\xaf\x3d\xb0\x8a\xb0\xd7\xb0\x25\xb1"
    b"\x72\xb1\xc0\xb1\x0e\xb2\x5c\xb2\xab\xb2\xf9\xb2\x48\xb3\x97\xb3"
    b"\xe6\xb3\x35\xb4\x84\xb4\xd3\xb4\x23\xb5\x73\xb5\xc3\xb5\x13\xb6"
    b"\x63\xb6\xb3\xb6\x04\xb7\x54\xb7\xa5\xb7\xf6\xb7\x47\xb8\x99\xb8"
    b"\xea\xb8\x3b\xb9\x8d\xb9\xdf\xb9\x31\xba\x83\xba\xd5\xba\x28\xbb"
    b"\x7a\xbb\xcd\xbb\x20\xbc\x73\xbc\xc6\xbc\x19\xbd\x6d\xbd\xc0\xbd"
    b"\x14\xbe\x68\xbe\xbb\xbe\x10\xbf\x64\xbf\xb8\xbf\x0d\xc0\x61\xc0"
    b"\xb6\xc0\x0b\xc1\x60\xc1\xb5\xc1\x0a\xc2\x5f\xc2\xb5\xc2\x0a\xc3"
    b"\x60\xc3\xb6\xc3\x0c\xc4\x62\xc4\xb8\xc4\x0f\xc5\x65\xc5\xbc\xc5"
    b"\x12\xc6\x69\xc6\xc0\xc6\x17\xc7\x6e\xc7\xc5\xc7\x1d\xc8\x74\xc8"
    b"\xcc\xc8\x24\xc9\x7b\xc9\xd3\xc9\x2b\xca\x84\xca\xdc\xca\x34\xcb"
    b"\x8d\xcb\xe5\xcb\x3e\xcc\x97\xcc\xf0\xcc\x49\xcd\xa2\xcd\xfb\xcd"
    b"\x54\xce\xae\xce\x07\xcf\x61\xcf\xba\xcf\x14\xd0\x6e\xd0\xc8\xd0"
    b"\x22\xd1\x7c\xd1\xd7\xd1\x31\xd2\x8b\xd2\xe6\xd2\x41\xd3\x9b\xd3"
    b"\xf6\xd3\x51\xd4\xac\xd4\x07\xd5\x62\xd5\xbd\xd5\x19\xd6\x74\xd6"
    b"\xd0\xd6\x2b\xd7\x87\xd7\xe3\xd7\x3e\xd8\x9a\xd8\xf6\xd8\x52\xd9"
    b"\xae\xd9\x0b\xda\x67\xda\xc3\xda\x20\xdb\x7c\xdb\xd9\xdb\x35\xdc"
    b"\x92\xdc\xef\xdc\x4c\xdd\xa8\xdd\x05\xde\x63\xde\xc0\xde\x1d\xdf"
    b"\x7a\xdf\xd7\xdf\x35\xe0\x92\xe0\xf0\xe0\x4d\xe1\xab\xe1\x09\xe2"
    b"\x66\xe2\xc4\xe2\x22\xe3\x80\xe3\xde\xe3\x3c\xe4\x9a\xe4\xf8\xe4"
    b"\x56\xe5\xb4\xe5\x13\xe6\x71\xe6\xd0\xe6\x2e\xe7\x8c\xe7\xeb\xe7"
    b"\x4a\xe8\xa8\xe8\x07\xe9\x66\xe9\xc4\xe9\x23\xea\x82\xea\xe1\xea"
    b"\x40\xeb\x9f\xeb\xfe\xeb\x5d\xec\xbc\xec\x1b\xed\x7a\xed\xda\xed"
    b"\x39\xee\x98\xee\xf7\xee\x57\xef\xb6\xef\x16\xf0\x75\xf0\xd4\xf0"
    b"\x34\xf1\x93\xf1\xf3\xf1\x53\xf2\xb2\xf2\x12\xf3\x72\xf3\xd1\xf3"
    b"\x31\xf4\x91\xf4\xf0\xf4\x50\xf5\xb0\xf5\x10\xf6\x70\xf6\xd0\xf6"
    b"\x2f\xf7\x8f\xf7\xef\xf7\x4f\xf8\xaf\xf8\x0f\xf9\x6f\xf9\xcf\xf9"
    b"\x2f\xfa\x8f\xfa\xef\xfa\x4f\xfb\xaf\xfb\x0f\xfc\x6f\xfc\xcf\xfc"
    b"\x2f\xfd\x8f\xfd\xf0\xfd\x50\xfe\xb0\xfe\x10\xff\x70\xff\xd0\xff"
    b"\x30\x00\x90\x00\xf0\x00\x50\x01\xb0\x01\x10\x02\x71\x02\xd1\x02"
    b"\x31\x03\x91\x03\xf1\x03\x51\x04\xb1\x04\x11\x05\x71\x05\xd1\x05"
    b"\x31\x06\x91\x06\xf1\x06\x51\x07\xb1\x07\x11\x08\x71\x08\xd1\x08"
    b"\x30\x09\x90\x09\xf0\x09\x50\x0a\xb0\x0a\x10\x0b\x6f\x0b\xcf\x0b"
    b"\x2f\x0c\x8e\x0c\xee\x0c\x4e\x0d\xad\x0d\x0d\x0e\x6d\x0e\xcc\x0e"
    b"\x2c\x0f\x8b\x0f\xea\x0f\x4a\x10\xa9\x10\x09\x11\x68\x11\xc7\x11"
    b"\x26\x12\x86\x12\xe5\x12\x44\x13\xa3\x13\x02\x14\x61\x14\xc0\x14"
    b"\x1f\x15\x7e\x15\xdd\x15\x3c\x16\x9a\x16\xf9\x16\x58\x17\xb6\x17"
    b"\x15\x18\x74\x18\xd2\x18\x30\x19\x8f\x19\xed\x19\x4c\x1a\xaa\x1a"
    b"\x08\x1b\x66\x1b\xc4\x1b\x22\x1c\x80\x1c\xde\x1c\x3c\x1d\x9a\x1d"
    b"\xf7\x1d\x55\x1e\xb3\x1e\x10\x1f\x6e\x1f\xcb\x1f\x29\x20\x86\x20"
    b"\xe3\x20\x40\x21\x9d\x21\xfb\x21\x58\x22\xb4\x22\x11\x23\x6e\x23"
    b"\xcb\x23\x27\x24\x84\x24\xe0\x24\x3d\x25\x99\x25\xf5\x25\x52\x26"
    b"\xae\x26\x0a\x27\x66\x27\xc2\x27\x1d\x28\x79\x28\xd5\x28\x30\x29"
    b"\x8c\x29\xe7\x29\x43\x2a\x9e\x2a\xf9\x2a\x54\x2b\xaf\x2b\x0a\x2c"
    b"\x65\x2c\xbf\x2c\x1a\x2d\x75\x2d\xcf\x2d\x29\x2e\x84\x2e\xde\x2e"
    b"\x38\x2f\x92\x2f\xec\x2f\x46\x30\x9f\x30\xf9\x30\x52\x31\xac\x31"
    b"\x05\x32\x5e\x32\xb7\x32\x10\x33\x69\x33\xc2\x33\x1b\x34\x73\x34"
    b"\xcc\x34\x24\x35\x7c\x35\xd5\x35\x2d\x36\x85\x36\xdc\x36\x34\x37"
    b"\x8c\x37\xe3\x37\x3b\x38\x92\x38\xe9\x38\x40\x39\x97\x39\xee\x39"
    b"\x44\x3a\x9b\x3a\xf1\x3a\x48\x3b\x9e\x3b\xf4\x3b\x4a\x3c\xa0\x3c"
    b"\xf6\x3c\x4b\x3d\xa1\x3d\xf6\x3d\x4b\x3e\xa0\x3e\xf5\x3e\x4a\x3f"
    b"\x9f\x3f\xf3\x3f\x48\x40\x9c\x40\xf0\x40\x45\x41\x98\x41\xec\x41"
    b"\x40\x42\x93\x42\xe7\x42\x3a\x43\x8d\x43\xe0\x43\x33\x44\x86\x44"
    b"\xd8\x44\x2b\x45\x7d\x45\xcf\x45\x21\x46\x73\x46\xc5\x46\x16\x47"
    b"\x67\x47\xb9\x47\x0a\x48\x5b\x48\xac\x48\xfc\x48\x4d\x49\x9d\x49"
    b"\xed\x49\x3d\x4a\x8d\x4a\xdd\x4a\x2d\x4b\x7c\x4b\xcb\x4b\x1a\x4c"
    b"\x69\x4c\xb8\x4c\x07\x4d\x55\x4d\xa4\x4d\xf2\x4d\x40\x4e\x8e\x4e"
    b"\xdb\x4e\x29\x4f\x76\x4f\xc3\x4f\x10\x50\x5d\x50\xaa\x50\xf6\x50"
    b"\x42\x51\x8f\x51\xdb\x51\x26\x52\x72\x52\xbe\x52\x09\x53\x54\x53"
    b"\x9f\x53\xea\x53\x34\x54\x7f\x54\xc9\x54\x13\x55\x5d\x55\xa6\x55"
    b"\xf0\x55\x39\x56\x82\x56\xcb\x56\x14\x57\x5d\x57\xa5\x57\xed\x57"
    b"\x35\x58\x7d\x58\xc5\x58\x0c\x59\x54\x59\x9b\x59\xe1\x59\x28\x5a"
    b"\x6f\x5a\xb5\x5a\xfb\x5a\x41\x5b\x87\x5b\xcc\x5b\x11\x5c\x57\x5c"
    b"\x9c\x5c\xe0\x5c\x25\x5d\x69\x5d\xad\x5d\xf1\x5d\x35\x5e\x78\x5e"
    b"\xbc\x5e\xff\x5e\x42\x5f\x84\x5f\xc7\x5f\x09\x60\x4b\x60\x8d\x60"
    b"\xce\x60\x10\x61\x51\x61\x92\x61\xd3\x61\x13\x62\x54\x62\x94\x62"
    b"\xd4\x62\x14\x63\x53\x63\x92\x63\xd1\x63\x10\x64\x4f\x64\x8d\x64"
    b"\xcb\x64\x09\x65\x47\x65\x84\x65\xc2\x65\xff\x65\x3b\x66\x78\x66"
    b"\xb4\x66\xf0\x66\x2c\x67\x68\x67\xa3\x67\xdf\x67\x19\x68\x54\x68"
    b"\x8f\x68\xc9\x68\x03\x69\x3d\x69\x76\x69\xb0\x69\xe9\x69\x21\x6a"
    b"\x5a\x6a\x92\x6a\xca\x6a\x02\x6b\x3a\x6b\x71\x6b\xa8\x6b\xdf\x6b"
    b"\x16\x6c\x4c\x6c\x82\x6c\xb8\x6c\xee\x6c\x23\x6d\x58\x6d\x8d\x6d"
    b"\xc2\x6d\xf6\x6d\x2a\x6e\x5e\x6e\x92\x6e\xc5\x6e\xf8\x6e\x2b\x6f"
    b"\x5e\x6f\x90\x6f\xc2\x6f\xf4\x6f\x26\x70\x57\x70\x88\x70\xb9\x70"
    b"\xe9\x70\x19\x71\x49\x71\x79\x71\xa8\x71\xd8\x71\x06\x72\x35\x72"
    b"\x63\x72\x92\x72\xbf\x72\xed\x72\x1a\x73\x47\x73\x74\x73\xa0\x73"
    b"\xcc\x73\xf8\x73\x24\x74\x4f\x74\x7a\x74\xa5\x74\xd0\x74\xfa\x74"
    b"\x24\x75\x4d\x75\x77\x75\xa0\x75\xc9\x75\xf1\x75\x19\x76\x41\x76"
    b"\x69\x76\x90\x76\xb7\x76\xde\x76\x05\x77\x2b\x77\x51\x77\x76\x77"
    b"\x9c\x77\xc1\x77\xe6\x77\x0a\x78\x2e\x78\x52\x78\x76\x78\x99\x78"
    b"\xbc\x78\xde\x78\x01\x79\x23\x79\x45\x79\x66\x79\x87\x79\xa8\x79"
    b"\xc9\x79\xe9\x79\x09\x7a\x28\x7a\x48\x7a\x67\x7a\x85\x7a\xa4\x7a"
    b"\xc2\x7a\xdf\x7a\xfd\x7a\x1a\x7b\x37\x7b\x53\x7b\x70\x7b\x8b\x7b"
    b"\xa7\x7b\xc2\x7b\xdd\x7b\xf8\x7b\x12\x7c\x2c\x7c\x46\x7c\x5f\x7c"
    b"\x78\x7c\x90\x7c\xa9\x7c\xc1\x7c\xd9\x7c\xf0\x7c\x07\x7d\x1e\x7d"
    b"\x34\x7d\x4a\x7d\x60\x7d\x75\x7d\x8a\x7d\x9f\x7d\xb3\x7d\xc7\x7d"
    b"\xdb\x7d\xee\x7d\x02\x7e\x14\x7e\x27\x7e\x39\x7e\x4a\x7e\x5c\x7e"
    b"\x6d\x7e\x7d\x7e\x8e\x7e\x9e\x7e\xad\x7e\xbd\x7e\xcc\x7e\xda\x7e"
    b"\xe9\x7e\xf6\x7e\x04\x7f\x11\x7f\x1e\x7f\x2b\x7f\x37\x7f\x43\x7f"
    b"\x4e\x7f\x59\x7f\x64\x7f\x6e\x7f\x78\x7f\x82\x7f\x8b\x7f\x94\x7f"
    b"\x9d\x7f\xa5\x7f\xad\x7f\xb5\x7f\xbc\x7f\xc3\x7f\xc9\x7f\xcf\x7f"
    b"\xd5\x7f\xdb\x7f\xe0\x7f\xe4\x7f\xe8\x7f\xec\x7f\xf0\x7f\xf3\x7f"
    b"\xf6\x7f\xf8\x7f\xfa\x7f\xfc\x7f\xfd\x7f\xfe\x7f\xff\x7f\xff\x7f"
)
# END PHASER_CURVE

#: Drive's soft clip, `y = x - x**3 / 3`, normalised so the table fills
#: int16. Generated by `tools/curves/phaser_curve.py`; `CURVE_SCALE` above is
#: what its full scale stands for and the class carries it in the shaper's
#: `post_gain`, so the level is exactly where it was.
CUBIC_CURVE = array("h", CURVE_BYTES)

_RANGES = (
    (0.0, 10.0),                 # 0 Rate, Hz; 0 is held
    (0.0, 1.0),                  # 1 Depth
    (60.0, 2000.0, "log"),       # 2 Centre, notch-1 Hz at mid-sweep
    (0.0, 0.9),                  # 3 Feedback
    (0.0, 1.0),                  # 4 Mix
    (0.0, 4.0),                  # 5 Stages index → 4/6/8/10/12
    (0.35, 0.65),                # 6 Shape, ramp duty
    (0.0, 1.0),                  # 7 Drive
    (0.0, 1.0),                  # 8 Sync (TOGGLE)
    (0.0, 6.0),                  # 9 Division index
)


def _triangle_waveform(duty):
    """256 int16 samples, −1 → +1 → −1, with `duty` the rising fraction."""
    duty = min(0.65, max(0.35, float(duty)))
    n = WAVEFORM_POINTS
    rising = max(2, min(n - 2, int(round(duty * n))))
    falling = n - rising
    wave = array("h")
    for index in range(rising):
        x = -1.0 + 2.0 * index / float(rising - 1)
        wave.append(max(-32768, min(32767, int(round(x * 32767.0)))))
    for index in range(falling):
        x = 1.0 - 2.0 * index / float(falling - 1)
        wave.append(max(-32768, min(32767, int(round(x * 32767.0)))))
    return wave


def _choice(choices, position):
    last = len(choices) - 1
    return choices[min(last, max(0, int(round(position * last))))]


def _patch(*engineering):
    return tuple(_component.macro_of(span, value)
                 for span, value in zip(_RANGES, engineering))


[docs] class Phaser(_component.Component): """A phaser after the Phase 90: notches swept up and down your signal on a triangle. **Controls.** Rate is the sweep's speed, and at 0 the notches hold still. Depth is how far they swing, and Centre puts the lower notch, mid-sweep. Stages sets how many all-pass stages there are, and each pair makes a notch: four stages make two, the second about two and a half octaves above the first. Mix at 0 is your dry signal, and at 0.5, the default, the notches go deeper than 40 dB. Feedback lifts a hump between the notches. Shape leans the triangle. Drive softens the signal on its way into the stages, so it grows harmonics as your level rises. The Effect controls page lists what the knobs span. **Drive and Feedback.** Drive is 0.3 when you construct the class, and there the Feedback hump stays under 5 dB. Turn Drive to 0 and Feedback lifts it more than 5 dB. The Phaser - lean patch is the default with Drive at 0. Keep the input under -9 dBFS and the defaults and patches stay off the rails. Feedback at its top can still push the output onto the rails. **Sync.** With Sync on, the sweep locks to the host: Division picks the length of a sweep in bars, a bar is read from the host's time signature, and a change of tempo or meter is followed. **Timing.** Latency is zero at every setting. Silence in is silence out once the notches ring down, which at musical settings is quick; the class reports the worst case, 552960 samples, for stages at their sharpest. **On a board.** The class needs audiodsp's `audiobiquad` and `audioshaper`, and on a board without them construction raises `ImportError`. """ NAME = 'Phaser' DISPLAY_NAME = 'Phaser' CATEGORIES = ('Modulation',) VERSION = '0.0.2' TIER = _component.AUDIODSP REQUIRES = ("audiobiquad", "audioshaper") CAPABILITIES = ("tempo_sync",) _SYNC_MACRO = 8 LATENCY_SAMPLES = 0 #: Worst-case first-order all-pass flush at the coefficient cap #: (`AUDIODSP_FILTER_F32_MAX_ALLPASS_C`) is ~550_000 samples in the C #: comment; musical settings die much sooner. Ceiling, next 2048. TAIL_SAMPLES = 552960 #: The defaults and every patch play the ceiling kit's materials #: clean at this level; at -6 dBFS, patch 1 rails on #: a 147 Hz square. INPUT_CEILING_DBFS = -9 #: Settings that clip by design: the rail check skips them. CLIPS_AT_TOP = (3,) MACRO_LABELS = ("Rate", "Depth", "Centre", "Feedback", "Mix", "Stages", "Shape", "Drive", "Sync", "Division") MACRO_MODES = { 0: "UNIPOLAR", 1: "UNIPOLAR", 2: "UNIPOLAR", 3: "UNIPOLAR", 4: "UNIPOLAR", 5: "UNIPOLAR", 6: "UNIPOLAR", 7: "UNIPOLAR", 8: "TOGGLE", 9: "UNIPOLAR", } _MACRO_RANGES = _RANGES _MACRO_UNITS = {0: "Hz", 2: "Hz"} PATCHES = { 0: ("Four stage, no feedback", _patch(0.4, 0.7, 400.0, 0.0, 0.5, 0.0, 0.5, 0.3, 0.0, 2.0)), 1: ("Four stage with resonance", _patch(0.4, 0.7, 400.0, 0.5, 0.5, 0.0, 0.5, 0.3, 0.0, 2.0)), 2: ("Slow wide sweep", _patch(0.1, 1.0, 400.0, 0.0, 0.5, 0.0, 0.5, 0.2, 0.0, 2.0)), 3: ("Fast tight sweep", _patch(4.0, 0.35, 500.0, 0.2, 0.5, 0.0, 0.5, 0.2, 0.0, 2.0)), 4: ("Six stage deep", _patch(0.3, 0.8, 350.0, 0.35, 0.5, 1.0, 0.5, 0.3, 0.0, 2.0)), 5: ("Held notch pair", _patch(0.0, 0.0, 400.0, 0.0, 0.5, 0.0, 0.5, 0.0, 0.0, 2.0)), 6: ("Bass-safe shallow", _patch(0.3, 0.4, 90.0, 0.0, 0.5, 0.0, 0.5, 0.15, 0.0, 2.0)), 7: ("Synced half bar", _patch(0.4, 0.7, 400.0, 0.0, 0.5, 0.0, 0.5, 0.3, 1.0, 3.0)), 8: ("Phaser - lean", _patch(0.4, 0.7, 400.0, 0.0, 0.5, 0.0, 0.5, 0.0, 0.0, 2.0)), } def _build(self, rate=0.4, depth=0.7, centre=400.0, feedback=0.0, mix=0.5, stages=4, shape=0.5, drive=0.3, sync=False, division=1.0, patch=None): rate_hz = self._sample_rate channels = self._channel_count # `post_gain` is the table's own scale and nothing else: the curve # peaks at 2/3 by construction, the table is normalised to that so # it fills int16, and this puts the 2/3 back. The wet leg's level is # exactly where it was - measured, the peak over the dry moves by # 0.000000 dB and the wet RMS by 0.00002 (audiocomponents#77). # The guard plays the borrowed source once, here, and nothing plays # the source again. A Drive or Mix move that takes the shaper in or # out of the pull re-points the cascade between the guard and the # shaper, and a `play()` drops the frames its node had taken and # not yet used: on the source itself that rewound a whole # RawSample to its start, and on a stream of 100-frame buffers # dropped part of one. The guard hands out whole 256-frame blocks, # which the shaper and the cascade each use up in a pull, so a # re-point between them drops nothing. `reset=False`: its reset # would drop the source frames it holds, and it holds nothing else. # `audiofilters.Filter` with no filter is a copy, the cheapest node # that hands out its own block size (DynamicEQ's guard). self._guard = self._own(audiofilters.Filter( filter=None, mix=1, buffer_size=256 * channels * 2, sample_rate=rate_hz, channel_count=channels, bits_per_sample=16, samples_signed=True), reset=False) self._guard.play(self._source, loop=False) self._shaper = self._own(audioshaper.Waveshaper( sample_rate=rate_hz, channel_count=channels, curve=CUBIC_CURVE, oversample=1, mix=0.0, pre_gain=1.0, post_gain=CURVE_SCALE)) self._shaper.play(self._guard) #: What the cascade plays: the shaper, or the guard while Drive or #: Mix is at 0. self._head = self._shaper # Built-in triangle: a custom waveform table is not a palette # audio node, but serving one still costs. Shape 0.5 (default) # uses synthio's own LFO, which is a BlockInput and is not an # extra RawSample. A custom table is baked only when Shape moves. self._lfo = None self._lfo_custom = False self._lfo_shape = 0.5 self._cascade = None self._held_hz = 1000.0 self._install_cascade(self._stage_count_from_value(stages)) stage_index = float(STAGES_CHOICES.index(self._stage_count_from_value( stages))) div_index = float(self._division_index_from_value(division)) self._init_macros( (rate, depth, centre, feedback, mix, stage_index, shape, drive, 1.0 if sync else 0.0, div_index), patch) def _stage_count_from_value(self, stages): wanted = int(stages) nearest = STAGES_CHOICES[0] for candidate in STAGES_CHOICES: if abs(candidate - wanted) < abs(nearest - wanted): nearest = candidate return nearest def _division_index_from_value(self, bars): wanted = float(bars) nearest = 2 for index, candidate in enumerate(DIVISION_BARS): if abs(candidate - wanted) < abs(DIVISION_BARS[nearest] - wanted): nearest = index return nearest def _install_cascade(self, stages): node = audiobiquad.AllPass( stages=int(stages), frequency=self._held_hz, feedback=0.0, mix=0.5, sample_rate=self._sample_rate, channel_count=self._channel_count) node.play(self._head) if self._cascade is None: self._own(node) self._cascade = node self._output = node return old = self._cascade index = self._nodes.index(old) self._nodes[index] = node self._resets[index] = True self._deinits[index] = True self._cascade = node # RE-POINT BEFORE STOPPING THE OLD ONE. `stop()` on an AllPass writes # {source, pending, pending_frames} as three words, and a pull landing # between them hands the DSP a length as a pointer -- the 0x400 crash, # on x86-64 and on RISC-V. The pump lock makes that write atomic; what # it cannot do is stop the pump pulling a node this method has already # finished with. Pointing the port at the new cascade first means the # old one is out of the graph before it is touched at all. self._output = node stopper = getattr(old, "stop", None) if stopper is not None: stopper() def _value(self, index): return _component.macro_value(self._MACRO_RANGES[index], self._macros[index])
[docs] def reset(self): """Clear every node, restore patch 0 and start the sweep again. The sweep is a `synthio.LFO` the walk does not reach, so it ran on through a reset from wherever it was; patch 0 now builds a fresh one, which starts where a fresh instance's does, as Vibrato's does on its clear.""" self._check_live() self._lfo = None _component.Component.reset(self)
def _apply_macro(self, index, position): if index == 5: stages = _choice(STAGES_CHOICES, position) if self._cascade is None or self._cascade.stages != stages: self._install_cascade(stages) self._refresh_mix_feedback() self._refresh_sweep() return if index == 7: self._refresh_drive() return if index in (3, 4): self._refresh_mix_feedback() return self._refresh_sweep() def _refresh_drive(self): # Mix 0 is a wire. Drive 0 drops the shaper from the pull so the # lean patch is AllPass (and the guard) alone. The cascade is # re-pointed only when that route changes: a move that keeps it # (or a reset) plays nothing again. if self._value(7) <= 0.0: self._shaper.set(mix=0.0, pre_gain=1.0) head = self._guard elif self._value(4) <= 0.0: # Mix 0 with Drive up: the shaper stays in the pull and walks # its own mix to 0, at the drive it had, so the drive fades # out with the sweep instead of cutting. self._shaper.set(mix=0.0) head = self._shaper else: drive = self._value(7) self._shaper.set(mix=drive, pre_gain=1.0 + 8.0 * drive) head = self._shaper if head is not self._head: self._head = head self._cascade.play(head) def _refresh_mix_feedback(self): self._cascade.feedback = self._value(3) self._cascade.mix = self._value(4) self._refresh_drive() def _lfo_rate_hz(self): rate = self._value(0) if self._value(8) >= 0.5: tempo, quarters = self._synced_beat() bars = _choice(DIVISION_BARS, self._macros[9]) rate = tempo / (60.0 * quarters * bars) return rate
[docs] def transport_changed(self): """With Sync on, follow the host's tempo and its time signature: a move of either sets the sweep's rate again. The base follows the tempo alone, so a 4/4 to 3/4 change at one tempo would keep the old rate. A NaN read twice is no change, as the base has it for a tempo.""" self._check_live() index = type(self)._SYNC_MACRO if index is None or self._macros[index] < 0.5: return # What the host got wrong (a tempo of None or NaN, a field missing, # a signature of 4/0 or 10**400/4) keeps the last good reading, so # it is no change and the sweep plays on as it was. followed = self._synced_beat() if followed == self._followed_bpm: return self._followed_bpm = followed self._apply_macro(index, self._macros[index])
def _fb_span(self): centre_notch = self._hz(self._value(2)) mid = centre_notch / TAN_22_5 depth = self._value(1) half = depth * HALF_SWING_HZ low = max(FB_FLOOR_HZ, mid - half) high = mid + half ceiling = self._sample_rate * 0.5 * _component.NYQUIST_MARGIN if high > ceiling: high = ceiling if low > high: low = high return low, high def _refresh_sweep(self): low, high = self._fb_span() mid = 0.5 * (low + high) self._held_hz = mid shape = self._value(6) rate = self._lfo_rate_hz() if rate <= 0.0 or self._value(1) <= 0.0: self._cascade.frequency = mid return self._attach_lfo(rate, 0.5 * (high - low), mid, shape) def _attach_lfo(self, rate, scale, offset, shape): want_custom = abs(float(shape) - 0.5) > 0.001 rebuild = ( self._lfo is None or want_custom != self._lfo_custom or (want_custom and abs(float(shape) - self._lfo_shape) > 0.001) ) if rebuild: # MicroPython cannot assign LFO.waveform after construction. if want_custom: self._lfo = synthio.LFO( waveform=_triangle_waveform(shape), rate=rate, scale=scale, offset=offset, once=False) else: self._lfo = synthio.LFO( rate=rate, scale=scale, offset=offset, once=False) self._lfo_custom = want_custom self._lfo_shape = float(shape) else: self._lfo.rate = rate self._lfo.scale = scale self._lfo.offset = offset self._cascade.frequency = self._lfo