# 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