Add tap.overdrive~ — voiced feedback overdrive (kernel bump + full slice)

REVIVAL.md

@@ -1088,6 +1088,34 @@ GitHub Actions CI.
   where the field guide left it — gated on an A/B showing an audible delta the informed model misses,
   which the DAFx-14 finding suggests may never open. Remaining: A/B calibration of the swing `drive`
   against reference, and runtime validation in Max.
+- ✅ **Net-new object — `tap.overdrive~` (2026-07-22).** The spiritual successor to the Jamoma-era
+  `tap.overdrive~`, deliberately *not* a port (per the overdrive handoff brief): TTOverdrive's two
+  memoryless odd-function curves — the sine shaper's hard ±1 plateau and its aliasing were the
+  "digital" tell — are dropped, replaced by a voiced feedback clipper chasing the *class* of
+  TS-lineage pedals (Mad Professor Little Green Wonder as the listening reference). Kernel:
+  **`overdrive.h`** (`tap::tools::od`) — the nonlinearity sits inside a lowpass **feedback loop**
+  solved zero-delay (the `svf.h` driven-circuit / `ladder.h` solver_fast one-pass scheme), with the
+  LF loop gain pinned so bass stays tight and nearly clean at any drive while mids take the full
+  gain — the frequency-dependent clipping a static curve cannot do, and most of the perceptual
+  distance to the reference. Even harmonics via an `asymmetry` bias (0..1), a unity clean-through so
+  the transfer never flattens, an always-on DC blocker (`R = 0.9997`, the TTDCBlock constant — this
+  time actually in the signal path, unlike TTOverdrive's vestigial one), `body` (−1..+1) sliding the
+  pre-clipper HP corner + CW upper-mid push / CCW treble lift (all linear voicing EQ, placeholders
+  pending the by-ear pass against LGW demos), 1/2/4/8× oversampling (default 4×), and normalized
+  0..1 parameters throughout (mappable, and Q15/Q31-ready for a future fixed-point M33 target).
+  Kernel Catch2 tests pin the design goals: gain-tilt-grows-with-drive, even-harmonic emergence,
+  DC blocking, never-flat slope, alias-floor improvement with oversampling, body tilt, decay to
+  silence, determinism. Wrapper `tap.overdrive_tilde` (thin `vector_operator`), attributes
+  `drive`/`body`/`asymmetry`/`preamp`/`output`/`oversample`/`smooth`/`bypass`/`mute`, min-api
+  attribute tests, the full vertical slice (maxref + help patcher + a bypass-passthrough
+  `maxtest` starter). Same-day follow-up: the rest of the kernel-repo house treatment — a
+  `taptools_od_*` C ABI + `Overdrive` ctypes class, the **executed verification notebook**
+  (`overdrive.ipynb`: tilt +5/+16.3/+17.2 dB at drive 0/0.5/0.9; H2 −151 → −26 dB across
+  asymmetry; folded H7 −22 → −36 dB at 4×; DC means ~1e-10), and two field-guide chapters —
+  *Distortion with a memory* (new book Part VII, The pedalboard — after `tap.tune~`'s Part VI,
+  Staying in tune, landed the same week) + *The clipper in the loop: overdrive.h* (machine part,
+  now VIII). Remaining: the in-Max voicing pass (the
+  `k_voice_*` constants are the sound of the object) and runtime validation.
 
 ---
 

docs/tap.overdrive~.maxref.xml

@@ -0,0 +1,96 @@
+<?xml version="1.0" encoding="utf-8" standalone="yes"?>
+<?xml-stylesheet href="./_c74_ref.xsl" type="text/xsl"?>
+
+<c74object name="tap.overdrive~" module="msp" category="TapTools, MSP Distortion">
+
+	<digest>
+		Voiced feedback overdrive / saturation
+	</digest>
+
+	<description>
+		The <o>tap.overdrive~</o> object is a soft-clipping overdrive whose nonlinearity sits
+		inside a lowpass feedback loop — the topology of TS-lineage feedback pedals (voiced
+		against the Mad Professor Little Green Wonder) — rather than a static waveshaping curve
+		applied to the whole spectrum. The result is frequency-dependent clipping: bass stays
+		tight and nearly clean at any drive while mids and highs take the full gain and break up
+		first, and the tilt grows as the drive rises. The asymmetry attribute biases the clipper
+		for even-harmonic warmth (a built-in DC blocker removes the offset this creates), and a
+		unity clean path is summed around the clipper so the transfer keeps rising with reduced
+		slope instead of flattening into a hard digital plateau. The body attribute is the
+		signature voicing control: toward -1 fuller lows reach the clipper and the top gets a
+		slight lift; toward +1 the lows tighten and thin and the upper mids push forward. The
+		clipping stage runs oversampled (default 4x) to keep aliasing down, and all parameters
+		glide smoothly. This object is the spiritual successor to the original Jamoma-era
+		tap.overdrive~, replacing its memoryless waveshaper modes. Single-channel: wrap in mc.
+		for multichannel.
+	</description>
+
+
+	<!--METADATA-->
+	<metadatalist>
+		<metadata name="author">74 Objects</metadata>
+		<metadata name="tag">TapTools</metadata>
+		<metadata name="tag">Audio</metadata>
+		<metadata name="tag">Distortion</metadata>
+	</metadatalist>
+
+
+	<!--MESSAGES-->
+	<methodlist>
+		<method name="clear">
+			<arglist/>
+			<description>Reset the filter, feedback, and resampler state.</description>
+		</method>
+	</methodlist>
+
+
+	<!--ATTRIBUTES-->
+	<attributelist>
+		<attribute name="drive" get="1" set="1" type="float" size="1">
+			<description>Drive (0-1). 0 is edge-of-breakup — a pedal's gain knob full
+			counterclockwise, still warm — and 1 is heavily saturated. The sweep is perceptual
+			(dB of gain into the clipper); use bypass for a true clean signal.</description>
+		</attribute>
+		<attribute name="body" get="1" set="1" type="float" size="1">
+			<description>Body voicing (-1..+1, 0 neutral). Toward -1: fuller lows into the
+			clipper and a slight treble lift. Toward +1: thinner, tighter lows and an upper-mid
+			push. Linear pre/post voicing around the clipper, not part of the
+			nonlinearity.</description>
+		</attribute>
+		<attribute name="asymmetry" get="1" set="1" type="float" size="1">
+			<description>Asymmetry (0-1): even-harmonic amount. 0 is a symmetric clip (odd
+			harmonics only); raising it biases the clipper for even-order warmth. The DC this
+			generates is removed by the built-in DC blocker.</description>
+		</attribute>
+		<attribute name="preamp" get="1" set="1" type="float" size="1">
+			<description>Input gain in dB (-24..24), applied before the clipper.</description>
+		</attribute>
+		<attribute name="output" get="1" set="1" type="float" size="1">
+			<description>Makeup gain in dB (-24..24), applied at the output.</description>
+		</attribute>
+		<attribute name="oversample" get="1" set="1" type="int" size="1">
+			<description>Internal oversampling factor for the clipping stage (1, 2, 4, or 8;
+			default 4). Reduces aliasing from the clipper's harmonics.</description>
+		</attribute>
+		<attribute name="smooth" get="1" set="1" type="float" size="1">
+			<description>Anti-zipper interpolation time in milliseconds applied to parameter changes.</description>
+		</attribute>
+		<attribute name="bypass" get="1" set="1" type="int" size="1">
+			<description>Pass the input through unprocessed.</description>
+		</attribute>
+		<attribute name="mute" get="1" set="1" type="int" size="1">
+			<description>Silence the output.</description>
+		</attribute>
+	</attributelist>
+
+
+	<!--SEEALSO-->
+	<seealsolist>
+		<seealso name="overdrive~"/>
+		<seealso name="tap.vca~"/>
+		<seealso name="tap.svf~"/>
+		<seealso name="tap.dcblock~"/>
+	</seealsolist>
+
+
+</c74object>