From 53d3ce7bab71d8c22649fddabc6f4f629f3a67a3 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 5 Aug 2026 01:29:15 +0000 Subject: [PATCH 01/12] =?UTF-8?q?Add=20Part=20IX=20=E2=80=94=20Recipes:=20?= =?UTF-8?q?whole-patch=20chapters=20chasing=20named=20sounds?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit A third kind of chapter for Tools on Tap: Parts I–VII say what each object is for, Part VIII says why to trust it, and a recipe puts several objects on one patch cord and chases a specific sound. The part opener states the rules (every knob spelled as the attribute is spelled; settings are starting points while measurements stay citations; provenance honest; ingredients ranked). Two recipes ship with the part: - "One machine, four decades" — four TR-808 kits off one phasor~/tap.808.seq~ scaffold: Planet Rock electro, Sexual Healing slow soul, Miami bass (the tuned long-decay kick as bassline), and trap with polymeter hat-roll rows. - "Three oscillators into a ladder" — the oscillator chapter's Moog recipe completed into a playable voice: stack, ladder, two tap.adsr~ contours, gate/pitch plumbing, and bass + lead settings tables. Every attribute and message was drafted against the TapTools-Max wrapper sources rather than from memory — which is what caught the snare's absent decay knob, the clap's tail spelling, the sequencer's hits/accents/velocities/step surface, the ladder's numeric mode index, and tap.adsr~'s level-gate contract. PLAN-recipes.md is the drafting record and carries the backlog (acid line, robot voice, shimmer, envelope filter, IR field guide, comb tunings). Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01V6CC6kpK5Lx2YkJWuNNQpw --- book/PLAN-recipes.md | 91 ++++++++++++++ book/src/SUMMARY.md | 6 + book/src/introduction.md | 4 + book/src/recipes/808-classics.md | 203 +++++++++++++++++++++++++++++++ book/src/recipes/cookbook.md | 31 +++++ book/src/recipes/minimoog.md | 142 +++++++++++++++++++++ 6 files changed, 477 insertions(+) create mode 100644 book/PLAN-recipes.md create mode 100644 book/src/recipes/808-classics.md create mode 100644 book/src/recipes/cookbook.md create mode 100644 book/src/recipes/minimoog.md diff --git a/book/PLAN-recipes.md b/book/PLAN-recipes.md new file mode 100644 index 0000000..74040a7 --- /dev/null +++ b/book/PLAN-recipes.md @@ -0,0 +1,91 @@ +# Plan — the Recipes part + +> **Status: drafted.** The part opener and the first two recipes are written and live in +> `src/recipes/` per the placement below (2026-08-05). This file remains as the drafting +> record, the plans-directory way, and carries the backlog of future recipes. + +Planning document for Part IX of *Tools on Tap*: **Recipes** — the book's third kind of +chapter. Parts I–VII say what each object is for; Part VIII says why to trust it; a recipe +puts several objects on one patch cord and chases a specific, named sound. + +## Placement in SUMMARY.md + +A new part after the machine part: + +```md +# Part IX — Recipes + +- [How to read a recipe](recipes/cookbook.md) +- [One machine, four decades](recipes/808-classics.md) +- [Three oscillators into a ladder](recipes/minimoog.md) +``` + +The introduction's organization list gains a matching Part IX bullet. + +## The rules a recipe is held to + +Stated in the part opener (`recipes/cookbook.md`), enforced in drafting: + +1. **Every knob named exists, spelled as the attribute is spelled.** Recipes were drafted + against the wrapper sources in TapTools-Max (`source/projects/`), not from memory — that + pass is what caught, e.g., that the snare has no `decay` (its tail rides `tone`), the + clap's tail knob is `tail`, the sequencer programs via `hits`/`accents`/`velocities`/ + `step` (there is no `steps` message), `tap.ladder~`'s `mode`/`solver` are numeric + indices at the Max layer, and `tap.adsr~` gates on signal level > 0.5 (so a + `tap.808.seq~` impulse at the default levels will not open it). +2. **Settings are starting points; measurements are citations.** A recipe's knob values are + ears' work and say so. Any *measured* number a recipe leans on (the kick's ~49 Hz + fundamental, the ladder's THD-vs-drive walk, sequencer polymeter) is borrowed from an + executed notebook or pinned test and cited, never re-derived — the "measured, not + remembered" promise unchanged. +3. **Provenance stays honest.** Documented production history (who used the machine) is + stated as such; pattern grids are labeled starting points, not transcriptions; and no + recipe claims to *be* a record — mix, room, tape, and hands are out of the box. +4. **Ingredients are ranked.** Every recipe ends with the vco-chapter-style ordered list of + what each element buys, so cutting from the bottom is a stated option. + +## Shipped recipes + +- **`recipes/808-classics.md` — One machine, four decades.** Four kits off one + `phasor~`/`tap.808.seq~` scaffold: "Planet Rock" electro (1982), "Sexual Healing" slow + soul (1982), Miami bass (the tuned long-decay kick as bassline), trap (half-time, + polymeter hat-roll rows via `length 24`/`length 32`). Evidence borrowed: + `tr808_calibration.ipynb` (kick fundamental, calibration residuals), `step_seq.ipynb` + (grid accuracy, polymeter), the drums chapter's pinned roll/choke behavior. +- **`recipes/minimoog.md` — Three oscillators into a ladder.** Completes the oscillator + chapter's Moog recipe into a playable monosynth voice: stack → ladder → `tap.vca~`, two + `tap.adsr~` contours (with the period-correct release-switch note), gate/pitch plumbing, + and bass + lead settings tables. Evidence borrowed: `vco.ipynb` and `ladder.ipynb` via + their chapters. + +## Backlog — future recipes, roughly in order of pull + +- **The acid line.** `tap.303.seq~` patterns that exploit the measured couplings: accent + runs into the C13 bloom (the ×1.94 wow), slide chains, `envmod`/`decay` interplay. + Mostly written already in spirit across the acid chapter; the recipe is patterns. +- **The robot voice.** `tap.vocoder~` driven properly: carrier choice (saw stack vs. + noise blend), band count trades, the sibilance path. +- **Shimmer.** `tap.pitchaccum~` + `tap.verb~`/`tap.convolve~` — the accumulating-fifths + pad, with the honest feedback-headroom accounting. +- **The funk envelope filter.** `tap.autowah~` against the calibrated hardware curves; + clav and bass settings. +- **Borrowed rooms, curated.** A short IR field guide for `tap.convolve~` — what to load, + true-stereo vs. mono-in, pre-delay by trimming. +- **The five-string drone.** `tap.5comb~` tunings as chord recipes. + +Each lands as one file in `src/recipes/` plus a SUMMARY line; no renumbering needed. + +## Notes for drafting + +- Titles follow the book's voice: image first, no object name in the title. +- Pattern grids are `text` code blocks, 16 columns with a step-number header; `X` accented, + `x` plain, `.` rest — the two-level scheme matches the sequencer's `plain`/`accented` + hardware model, which is the idiom recipes should teach first (per-step `velocities` is + the documented escape hatch). +- Tempo math is stated once in the scaffold section (`phasor~` frequency = BPM ÷ 240 for a + 16-step bar) and reused. +- Figure candidates (not yet drawn): the shared drum-kit scaffold as a proper signal-flow + SVG; the Moog voice wiring diagram in the house block-diagram style (`book/figures/`). +- If a wrapper surface changes (e.g. `tap.ladder~` ever grows symbolic `mode` values), the + recipes are the pages most likely to silently rot — re-check them against the wrappers + when bumping the TapTools-Max side. diff --git a/book/src/SUMMARY.md b/book/src/SUMMARY.md index 846cff5..e407ec4 100644 --- a/book/src/SUMMARY.md +++ b/book/src/SUMMARY.md @@ -55,3 +55,9 @@ - [Three ways to move a pitch: yin.h, psola.h, pvoc.h](machine/pitch.md) - [The nearest allowed note: tune.h](machine/tune.md) - [The clipper in the loop: overdrive.h](machine/overdrive.md) + +# Part IX — Recipes + +- [How to read a recipe](recipes/cookbook.md) +- [One machine, four decades](recipes/808-classics.md) +- [Three oscillators into a ladder](recipes/minimoog.md) diff --git a/book/src/introduction.md b/book/src/introduction.md index 1fca59a..0470ee1 100644 --- a/book/src/introduction.md +++ b/book/src/introduction.md @@ -45,6 +45,10 @@ The book is organized the way a patch is: recording *why* each algorithm is written the way it is, alternatives and all. Parts I–VII are for driving the objects; Part VIII is for trusting them — or changing them. +- **Part IX — Recipes**: whole patches chasing specific sounds — the TR-808 + kits behind four decades of records, the three-oscillator Moog voice — + with settings you can check against the reference pages and the honest + accounting of what each ingredient buys. More chapters land as objects mature; the utility and Jitter objects live in their reference pages, where they belong. diff --git a/book/src/recipes/808-classics.md b/book/src/recipes/808-classics.md new file mode 100644 index 0000000..c61e0ff --- /dev/null +++ b/book/src/recipes/808-classics.md @@ -0,0 +1,203 @@ +# One machine, four decades + +The TR-808 sold poorly, was discontinued in 1983, and then spent forty years +becoming the most influential drum machine ever built — not by being +realistic, but by being *itself* in four different genres' hands. This +recipe visits four of those hands: the 1982 electro of "Planet Rock," the +same year's slow soul of "Sexual Healing," the tuned-kick boom of Miami +bass, and the half-time rolls of trap. Same eight circuits every time; what +changes is the pattern, the accents, and which knob someone dared to turn +all the way up. + +One honesty note before the first grid: **these patterns are starting +points, not transcriptions.** Where a record's production story is +documented, the recipe says so; the grids themselves are the versions ears +agree get you into the neighborhood, and your ears finish the trip. The +voice knobs, on the other hand, are exact — every attribute below is +spelled as the shipping object spells it, and the calibration numbers +behind the voices live in the [drum machine chapter](../drums.md) and the +[`tr808_calibration.ipynb`](https://github.com/tap/TapTools/blob/main/notebooks/tr808_calibration.ipynb) +notebook. + +## The scaffold every recipe shares + +One `phasor~` is the transport; every `tap.808.seq~` row reads it; every +row's output cable is a voice's trigger input. The phasor's frequency for a +16-step bar of 4/4 is **BPM ÷ 240** (four beats per cycle, four sixteenths +per beat). Rows fed the same ramp are sample-locked forever — that is the +sequencer's phase-derived design (see [its machine +chapter](../machine/seq.md)), and it is why nothing below mentions sync. + +```text +phasor~ (BPM/240) + ├── tap.808.seq~ ──▶ tap.808.kick~ ──┐ + ├── tap.808.seq~ ──▶ tap.808.snare~ ──┤ + ├── tap.808.seq~ ──▶ tap.808.hat~ ──┼──▶ +~ ──▶ tap.limi~ + ├── tap.808.seq~ ──▶ (open) hat inlet 2┤ + └── tap.808.seq~ ──▶ tap.808.cowbell~──┘ +``` + +Program a row with two lists: `hits` (which of the 16 steps sound, 1/0 per +step) and `accents` (which sounding steps lean, 1/0 per step). An accented +step emits the row's `accented` level (default 0.5), a plain step emits +`plain` (default 0.01) — those defaults are the hardware's accent knob at +noon, and they matter more than they look, because a voice's trigger +amplitude is a *voltage on the 4–14 V bus*: an accented hit is punchier and +differently voiced, not merely louder. Raise `accented` toward 1.0 when a +groove should hit like the accent knob cranked. Single steps tweak with +`step ` (1-based), and each row's 16 slots (`store`/`recall`) +hold your fills. + +In the grids below, `X` is an accented hit, `x` a plain one, `.` a rest. + +## 1982, the Bronx via Düsseldorf: the "Planet Rock" kit + +The documented part: Afrika Bambaataa and producer Arthur Baker built +"Planet Rock" on a rented TR-808, borrowing Kraftwerk's melodies, and its +kit — dry kick, clap-snare backbeat, offbeat cowbell — became *the* electro +sound. The orchestra stabs were a sampler's; everything percussive is the +machine's. + +```text +step: 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 +kick: X . . . . . . x . . x . . . . . +snare: . . . . X . . . . . . . X . . . +clap: . . . . X . . . . . . . X . . . +closed: x . x . x . x . x . x . x . x . +open: . . . . . . . . . . . . . . x . +cowbell: . . x . . . x . . . x . . . x . +``` + +- Tempo ≈ 129 BPM → `phasor~ 0.5375`. +- `tap.808.kick~`: `@decay 0.35 @tone 0.55` — the electro kick is short and + clicky, not the boom (that comes later in this chapter). +- `tap.808.snare~`: `@tone 0.6 @snappy 0.7`; layer `tap.808.clap~` on the + same backbeat row — the clap-plus-snare composite is half the sound. +- `tap.808.cowbell~` on the offbeats, `@level 0.6`. The drum machine + chapter's line stands: more cowbell is a patching decision. +- Hats: closed 8ths; the open hat answering just before the bar turns. +- Fill: `store 1` the main pattern, program the classic descending-tom fill + (`tap.808.tom~`, `@size high` → `mid` → `low` on three rows) into slot 2, + and `recall 2` a bar before the phrase ends — `quantize cycle` (the + default) swaps it exactly on the downbeat. + +## 1982, Ostend: the "Sexual Healing" slow jam + +The documented part: Marvin Gaye programmed the TR-808 himself for +"Sexual Healing," and it became one of the first major hits carried by the +machine — proof in the same year as "Planet Rock" that the same circuits +could whisper. The kit is soft, sparse, and riding the plain/accent +distinction rather than density. + +```text +step: 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 +kick: X . . . . . . x . . . . . . . . +snare: . . . . x . . . . . . . x . . . +closed: x . x . x . x . x . x . x . x . +open: . . . . . . x . . . . . . . x . +claves: . . x . . . . . . . x . . . . . +``` + +- Tempo ≈ 94 BPM → `phasor~ 0.3917`. +- `tap.808.rim~ @model claves` — the high tick is the hook of the kit. + `@level 0.5` keeps it a seasoning. +- `tap.808.kick~`: `@decay 0.6 @tone 0.35` — rounder than electro, still + polite. +- `tap.808.snare~`: `@snappy 0.35 @tone 0.4` — more drum, less noise. +- Leave the sequencer's `plain` level at its 0.01 default and place accents + *sparingly*; at this tempo the difference between a 4 V hit and a + half-accented one is the entire feel. +- A touch of `@swing 0.15` on the hat row loosens the grid the way a human + thumb on the start button did. + +## Late eighties, Miami: the kick is the bassline + +Miami bass turned the kick's `decay` knob to the top and discovered the +808's bass drum is a *tuned instrument* — a bridged-T resonator whose +fundamental sits near 49 Hz (measured within 2.4 % of a real unit across +the knob grid; see the calibration pass in the drum machine chapter). Turn +`decay` up and it rings for seconds; give two copies two `tuning` ratios +and you have a two-note bassline. + +```text +step: 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 +kick A (root): X . . . . . . . . . X . . . . . +kick B (fourth): . . . . . . X . . . . . . X . . +snare: . . . . X . . . . . . . X . . . +closed: x . x x x . x x x . x x x . x x +``` + +- Tempo ≈ 126 BPM → `phasor~ 0.525`. +- Two `tap.808.kick~` objects, two rows. `tuning` is a ratio of the stock + fundamental, so **target Hz ÷ 49 ≈ your setting**: kick A `@tuning 1.0` + (G1, where stock already sits), kick B `@tuning 1.33` (≈ C2, the fourth). + Both `@decay 1.0` — the whole genre is that knob at the top. +- `@tone 0.2` keeps the click out of the way of the ring; `@attack 0.5` + softens the punch mechanism if the notes should bloom instead of hit. +- `tap.808.snare~ @snappy 0.8 @drive 6` — the swing-VCA drive is the crack + that cuts through the sub. +- Watch the sum: two ringing kicks stack. `tap.limi~` on the bus is the + modern answer; riding `level` per voice is the period one. + +## The 2010s: trap, and the arithmetic of rolls + +Trap keeps Miami's tuned, sustained kick and moves the snare to beat 3 — +the half-time frame — then spends all its rhythmic budget on hi-hat +subdivision games. Those games are where this sequencer's phase-derived +design pays off: rows of *different lengths* off one phasor divide the same +bar differently, so a 32nd-note roll row and a 16th-triplet roll row are +just `length 32` and `length 24` — polymeter as arithmetic, measured in the +[sequencer notebook](https://github.com/tap/TapTools/blob/main/notebooks/step_seq.ipynb). + +```text +step: 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 +kick: X . . . . . . x . . x . . . . . +snare: . . . . . . . . X . . . . . . . +closed (len 16): x . x . x . x . x . x . . . . . +roll (len 32): steps 25–32 hit, plain (32nds on beat 4) +triplet (len 24): steps 19–24 hit, plain (16th triplets, beats 3–4) +``` + +- Tempo ≈ 140 BPM → `phasor~ 0.5833`. +- Tune the kick to the song's key with the ratio table: E1 ≈ `@tuning + 0.83`, F1 ≈ `0.88`, G1 = `1.0`, A1 ≈ `1.12`. `@decay 1.0 @tone 0.15`, and + keep `sigh` at its default 1.0 — the pitch relaxation *is* the 808-bass + glide everyone samples. +- The roll rows: program hits only on their last steps (as above), leave + them muted (`@mute 1`), and unmute for the bar that needs the roll — or + keep separate patterns in slots and `recall`. Fast rolls do not + machine-gun: the voices' filter states persist across triggers, so a roll + interferes with the ringing tail like hardware (pinned by the family's + tests; see the drum machine chapter). +- Alternate hat voicing per unit: `@seed` is which 808 you own, and + `@tolerance 0.3` puts the metal bank's oscillators off-grid the way + resistor variance really does (Werner et al. measured up to ~20 % — the + chapter has the numbers). Two hat objects, two seeds, panned, is a stereo + kit for free. + +## What each ingredient buys + +1. **The pattern and its accents.** Four decades of genre difference above + is mostly the grids. The accent flags are not dynamics polish — they are + the hardware's second voicing per drum. Spend your time here. +2. **`decay` and `tuning` on the kick.** One knob separates electro from + Miami; one ratio puts the kick in the song's key. +3. **The composite backbeat.** Clap + snare on one row (electro), or snare + `drive` (Miami, trap) — the backbeat carries the genre signature after + the kick. +4. **Polymeter rows for rolls.** Two extra rows, two `length` values, and + the trap chapter of the machine's biography writes itself. +5. **`seed`/`tolerance` on the metal.** Seasoning, in the salt sense: + invisible until you A/B two units. + +## When to leave the recipe + +- **You want *those records*, exactly.** Mix, tape, room, and a human on + the start button are not in the box; at some point the honest tool is the + actual sample. +- **You want velocity-per-step expression.** The `velocities` list gives a + row continuous 0..1 levels — but note it trades away the two-level + hardware model; the accent bus is the 808's own idiom. +- **You want 909, LinnDrum, or DMX.** Different circuits, different + machines — this family models one instrument, and its refusal to be + generic is the point. diff --git a/book/src/recipes/cookbook.md b/book/src/recipes/cookbook.md new file mode 100644 index 0000000..8291595 --- /dev/null +++ b/book/src/recipes/cookbook.md @@ -0,0 +1,31 @@ +# How to read a recipe + +The first parts of this book keep two promises: the object chapters say what +each tool is for, and the machine chapters say why to trust it. This part +makes a third kind of promise. A recipe puts several objects on one patch +cord and chases a *specific sound* — a record you have heard, an instrument +you have coveted — and tells you honestly how close the kit gets. + +Recipes are held to the house rules, adapted: + +- **Every knob named exists, spelled the way the attribute is spelled.** A + recipe is checkable against the reference pages; if it says `@decay 0.8`, + that attribute takes that value on the shipping object. +- **Settings are starting points, not measurements.** A recipe's numbers get + you into the neighborhood; your ears walk the last block. Where a chapter + number *is* a measurement (a decay time, an alias floor), it still cites + the executed notebook or pinned test that carries it — the recipes borrow + those numbers rather than re-deriving them. +- **Provenance stays honest.** When a recipe chases a record, it says what is + documented about how that record was made and what is folklore. When it + chases an instrument, it leans on the same published analyses the kernels + were built from. What a recipe never does is claim to *be* the record — + mix, room, tape, and hands are not in the box. +- **Every recipe ranks its ingredients.** The house habit from the Moog + recipe in the oscillator chapter: list what each element buys, in order of + importance, so you know what to cut first when CPU or taste says so. + +Each recipe has the same skeleton: the sound and where it came from, the +signal chain, the settings (tables for knobs, grids for patterns), what each +ingredient buys, and — because every tool is sometimes the wrong tool — when +to leave the recipe and cook something of your own. diff --git a/book/src/recipes/minimoog.md b/book/src/recipes/minimoog.md new file mode 100644 index 0000000..71f9d36 --- /dev/null +++ b/book/src/recipes/minimoog.md @@ -0,0 +1,142 @@ +# Three oscillators into a ladder + +The oscillator chapter ends with the Moog recipe's core — the three-voice +saw stack and the driven ladder — and ranks what each ingredient buys. This +recipe finishes the instrument: the two envelopes, the amplifier, the gate, +and the settings that turn one signal chain into the two patches everyone +actually means by "Moog" — the bass that walks and the lead that sings. +The model here is the classic three-oscillator monosynth voice: three +oscillators into a mixer, one four-pole ladder, one loudness contour, one +filter contour, glide on the pitch. Nothing below requires an object the +package doesn't ship. + +Companion material: the [oscillator chapter](../vco.md) (the stack's +rationale and the analog section's ranges), the [ladder +chapter](../ladder.md) (every filter number below is measured in its +[notebook](https://github.com/tap/TapTools/blob/main/notebooks/ladder.ipynb)), +and the reference pages for `tap.adsr~` and `tap.vca~`. + +## The voice, wired + +```text +pitch (midi note) ──▶ mtof ─┬─▶ tap.vco~ (voice 1)──┐ + ├─▶ tap.vco~ (voice 2)──┼─▶ *~ 0.36 ─▶ tap.ladder~ ─▶ tap.vca~ ─▶ out + └─▶ ÷2 ─▶ tap.vco~ (3)──┘ ▲ ▲ +gate (0/1 signal) ──┬───────────▶ tap.adsr~ (filter contour) ─▶ *~ amount ─▶ +~ base ──┘│ + └───────────▶ tap.adsr~ (loudness contour) ─────────────────────────┘ +``` + +- **Pitch** arrives as note frequencies (floats into each `tap.vco~` left + inlet; halve for voice 3's octave-down). The oscillators' own `smooth` + ramp is the glide knob — no portamento object exists or is needed. +- **Gate** is any signal that goes above 0.5 and back — `tap.adsr~` reads + the gate by level, per sample. A `tap.303.seq~` gate output (1.0 plain, + 2.0 accented) drives it directly, which also gets you slides for free; + so does a MIDI-driven 0/1 signal, or the `trigger 1` / `trigger 0` + attribute messages for mouse-driven patching. +- **The filter contour** scales into the cutoff's signal inlet: envelope × + `amount` (Hz) + `base` (Hz) into `tap.ladder~`'s right inlet. The classic + panel's "amount" knob is your `*~`. +- **The loudness contour** multiplies the ladder's output — `tap.vca~` with + the envelope into its gain inlet keeps the option of `@circuit warm` + saturation later. + +One period-correct honesty note: the original panel's contours are +attack/decay/sustain with a release *switch* (release equals decay, on or +off). `tap.adsr~` gives the full four stages; set `release` equal to +`decay` and you have the switch's "on" position. + +## The stack and the ladder + +The three-voice table is the oscillator chapter's, reproduced so this page +patches alone: + +| voice | frequency | `detune` | `drift` | `seed` | +|-------|-----------|----------|---------|--------| +| 1 | f | −4 | 8 | 11 | +| 2 | f | +5 | 8 | 22 | +| 3 | f ÷ 2 | +2 | 10 | 33 | + +All three: `@shape 2` (saw), `@jitter 3 @track 2 @imperfect 0.3`, and +`smooth` per the patch below. Sum through `*~ 0.36` (≈ 1/2.8, headroom for +three voices), then `tap.ladder~` at the chapter's voicing: `@mode 0` (the +lp24 response — the mode attribute is the numeric pole-mix index) +`@resonance 0.35 @drive 9 @asym 0.45 @comp 0.25`. Keeping `comp` low +preserves the authentic passband droop; `drive 9` sits where the ladder +notebook measures the tanh stages just starting to thicken (3.5 % THD at +8 dB). Spend the character budget in the filter first — the chapter's +measurements are the argument. + +## Patch one: the bass + +The left hand of a decade of records: short filter contour, no vibrato, +glide short enough to read as punch rather than portamento. + +| control | setting | +|---|---| +| all `tap.vco~` `smooth` | 25 ms | +| filter `tap.adsr~` | `@attack 2 @decay 220 @sustain -18 @release 220` | +| filter `amount` / `base` | 2500 Hz / 120 Hz | +| ladder `resonance` | 0.25 | +| loudness `tap.adsr~` | `@attack 2 @decay 400 @sustain -3 @release 120` | + +The sound lives in the filter contour's `decay`: 220 ms is the "wah" that +articulates each note. Shorten toward 120 ms and it turns percussive; +lengthen toward 400 ms and it turns brassy. For a rounder, more +sub-friendly bass, drop `drive` to 3 and `asym` to 0.2 — the even +harmonics are lovely on a lead and muddy on a bass amp. If anything +downstream cares about DC, remember the ladder chapter's warning: +an asymmetric saturator can leave a small signal-dependent offset — +`tap.dcblock~` after the VCA is one object of insurance. + +## Patch two: the lead + +The singing version: longer glide, opened filter, resonance high enough to +color but under the edge, and the release switch "on." + +| control | setting | +|---|---| +| all `tap.vco~` `smooth` | 80 ms | +| filter `tap.adsr~` | `@attack 15 @decay 600 @sustain -8 @release 600` | +| filter `amount` / `base` | 4000 Hz / 300 Hz | +| ladder `resonance` | 0.55 | +| loudness `tap.adsr~` | `@attack 8 @decay 300 @sustain -2 @release 350` | + +Two moves push it from good to *that sound*: + +- **Play the glide.** 80 ms of `smooth` means overlapping note changes + swoop; detached ones barely bend. The keyboard articulation is the + vibrato. +- **Lean on the octave voice.** Pull voice 3 up to `f` (unison) for the + hollow reedy register, or leave it at `f ÷ 2` and drop voice 2's level + for the fat fifth-less stack. The `interp`-timed preset morph (`store` / + `recall `) can glide between these voicings mid-phrase — + a patch element the hardware never had. + +## What each ingredient buys + +In order — and, per the house rule, cut from the bottom when CPU or taste +says so: + +1. **The stack.** Three free-running voices at ±cents is most of the sound + (the oscillator chapter's argument, with its measurements). +2. **The ladder.** Drive, asymmetry, and the low-`comp` droop — the + character budget. +3. **The filter contour.** The one envelope listeners hear as "the synth's + voice." Its `decay` is the most audible 100 ms in the patch. +4. **Glide.** Free, iconic, already in the oscillator. +5. **The loudness contour.** Keep it simple; the filter does the talking. +6. **The analog section.** `drift`/`jitter`/`imperfect` at the chapter's + moderate settings — salt, not sauce. + +## When to leave the recipe + +- **You want polyphony.** This is a monosynth voice; `mc.`-wrapping the + whole chain gives you many monosynths, and a real polysynth patch wants + per-voice envelopes and different discipline. +- **You want the 303 instead.** The couplings that make acid are a + different instrument — `tap.303~` refuses to be decoupled, and that + refusal is its chapter. +- **You want clean.** Every stage here has an opinion — `tap.svf~` and + `tap.fourpole~` are the polite siblings when the patch needs a filter, + not a character. From 43153630638b2ec7f04c07f6fba01e14d5937d28 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 5 Aug 2026 01:52:11 +0000 Subject: [PATCH 02/12] Add the famous-Moog-patches recipe, and answer the modular question MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit "The patches with names on them" drives the previous recipe's three-oscillator voice at four records, each as a settings delta from its bass/lead tables: Steve Winwood's "While You See a Chance" hook, Bernie Worrell's stacked-Minimoog "Flash Light" bass, Rick Wright's "Shine On You Crazy Diamond" lead, and Keith Emerson's one-take "Lucky Man" modular solo. Gear provenance is stated per patch — documented history versus reconstruction — per the part opener's rules. The Lucky Man section carries the answer to whether the kit needs a Moog modular object: no, because a modular is routing freedom and Max is the patch panel — the modules already ship, and the wiring the solo needs is the previous chapter's diagram. The genuinely modular idiom (the sequenced line: tap.303.seq~ -> mtof~ -> the stack) is sketched once and added to the plan-file backlog as its own future recipe. Shared performance plumbing is stated once: constant-cents vibrato via the Hz-calibrated FM inlet (depth ~ 0.006 x f for +/-10 cents), and the sequencer pair driving the voice through mtof~ with adsr's level-gate contract. Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01V6CC6kpK5Lx2YkJWuNNQpw --- book/PLAN-recipes.md | 14 ++- book/src/SUMMARY.md | 1 + book/src/recipes/minimoog.md | 4 +- book/src/recipes/moog-classics.md | 171 ++++++++++++++++++++++++++++++ 4 files changed, 188 insertions(+), 2 deletions(-) create mode 100644 book/src/recipes/moog-classics.md diff --git a/book/PLAN-recipes.md b/book/PLAN-recipes.md index 74040a7..59fac66 100644 --- a/book/PLAN-recipes.md +++ b/book/PLAN-recipes.md @@ -1,6 +1,6 @@ # Plan — the Recipes part -> **Status: drafted.** The part opener and the first two recipes are written and live in +> **Status: drafted.** The part opener and the first three recipes are written and live in > `src/recipes/` per the placement below (2026-08-05). This file remains as the drafting > record, the plans-directory way, and carries the backlog of future recipes. @@ -18,6 +18,7 @@ A new part after the machine part: - [How to read a recipe](recipes/cookbook.md) - [One machine, four decades](recipes/808-classics.md) - [Three oscillators into a ladder](recipes/minimoog.md) +- [The patches with names on them](recipes/moog-classics.md) ``` The introduction's organization list gains a matching Part IX bullet. @@ -57,6 +58,13 @@ Stated in the part opener (`recipes/cookbook.md`), enforced in drafting: `tap.adsr~` contours (with the period-correct release-switch note), gate/pitch plumbing, and bass + lead settings tables. Evidence borrowed: `vco.ipynb` and `ladder.ipynb` via their chapters. +- **`recipes/moog-classics.md` — The patches with names on them.** The voice above driven + at four records as deltas from its bass/lead tables: Winwood's "While You See a Chance" + hook, Worrell's "Flash Light" stacked-Minimoog bass, Wright's "Shine On" lead, and + Emerson's "Lucky Man" modular solo. Carries the answer to "do we need a Moog modular + object?" — no: a modular is routing freedom, and Max is the patch panel; the modules + already ship (`tap.vco~`/`tap.ladder~`/`tap.adsr~`/`tap.vca~`/`tap.noise~` + the + sequencer pair). Gear provenance is stated per patch (documented vs. reconstruction). ## Backlog — future recipes, roughly in order of pull @@ -72,6 +80,10 @@ Stated in the part opener (`recipes/cookbook.md`), enforced in drafting: - **Borrowed rooms, curated.** A short IR field guide for `tap.convolve~` — what to load, true-stereo vs. mono-in, pre-delay by trimming. - **The five-string drone.** `tap.5comb~` tunings as chord recipes. +- **The sequenced modular.** Berlin school and "I Feel Love": `tap.303.seq~` → `mtof~` → + the vco stack, gate → `tap.adsr~` — the scaffold is sketched at the top of + `moog-classics.md`; the recipe is patterns, ostinato transposition, and the hat-groove + glue. Each lands as one file in `src/recipes/` plus a SUMMARY line; no renumbering needed. diff --git a/book/src/SUMMARY.md b/book/src/SUMMARY.md index e407ec4..2b3062d 100644 --- a/book/src/SUMMARY.md +++ b/book/src/SUMMARY.md @@ -61,3 +61,4 @@ - [How to read a recipe](recipes/cookbook.md) - [One machine, four decades](recipes/808-classics.md) - [Three oscillators into a ladder](recipes/minimoog.md) +- [The patches with names on them](recipes/moog-classics.md) diff --git a/book/src/recipes/minimoog.md b/book/src/recipes/minimoog.md index 71f9d36..4ce7c41 100644 --- a/book/src/recipes/minimoog.md +++ b/book/src/recipes/minimoog.md @@ -8,7 +8,9 @@ actually means by "Moog" — the bass that walks and the lead that sings. The model here is the classic three-oscillator monosynth voice: three oscillators into a mixer, one four-pole ladder, one loudness contour, one filter contour, glide on the pitch. Nothing below requires an object the -package doesn't ship. +package doesn't ship. And once the voice stands, the [next +recipe](moog-classics.md) drives it at the records with names on them — +Winwood, Worrell, Wright, Emerson. Companion material: the [oscillator chapter](../vco.md) (the stack's rationale and the analog section's ranges), the [ladder diff --git a/book/src/recipes/moog-classics.md b/book/src/recipes/moog-classics.md new file mode 100644 index 0000000..ba6f029 --- /dev/null +++ b/book/src/recipes/moog-classics.md @@ -0,0 +1,171 @@ +# The patches with names on them + +The previous recipe built the three-oscillator voice. This one drives it at +four records — a blue-eyed-soul hook, the bassline that retired a bass +player, a singing art-rock lead, and the one-take modular solo that started +it all — and, along the way, answers a fair question: if "Lucky Man" was +played on a Moog *modular*, does the kit need a modular object? + +The provenance rule from the part opener applies double here, because gear +folklore is a genre of its own. For each patch the chapter says what is +documented about the record and what is reconstruction. And the standing +disclaimer stands: these settings chase the *sound*; the hands, the tape, +and the mix stay on the record. + +Every patch below is a delta against the wiring and tables of +[Three oscillators into a ladder](minimoog.md) — build that voice first. +Two performance tools recur, so here they are once: + +- **Vibrato** goes into each `tap.vco~`'s FM inlet, which is calibrated in + Hz. For vibrato that reads as a constant musical width, scale the LFO by + the note: `cycle~ 5.5` multiplied by 0.006 × the note's frequency is + about ±10 cents. Fade the LFO in with `line~` a beat after note-on — the + delayed vibrato is most of what makes a lead "sing." +- **Sequenced lines**: `tap.303.seq~` emits pitch as a MIDI-note signal and + a gate at 1.0/2.0 — `mtof~` turns the pitch into Hz for the oscillators' + signal inlets, and the gate drives `tap.adsr~` directly (it opens above + 0.5). The Moog voice sequenced this way is the classic + synth-line scaffold, slides included. + +## The Winwood hook — "While You See a Chance" (1980) + +What's documented: Winwood played essentially everything on *Arc of a +Diver* himself, synthesizers included; accounts of the rig put Moog +monosynths at the center of it. The reconstruction: the opening hook is a +brassy, open-filter lead with a fast attack and just enough glide to round +the corners — a patch that sits between horn section and organ, which is +very much a keyboardist's lead. + +Deltas from the lead patch: + +| control | setting | +|---|---| +| voices | 1 and 2 only, at f, `detune` −6 / +6; retire voice 3 | +| all `smooth` | 40 ms | +| ladder | `@resonance 0.3 @drive 6 @asym 0.3` | +| filter contour | `@attack 5 @decay 500 @sustain -6 @release 400`, amount 4500 Hz, base 400 Hz | +| loudness contour | `@attack 5 @decay 200 @sustain -2 @release 250` | + +The brass illusion is the filter contour's `sustain` sitting high (−6 dB): +the filter opens and *stays* open, so the tone holds its brightness through +the note instead of wah-ing. Play the hook in clean detached eighths — the +40 ms of glide only speaks when notes touch. + +## The bassline that retired a bass player — "Flash Light" (1977) + +What's documented, and gloriously so: Bernie Worrell built Parliament's +"Flash Light" bassline by stacking Minimoogs — the story is told with the +number three attached — playing the line keyboard-style under Bootsy +Collins' guitar. This is the patch where the previous chapter's "the stack +is most of the sound" rule gets its funk citation. + +Deltas from the bass patch: + +| control | setting | +|---|---| +| voices | 1 and 2 at f (`detune` −7 / +7), voice 3 at f ÷ 2, its `gain` −6 | +| all `smooth` | 35 ms | +| ladder | `@resonance 0.6 @drive 12 @asym 0.5 @comp 0.2` | +| filter contour | `@attack 1 @decay 150 @sustain -24 @release 150`, amount 2200 Hz, base 90 Hz | +| loudness contour | `@attack 1 @decay 250 @sustain -6 @release 100` | + +The rubber is the filter contour: near-instant attack, short decay, and a +`sustain` low enough (−24 dB) that every note is a squelch that immediately +ducks. `resonance 0.6` puts a vowel on the squelch; `drive 12` into the +tanh stages is the fat (the ladder chapter measures 16.5 % THD up there — +that's the point). Play staccato sixteenths with octave pops; let the 35 ms +glide smear only the connected passing notes. If the low end blurs, this is +the one patch where `comp` earns its raise: 0.2 keeps some droop-era +character while returning enough passband to anchor the root. + +## The singing lead — "Shine On You Crazy Diamond" (1975) + +What's documented: Richard Wright's rig in the *Wish You Were Here* +sessions included a Minimoog, and the singing synth lead lines in "Shine +On" are credited to it. The reconstruction: a nearly clean patch — this +lead's beauty is restraint, a barely-driven filter, and vibrato that +arrives late. + +Deltas from the lead patch: + +| control | setting | +|---|---| +| voices | 1 and 2 at f, `detune` −2 / +2 — a shimmer, not a chorus | +| all `smooth` | 15 ms | +| ladder | `@resonance 0.15 @drive 3 @asym 0.2` | +| filter contour | `@attack 30 @decay 900 @sustain -10 @release 700`, amount 3000 Hz, base 250 Hz | +| loudness contour | `@attack 8 @decay 300 @sustain -2 @release 500` | + +Then spend all your effort on the vibrato: 5.5 Hz, ±10 cents (the intro's +formula), faded in over ~400 ms after each phrase begins, and *not* on +every note. The patch is deliberately close to the ideal oscillator — +`imperfect 0.2`, drift at the polite end — because the expressive load is +carried by the hands, and everything the analog section adds here it adds +to sustained exposed notes. + +## The one-take solo — "Lucky Man" (1970), and the modular question + +What's documented: Keith Emerson's solo on "Lucky Man" was played on his +Moog modular system and famously kept from an improvised take — one of the +first Moog solos on a rock record, and for a generation of listeners the +first synthesizer they ever heard. The sound: a huge unison lead whose +actual melodic content is mostly *portamento* — sweeps and dives across +octaves, the glide circuit played as the instrument. + +Deltas from the lead patch: + +| control | setting | +|---|---| +| voices | all three; voice 3 up at f (unison), `detune` −5 / +4 / +7 | +| all `smooth` | 280 ms | +| ladder | `@resonance 0.2 @drive 8 @asym 0.4` | +| filter contour | `@attack 10 @decay 800 @sustain -4 @release 600`, amount 5000 Hz, base 800 Hz | +| loudness contour | `@attack 10 @decay 300 @sustain -1 @release 400` | + +At 280 ms of `smooth`, pitch is a place you *travel to*: hold a note, strike +one two octaves up, and the voice draws the line between them. That is the +solo. The filter stays essentially open (`sustain` −4 dB) because the +record's drama is in pitch, not timbre. + +So — does the kit need a Moog modular object? **No, because you are +holding one.** A modular synthesizer is oscillators, filters, envelopes, +and amplifiers with *no fixed routing*; the panel of patch cords is the +product. In this package the modules are `tap.vco~`, `tap.ladder~`, +`tap.svf~`, `tap.adsr~`, `tap.vca~`, `tap.noise~`, and the sequencer pair — +and Max itself is the patch panel, with the routing freedom no hardwired +monosynth voice (and no single "modular object") could offer. Everything +Emerson's system did on that solo — voices summed to one filter, one +loudness contour, glide on the pitch source — is the previous chapter's +wiring diagram; what the modular *added* was the freedom to have wired it +otherwise, and that freedom is the patching environment you are already +in. The one genuinely modular idiom worth calling out is the sequenced +line: `tap.303.seq~` → `mtof~` → the stack, gate → `tap.adsr~`, is the +Moog-sequencer scaffold of the Berlin school and "I Feel Love"-era disco — +no new object required, slides included. + +## What separates the four + +The instructive part of putting these side by side: the signal chain never +changed. What moved: + +1. **The filter contour's `sustain`.** High and it's brass (Winwood), open + and it's drama (Emerson), low and it's rubber (Worrell). One attribute + spans the genre map. +2. **`smooth`.** 15 ms is articulation, 40 ms is rounding, 280 ms is the + melody itself. +3. **`drive` and `resonance`.** The funk patch is the only one leaning + hard on both — and it's the one imitating three stacked instruments. +4. **The hands.** Delayed vibrato, staccato versus legato, when *not* to + play — the parts of the record the recipe honestly can't ship. + +## When to leave the recipe + +- **You want the record's whole arrangement.** The hook was never alone: + Winwood's is doubled, Worrell's sits under a live band, Wright's floats + on tape-delayed guitars. The patch is the voice, not the mix. +- **You want polysynth-era sounds.** Prophets and Oberheims are a + different architecture — per-voice envelopes on real polyphony — and + imitating them with `mc.` stacks of this voice flatters neither. +- **You want the sequenced-modular genre.** Start from the scaffold above, + but that recipe deserves its own chapter — it lives in the plan file's + backlog with "I Feel Love" written on it. From 6546cc460ac1b58b6d01e4de289caf6d8d624eca Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 5 Aug 2026 02:27:50 +0000 Subject: [PATCH 03/12] Ship the remaining seven Recipes chapters, completing Part IX The second wave, each drafted against a fresh wrapper-source sweep: the acid line (the Phuture knob-riding method, lane messages, the measured accent-run bloom), the sequenced modular (Berlin school and "I Feel Love" off tap.303.seq~ through mtof~ into the Moog voice), the robot voice (carrier casting with the noise layer as sibilance budget), shimmer (the full spiral-into-wash chain with variants), the funk envelope filter (clav chop, bass quack, cocked wah, and the sidechain/ envelope-outlet patch points), a field guide to rooms (IR curation and placement for tap.convolve~), and comb drones (five keepable tunings and the morph gesture). The drafting audit also caught and fixed a shipped-chapter drift: the pitchaccum chapter documented pitch1/feedback1 with 0..1 feedback values, but the wrapper spells them trans1/fb1 on a 0-99 scale; the rooms recipe documents the buffer~-plus-set loading contract explicitly. New findings (uninterpolated tap.delay~/tap.multitap~, tap.verb~'s std::rand() nondeterminism, the vco signal-inlet glide gap, the missing vocoder sibilance path) are recorded in TapTools-Max's plans/recipes-improvements.md. Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01V6CC6kpK5Lx2YkJWuNNQpw --- book/PLAN-recipes.md | 64 ++++++++++------ book/src/SUMMARY.md | 7 ++ book/src/pitchaccum.md | 21 +++--- book/src/recipes/acid-line.md | 102 +++++++++++++++++++++++++ book/src/recipes/comb-drones.md | 71 +++++++++++++++++ book/src/recipes/funk-filter.md | 79 +++++++++++++++++++ book/src/recipes/robot-voice.md | 77 +++++++++++++++++++ book/src/recipes/rooms.md | 86 +++++++++++++++++++++ book/src/recipes/sequenced-modular.md | 105 ++++++++++++++++++++++++++ book/src/recipes/shimmer.md | 89 ++++++++++++++++++++++ 10 files changed, 669 insertions(+), 32 deletions(-) create mode 100644 book/src/recipes/acid-line.md create mode 100644 book/src/recipes/comb-drones.md create mode 100644 book/src/recipes/funk-filter.md create mode 100644 book/src/recipes/robot-voice.md create mode 100644 book/src/recipes/rooms.md create mode 100644 book/src/recipes/sequenced-modular.md create mode 100644 book/src/recipes/shimmer.md diff --git a/book/PLAN-recipes.md b/book/PLAN-recipes.md index 59fac66..d521034 100644 --- a/book/PLAN-recipes.md +++ b/book/PLAN-recipes.md @@ -1,8 +1,10 @@ # Plan — the Recipes part -> **Status: drafted.** The part opener and the first three recipes are written and live in +> **Status: drafted.** The part opener and all ten recipes are written and live in > `src/recipes/` per the placement below (2026-08-05). This file remains as the drafting -> record, the plans-directory way, and carries the backlog of future recipes. +> record, the plans-directory way. The improvement findings the drafting surfaced live in +> `plans/recipes-improvements.md` in the TapTools-Max repo (the design-of-record for object +> changes); new recipes now wait on new objects. Planning document for Part IX of *Tools on Tap*: **Recipes** — the book's third kind of chapter. Parts I–VII say what each object is for; Part VIII says why to trust it; a recipe @@ -19,6 +21,13 @@ A new part after the machine part: - [One machine, four decades](recipes/808-classics.md) - [Three oscillators into a ladder](recipes/minimoog.md) - [The patches with names on them](recipes/moog-classics.md) +- [Move a knob while it loops](recipes/acid-line.md) +- [The ostinato machine](recipes/sequenced-modular.md) +- [The robot on the radio](recipes/robot-voice.md) +- [The staircase and the wash](recipes/shimmer.md) +- [Sixteenths into a listening filter](recipes/funk-filter.md) +- [A field guide to rooms](recipes/rooms.md) +- [Chords with no keyboard](recipes/comb-drones.md) ``` The introduction's organization list gains a matching Part IX bullet. @@ -66,26 +75,37 @@ Stated in the part opener (`recipes/cookbook.md`), enforced in drafting: already ship (`tap.vco~`/`tap.ladder~`/`tap.adsr~`/`tap.vca~`/`tap.noise~` + the sequencer pair). Gear provenance is stated per patch (documented vs. reconstruction). -## Backlog — future recipes, roughly in order of pull - -- **The acid line.** `tap.303.seq~` patterns that exploit the measured couplings: accent - runs into the C13 bloom (the ×1.94 wow), slide chains, `envmod`/`decay` interplay. - Mostly written already in spirit across the acid chapter; the recipe is patterns. -- **The robot voice.** `tap.vocoder~` driven properly: carrier choice (saw stack vs. - noise blend), band count trades, the sibilance path. -- **Shimmer.** `tap.pitchaccum~` + `tap.verb~`/`tap.convolve~` — the accumulating-fifths - pad, with the honest feedback-headroom accounting. -- **The funk envelope filter.** `tap.autowah~` against the calibrated hardware curves; - clav and bass settings. -- **Borrowed rooms, curated.** A short IR field guide for `tap.convolve~` — what to load, - true-stereo vs. mono-in, pre-delay by trimming. -- **The five-string drone.** `tap.5comb~` tunings as chord recipes. -- **The sequenced modular.** Berlin school and "I Feel Love": `tap.303.seq~` → `mtof~` → - the vco stack, gate → `tap.adsr~` — the scaffold is sketched at the top of - `moog-classics.md`; the recipe is patterns, ostinato transposition, and the hat-groove - glue. - -Each lands as one file in `src/recipes/` plus a SUMMARY line; no renumbering needed. +## The second wave (shipped 2026-08-05) + +All seven backlog recipes landed in one pass, each drafted against a fresh wrapper-source +sweep (the audit found and fixed a shipped-chapter drift along the way: the pitchaccum +chapter's `pitch1`/`feedback1` spellings are actually `trans1`/`fb1`, feedback on a 0–99 +scale — corrected in `src/pitchaccum.md`): + +- **`recipes/acid-line.md` — Move a knob while it loops.** The Phuture method: a 16-step + line (grids + the `pitches`/`gates`/`accents`/`slides` lane messages), the knob rides, + accent runs into the measured ×1.94 C13 bloom, `tap.overdrive~` after. +- **`recipes/sequenced-modular.md` — The ostinato machine.** Berlin school / "I Feel + Love": `tap.303.seq~` → `mtof~` → external slew → the Moog voice; transpose as harmony; + the honest wrinkle that the vco's signal inlet bypasses `smooth` (→ improvements plan). +- **`recipes/robot-voice.md` — The robot on the radio.** Carrier casting (saw pair + 10 % + noise as the sibilance budget), the three settings rows (talk/choir/rhythm-transfer), + the left-inlet-is-modulator debugging fact. +- **`recipes/shimmer.md` — The staircase and the wash.** The full Eno-school chain: + pitchaccum spiral (+12/+7) into `tap.verb~` or a convolved church; damping as the + make-or-break; descent, micro-halo, and morph-gesture variants. +- **`recipes/funk-filter.md` — Sixteenths into a listening filter.** Clav chop, bass + quack (factory slot 2), cocked wah (slot 4), the sidechain and envelope-outlet patch + points; honest Mu-Tron distancing per the autowah chapter. +- **`recipes/rooms.md` — A field guide to rooms.** IR curation for `tap.convolve~`: + shopping list, sixty-second audition drill, placement (`predelay` first, `blocksize` by + role, `set` for performance swaps). +- **`recipes/comb-drones.md` — Chords with no keyboard.** Five `tap.5comb~` voicings as a + keepable table (factory, open fifth, just major, dark cluster, √2 bell plate), ringing + techniques, the eight-second morph gesture. + +New recipes now wait on new objects (or on the improvements plan landing — e.g. the vco +performance section would simplify the Moog chapters' vibrato plumbing). ## Notes for drafting diff --git a/book/src/SUMMARY.md b/book/src/SUMMARY.md index 2b3062d..8cfbc19 100644 --- a/book/src/SUMMARY.md +++ b/book/src/SUMMARY.md @@ -62,3 +62,10 @@ - [One machine, four decades](recipes/808-classics.md) - [Three oscillators into a ladder](recipes/minimoog.md) - [The patches with names on them](recipes/moog-classics.md) +- [Move a knob while it loops](recipes/acid-line.md) +- [The ostinato machine](recipes/sequenced-modular.md) +- [The robot on the radio](recipes/robot-voice.md) +- [The staircase and the wash](recipes/shimmer.md) +- [Sixteenths into a listening filter](recipes/funk-filter.md) +- [A field guide to rooms](recipes/rooms.md) +- [Chords with no keyboard](recipes/comb-drones.md) diff --git a/book/src/pitchaccum.md b/book/src/pitchaccum.md index bf5841a..79e5999 100644 --- a/book/src/pitchaccum.md +++ b/book/src/pitchaccum.md @@ -44,7 +44,7 @@ staircase climbs; in the ordinary patch every echo is the same interval.* ## The knobs, one by one (per shadow, ×2) -### `pitch1` / `pitch2` — the step of the staircase +### `trans1` / `trans2` — the step of the staircase ±24 semitones, continuous. Musical intervals (+7, +12, +5) make harmony; small offsets (±0.1–0.3 st) make lush detune-echo instead of a spiral; @@ -55,12 +55,12 @@ negative values descend into the dark version nobody expects. Up to 3 s per shadow. Short (50–150 ms) blurs the passes into a texture; long (0.5–2 s) articulates each step of the climb as an audible echo. -### `feedback1` / `feedback2` — how many steps +### `fb1` / `fb2` — how many steps -How much survives each trip. 0.3 gives two or three audible generations; 0.7 -a long climb; 0.9+ a texture that essentially sustains until the transposition -walks it out of range (energy shifted past the audible band is the spiral's -natural exit). +How much survives each trip, 0–99. 30 gives two or three audible +generations; 70 a long climb; 90+ a texture that essentially sustains until +the transposition walks it out of range (energy shifted past the audible +band is the spiral's natural exit). ### `xfade` — the grain crossfade @@ -87,13 +87,14 @@ spirals and a timed `recall` between them is a gesture in itself. ## Recipes -- **Shimmer, the classic:** shadow 1 at +12, delay ~400 ms, feedback 0.75; - shadow 2 at +7, delay ~650 ms, feedback 0.6; both into a reverb +- **Shimmer, the classic:** shadow 1 at +12, delay ~400 ms, `fb1 75`; + shadow 2 at +7, delay ~650 ms, `fb2 60`; both into a reverb (`tap.convolve~` with a long church, or `tap.verb~`). The reverb is - load-bearing — shimmer is spiral *plus* wash. + load-bearing — shimmer is spiral *plus* wash. The full patch has its own + recipe in Part IX. - **The descent:** −5 and −12, long delays, moderate feedback — a staircase into the basement, much rarer and much creepier. -- **Micro-thickener:** ±0.15 st, 60/90 ms delays, feedback 0.5, `xfade` +- **Micro-thickener:** ±0.15 st, 60/90 ms delays, feedback 50, `xfade` wide — not a spiral at all, just an expensive-sounding widener. ## When it is not the right tool diff --git a/book/src/recipes/acid-line.md b/book/src/recipes/acid-line.md new file mode 100644 index 0000000..b916e88 --- /dev/null +++ b/book/src/recipes/acid-line.md @@ -0,0 +1,102 @@ +# Move a knob while it loops + +The documented origin story of acid house is an instruction manual for this +recipe: in Chicago around 1985–87, Phuture (DJ Pierre, Spanky, Herk) let a +secondhand TB-303 loop a pattern and *turned the knobs while it played* — +"Acid Tracks" is twelve minutes of that. The lesson generalizes: an acid +line is not a melody with a sound; it is a **loop plus a hand**. The +pattern's job is to give the couplings something to chew on — accents for +the bloom, slides for the vowels — and the performance is `cutoff`, +`resonance`, and `envmod` moving in real time. + +Everything measured here is borrowed from [the acid machine +chapter](../acid.md) and its notebooks +([`tb303.ipynb`](https://github.com/tap/TapTools/blob/main/notebooks/tb303.ipynb), +[`step_seq.ipynb`](https://github.com/tap/TapTools/blob/main/notebooks/step_seq.ipynb)). + +## The scaffold + +```text +phasor~ (BPM/240) ──▶ tap.303.seq~ ──pitch──▶ tap.303~ ──▶ out + └──gate───▶ (right inlet) +``` + +One bar of 16 steps per phasor cycle (BPM ÷ 240, the drum scaffold's math); +~125 BPM → `phasor~ 0.5208`. The sequencer's pitch and gate outlets are the +voice's own contract — accents ride the gate at 2.0, slides are pitch +changes under a held gate, so the voice's ~60 ms RC does the glide. + +## A line to start from + +Program per step (`step [accent] [slide]`, `rest `) or per +lane. A serviceable opener in A — and, as everywhere in this part, a +starting point, not a transcription: + +```text +step: 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 +pitch: 33 33 45 33 33 36 33 31 33 33 45 47 33 33 31 36 +gate: x x x x . x x x x x x x . x x x +accent: A . . A . . A . . A . . . . A . +slide: . . . . . . . S . . . S . . . . +``` + +```text +pitches 33 33 45 33 33 36 33 31 33 33 45 47 33 33 31 36 +gates 1 1 1 1 0 1 1 1 1 1 1 1 0 1 1 1 +accents 1 0 0 1 0 0 1 0 0 1 0 0 0 0 1 0 +slides 0 0 0 0 0 0 0 1 0 0 0 1 0 0 0 0 +``` + +The ingredients that make it acid rather than bass: the octave jumps +(33 → 45), at least one slide *into* a note (the flag sits on the target +step), rests that let the filter close, and accents placed where the groove +leans — not where the melody peaks. + +## The voice + +`recall 1` is the factory "squelch" and a fine start. Explicitly: + +```text +@waveform saw @cutoff 500 @resonance 0.9 @envmod 0.7 @decay 300 @accent 0.8 +``` + +Then the moves, in the order a set builds: + +1. **Ride `cutoff`.** 300 → 2000 Hz over eight bars and back. This is the + genre. Remember the modeled `envmod` law: 2/3 of the envelope's sweep + sits above the knob, 1/3 below, and the resting point shifts as you turn + it — the knobs interact like the hardware because the interaction is + modeled. +2. **Stack the accents.** Runs of accented notes at high `resonance` are + the wow: the C13 capacitor doesn't fully discharge between close + accents, and the measured cutoff-peak bloom across a run is **×1.94**. + Put three accents in a row somewhere and listen to the third one open. +3. **Raise `resonance` into the break.** Past 1.0 is the documented bend + territory — a stock 303 never self-oscillates, and neither does this + filter until you push it there deliberately. +4. **`waveform square` for the hollow verse, saw for the drop.** +5. **`vca warm`** thickens exactly where the hardware does — measured 5.4 % + difference signal on quiet notes, 11.5 % on hot accents. +6. **Transpose, don't re-program:** `transpose -12` on the sequencer for + the sub-drop, `+5`/`+7` for the question-answer sections. It shifts + live, like the hardware's transpose mode without the mode. + +## After the voice + +Acid techno's other instrument is the distortion pedal: `tap.overdrive~` +after the voice, driven hard, is the documented lineage (a 303 into a +screaming feedback overdrive is half the harder end of the genre). Keep +`mute` in reach on the sequencer for breakdowns — it drops the gate but the +clock keeps running, so the line re-enters exactly in place. + +## When to leave the recipe + +- **You're programming melodies.** If the line only sounds right without + slides or accents, it isn't an acid line yet — or it wants the generic + bass rig (`tap.vco~` + `tap.svf~` + `tap.adsr~`) instead of this voice's + refusals. +- **You want the filter alone** — `tap.diode~` gives you the 303's ladder + on any source, squelch and all, without the biography. +- **You want hands-free evolution.** The 303 rewards a hand on a knob; if + the patch must run itself, store extremes in the voice's preset slots and + ride timed `recall` morphs instead — a different instrument, honestly. diff --git a/book/src/recipes/comb-drones.md b/book/src/recipes/comb-drones.md new file mode 100644 index 0000000..5182f10 --- /dev/null +++ b/book/src/recipes/comb-drones.md @@ -0,0 +1,71 @@ +# Chords with no keyboard + +The comb-bank chapter ends on "strings, chords, drones, and gestures; no +guitar required" — this recipe supplies the chords. `tap.5comb~`'s five +voices tune in Hz (`freq1..5`), which means voicings are numbers you can +keep, trade, and morph between; below is a small book of them, plus the +excitation and morph craft that turns a filter bank into an instrument. + +The mechanics cited here — ring time on a log map (20 ms–100 s), Hermite +tuning, `warp`'s stretched partials, `phase`'s midpoint pluck — are +measured and explained in [five strings, no guitar](../fivecomb.md) and +[its machine chapter](../machine/comb.md). + +## Voicings to keep + +Tunings in Hz; MIDI equivalents in parentheses for orientation. (The +object speaks Hz only — keep `mtof` handy, or this table.) + +| voicing | freq1..5 | character | +|---|---|---| +| the factory chord | 80 / 120 / 160 / 200 / 102 | the legacy preset: a root-fifth-octave stack with a rub (102 against 80) | +| the open fifth | 55 / 110 / 165 / 220 / 330 (A1, A2, E3, A3, E4) | power-chord drone; nothing to clash with any source | +| the major glow | 110 / 165 / 220 / 275 / 330 (A2, E3, A3, ~C#4, E4) | just-intonation major: 275 is a pure 5/4 third, warmer than 12-TET's 277.2 | +| the dark cluster | 65.4 / 77.8 / 98 / 130.8 / 196 (C2, D#2, G2, C3, G3) | minor with a low rub; film-cue territory | +| the bell plate | 210 / 297 / 420 / 594 / 841 | non-octave (√2 ratios): inharmonic, gong-ish before `warp` even arrives | + +Masters make voicings performable: `freq` (0..2) transposes the whole +bank proportionally — chords stay chords under the glide — and `res`/`lp` +scale ring and brightness bank-wide. + +## Ringing them + +- **Drone:** `res1..5 85`, `lp` toward 5000. Feed it *anything* quiet and + sustained — pink noise at low level, a field recording, your room tone. + At `res` ≈ 100 the bank sustains essentially forever; the input stops + being audio and becomes bowing pressure. +- **Pluck:** `res1..5` around 60–70 and excite with clicks or a sparse + `tap.808.rim~` (`@model claves`) pattern — every tick strums the chord. + Drums work; speech works eerily well (the chapter's "resonator chord"). +- **Strings, stiffened:** `warp 40` stretches the upper partials sharp — + piano-ish, then bell-ish — while the compensated main tap keeps the + *pitch* put. Pair with `lp` near 3000 for the felt-hammer version. +- **The midpoint pluck:** `phase 100` cancels the even harmonics — the + hollow, clarinet-adjacent voicing of a string plucked exactly at its + middle. On the bell plate tuning it turns purely ceremonial. + +Watch the sum: five ringing combs stack like five strings. Ride `gain` +down as `res` goes up, and `tap.limi~` on the output is cheap insurance +for the `res 100` lifestyle. + +## The gesture + +The bank's real instrument is the morph engine. Store the major glow in +slot 1 and the dark cluster in slot 2 — then `recall 2 8000` and every +frequency, ring time, and damping glides for eight seconds *through +tunings you never chose*, Hermite interpolation keeping the sweep +continuous instead of zippered. The chapter's advice stands: automate +nothing else. One long morph over a static source is a complete piece of +sound design; grabbing a single fader mid-morph overrides just that +parameter, which is the escape hatch when the in-between territory finds +something worth keeping. + +## When to leave the recipe + +- **One resonance, surgically placed:** `tap.comb~` is the single unit, + or `tap.svf~ @type bell` when you want EQ, not a string. +- **You want echoes.** Combs long enough to hear as repeats are delays + wearing a costume — `tap.delay~`/`tap.multitap~` are the honest tools. +- **You want more than five strings.** The count is fixed; `mc.` wrapping + the whole bank gives you choirs of banks, at which point you are + building a sympathetic-string instrument and should budget CPU like it. diff --git a/book/src/recipes/funk-filter.md b/book/src/recipes/funk-filter.md new file mode 100644 index 0000000..7245f4c --- /dev/null +++ b/book/src/recipes/funk-filter.md @@ -0,0 +1,79 @@ +# Sixteenths into a listening filter + +The envelope filter earned its place in funk on documented records — the +Mu-Tron-era clavinets and basses of the seventies, Stevie Wonder's +"Higher Ground" chief among them — and the autowah chapter is honest about +what this object is instead: a model of the Snow White AutoWah, a +different, throatier circuit. You are not summoning a Mu-Tron; you are +plugging into a very good pedal that listens the same way. The funk is in +what it listens *to* — which makes this the one recipe where the settings +table is half the story and your right hand is the other half. + +Measured behavior cited below (the sweep law exact to the design, the RC +release, the 250 Hz → ~2.5 kHz hardware span) lives in +[the pedal that listens](../autowah.md) and its +[validation notebook](https://github.com/tap/TapTools/blob/main/notebooks/autowah_validation.ipynb). + +## How to think about the knobs + +Two of them are calibration, one is the personality: + +- **`sensitivity`** matches the pedal to your source's level and your + touch. Tune it so your *normal* hits open the filter halfway and your + hard hits open it fully — the tanh knee compresses beyond that instead + of slamming. Too high and everything pins; too low and the filter + ignores you. +- **`bias` and `range`** set where the sweep lives: resting frequency and + octaves above it. The defaults (250 Hz, 3.3 octaves) *are* the hardware. +- **`decay`** is the personality: how fast the filter falls back. Tens of + ms is a wah articulation on every note — the funk setting. Hundreds is + a swell that rides phrasing. + +## The patches + +| patch | settings | +|---|---| +| the clav chop | `@sensitivity 3 @attack 2 @decay 80 @bias 250 @range 3.3 @resonance 0.7 @mix 100` | +| the bass quack | `recall 2`, then `@decay 150 @resonance 0.6` | +| the slow swell | `recall 3`, or `@decay 900 @range 2.5` on pads | +| the cocked wah | `recall 4` — `sensitivity` at −60 is the envelope off; park `bias` at 800–1200 Hz | + +- **The clav chop** wants sixteenth-note playing with deliberate dynamic + contrast — the filter turns your accents into vowels. `mode 1` + (bandpass, the circuit's other tap) is quackier and noticeably quieter; + make it up with `gain`. +- **The bass quack** starts from the factory bass voicing (slot 2 — + lower bias, tighter range, the GB pedal's instrument switch as a + preset). Fingers, not pick, and let notes ring — the release is a real + RC discharge (measured: a pure exponential, σ = 0.004) and it *sounds* + like circuitry when you leave it room. +- **The cocked wah** is the secret mode: a fixed resonant filter with + `bias` as a manual sweep — the parked-pedal midrange honk, and slot 4 + ships it. +- **`direction 1`** sweeps *down* from bias — the extension the pedal + never had; reverse-envelope funk on a clean chop is startling. + +## The two patch points nobody uses enough + +- **The sidechain (right inlet):** one sound wahs another. Kick → + sidechain, pad → filter is the classic; a `tap.808.seq~` row (through + `@pulse` widened impulses) makes the filter *sequenced* while the pad + sustains — an envelope filter with a drummer's timing. +- **The envelope outlet (right outlet, 0..1 signal):** the detector as a + free modulation source. Scale it into `tap.vco~`'s FM inlet, a + `tap.vca~` gain, or a second filter — one performance, many + destinations. (In `bypass` the outlet goes to zero, so tap it from a + live instance.) + +## When to leave the recipe + +- **Your source has no dynamics.** A static pad through an auto-wah is a + static filter — feed the sidechain something rhythmic, or use + `tap.svf~` with an LFO and own the motion yourself. +- **You want the filter on a knob.** That's the cocked wah until you want + *morphing* responses — then `tap.svf~`'s `morph` is the tool. +- **You want the exact Mu-Tron quack.** Raise `resonance`, try `mode 1`, + and know the chapter's warning stands: you're modding a Snow White. The + hardware A/B pass — the notebook cell waiting for the real pedal — will + tell us precisely how far the model is from *its own* hardware, not + from someone else's. diff --git a/book/src/recipes/robot-voice.md b/book/src/recipes/robot-voice.md new file mode 100644 index 0000000..6d1a767 --- /dev/null +++ b/book/src/recipes/robot-voice.md @@ -0,0 +1,77 @@ +# The robot on the radio + +The vocoder chapter closes on "the casting is everything," and this recipe +is the casting call. The sound has a documented pedigree — Bell Labs +speech-compression research became, in musicians' hands, Kraftwerk's robot +choirs and ELO's talking skies, and the machine has never left the radio +since — but the records disagree on gear and agree on craft: a bright, +busy carrier, an articulate modulator, and somebody enunciating like they +mean it. All three are patching decisions. + +Everything structural below is pinned by the kernel's tests and explained +in [the vocoder chapter](../vocoder.md): 24 bands, 50 Hz–12 kHz, everything +you hear is carrier. + +## The carrier, built properly + +The eternal failure is a dull carrier — high bands with nothing in them, +consonants gone. Build it in three layers: + +```text +tap.vco~ (saw, f) ──┐ +tap.vco~ (saw, f, +7 c) ──┼─▶ +~ ──▶ tap.vocoder~ right inlet +tap.noise~ (white) ─ *~ 0.1┘ +``` + +- **Two saws, a few cents apart** (`@shape 2`, `detune` ±4–7): harmonics + to the top of the range, and the beating keeps long vowels alive. Use + the [Moog recipe's](minimoog.md) stack values; skip the octave-down + voice — vocoded speech reads clearest with the energy above the + fundamental. +- **A tenth of white noise** (`tap.noise~ @mode white` through `*~ 0.1`): + this is the *s* and *t* budget. The object has no unvoiced/sibilance + path of its own, so the noise rides the carrier full-time and the + modulator's high-band envelopes gate it into consonants exactly when + needed. +- **Pitch is the performance.** The vocoder never changes the carrier's + pitch, so the carrier's notes are the melody. Held chords (an `mc.` + stack of carriers) make the robot a choir; a single line makes it a + lead vocalist. + +## The modulator, cast against type + +Articulation beats fidelity — the chapter's measured point is that band +envelopes carry everything, so contrast between bands is what you feed it. +A cheap dynamic mic is fine; compression helps; and over-enunciating +helps more than any knob. Keep the modulator out of the mix — the machine +uses it, nobody should hear it. + +## The three settings + +| patch | `q` | `response_interval` | the craft | +|---|---|---|---| +| the talking synth | 20 (default) | 30 | speak in rhythm; consonants land like drum hits | +| the choir | 10–15 | 250 | sing sustained vowels; the carrier chord is the harmony | +| rhythm transfer | 25–40 | 10–20 | drum loop as modulator; any sustained pad as carrier | + +`q` trades crispness against smoothness (narrow separates consonants, +wide blends vowels); `response_interval` is the mouth's speed — attack and +release in one knob. `gain` is linear makeup, and you will need some: a +band-multiplied signal lands quieter than either input. + +Two wiring facts that account for most dead patches: the **modulator is +the left inlet** (a synth weakly filtered by your voice means the cables +are backwards), and a silent carrier is silence no matter how loudly you +speak — pinned by test, and the fastest debugging question in vocoding. + +## When to leave the recipe + +- **You want tuned speech, not a played carrier** — the corrector + (`tap.tune~`) moves the voice itself; the vocoder wears the voice over + something else. Different identity theft. +- **You want formant-shifted or gender-shifted voice** — that's spectral + surgery, not band gating; the corridor starts at `tap.spectra~`. +- **You want intelligibility above all.** Twenty-four analog-style bands + are a voice, not a spectrograph; if every syllable must survive, dry + speech mixed under the vocoded double is the radio trick that always + works. diff --git a/book/src/recipes/rooms.md b/book/src/recipes/rooms.md new file mode 100644 index 0000000..cae4511 --- /dev/null +++ b/book/src/recipes/rooms.md @@ -0,0 +1,86 @@ +# A field guide to rooms + +The convolution chapter makes one promise that changes how you shop: +`tap.convolve~` is *exact* — measured to 10⁻¹² against direct convolution — +so the engine contributes no character at all. Everything the effect sounds +like is the impulse response you load. That turns "how do I get a good +reverb?" into "how do I find, judge, and place a good room?" — a curation +problem, and this recipe is the field guide. + +Companion material: [the convolution chapter](../convolve.md) and its +[verification notebook](https://github.com/tap/TapTools/blob/main/notebooks/convolution_reverb.ipynb); +every measured number cited below lives in one of them. + +## The shopping list + +An IR is a recording of a space answering a click, and the internet holds +decades of them — university acoustics archives, church-recording projects, +hardware-unit captures released by their communities. What to bring home, +by job: + +- **A church or concert hall (2–5 s).** The default "make it beautiful" + space. Long tails flatter sustained, sparse material and drown busy + mixes — the classic trade. +- **A plate.** Not a room at all — a steel sheet's dense, fast-building + wash. The vocal reverb of half the records you know; sits in a mix better + than any hall because it has no early-reflection "walls" to argue with + the stereo image. +- **A spring.** The lo-fi twang of amp reverb; gloriously wrong on drums. +- **A small real room (0.3–0.8 s).** The most useful and least glamorous + purchase: drums and guitars recorded dry come alive with a believable + space that reads as "a room," not "an effect." +- **Not a room.** The chapter's point stands in practice: any filter you + can record is loadable. A guitar body IR makes a piezo pickup sound like + wood; a vowel is a formant filter; a single click is a delay. + +Prefer **4-channel captures** when offered: the engine runs the full +true-stereo matrix (LL/LR/RL/RR), and the cross-feed paths are where +"being in the room" lives — measured in the notebook at exact path gains +with zero leakage. A 2-channel IR runs as dual mono (no cross-feed); a +mono IR is the same room on both sides. + +## Judging a room in sixty seconds + +Load it into the `buffer~`, then: + +1. **Send a click through and listen to the tail alone** (`mix` fully + wet). You are auditioning the IR itself — the engine adds nothing. A + good tail decays smoothly darker; a flutter or a metallic ring here + will be on everything you send. +2. **Check the onset.** Silence before the direct sound is pre-delay baked + into the capture — trim it in an editor or accept it, but *know* it's + there, because it stacks with the `predelay` you set and the engine's + own `blocksize` samples of latency. +3. **A/B at matched loudness.** `normalize 1` is on by default and is + energy-based, so a quiet cathedral capture and a hot plate land at + comparable levels — judge the room, not the gain staging. + +## Placing the room in a patch + +- **Send, don't insert.** One `tap.convolve~` fed by a send bus serves the + whole patch, glues sources into one space, and keeps the option of + riding the send. Keep `mix 100` (wet-only) on a send; use `mix` as an + insert dry/wet only on a single source. +- **`predelay` before you EQ.** 10–30 ms separates the dry attack from the + wash and buys clarity for free — the chapter's advice, and the first + knob to reach for when a reverb "swallows" a vocal. +- **`blocksize` by role.** Live input through the reverb: 64–128 (1.3–2.7 + ms at 48 kHz — the measured cost is exactly `blocksize` samples). Mix-bus + send: 512–2048, the CPU-cheap end, where the latency reads as a little + extra pre-delay you set once and forget. +- **Swap rooms as a performance move.** IR swaps are atomic and click-free + (measured RMS across the swap: 21.9 → 22.1) — load verse-room and + chorus-hall into two `buffer~` objects and rebind with `set ` + on the downbeat. (The buffer is the only way in: the object binds the + `buffer~` named by its first argument, and re-loading a file into that + buffer re-transforms the IR automatically.) + +## When to leave the recipe + +- **You want to *design* the tail** — decay and damping knobs, modulation, + gated endings. A static IR can't; `tap.verb~` is the algorithmic sibling + built for exactly that. +- **You want shimmer.** The wash is only half of it — the spiral half is + `tap.pitchaccum~`, and that pairing has its own recipe in this part. +- **You want zero latency.** `blocksize` samples, full stop; at 64 that's + small, not zero. diff --git a/book/src/recipes/sequenced-modular.md b/book/src/recipes/sequenced-modular.md new file mode 100644 index 0000000..88424d2 --- /dev/null +++ b/book/src/recipes/sequenced-modular.md @@ -0,0 +1,105 @@ +# The ostinato machine + +Two documented lineages share one patch. The Berlin school — Tangerine +Dream's *Phaedra* (1974) above all — put a Moog modular's step sequencer on +stage and let a filtered ostinato run for twenty minutes while hands moved +the cutoff. Three years later Giorgio Moroder and Donna Summer's "I Feel +Love" built an entire hit from a sequenced Moog modular bassline. The +Recipes part's Moog chapter argued you already own the modular — Max is the +patch panel; this recipe is that argument cashed in: the sequencer pair +driving the three-oscillator voice. + +## The scaffold + +```text +phasor~ (BPM/240) ──▶ tap.303.seq~ ──pitch──▶ mtof~ ──▶ slide~ ─┬─▶ tap.vco~ ──┐ + │ └─▶ tap.vco~ ──┼─▶ *~ ─▶ tap.ladder~ ─▶ tap.vca~ + └──gate──┬─▶ tap.adsr~ (filter) ─▶ *~ amount ─▶ +~ base ──▶ ▲ (cutoff) + └─▶ tap.adsr~ (loudness) ────────────────────────────▶ ▲ (gain) +``` + +- `tap.303.seq~`'s pitch outlet is a MIDI-note signal; `mtof~` turns it + into Hz for the oscillators' signal inlets. +- Its gate outlet (1.0 plain, 2.0 accented) drives both `tap.adsr~` + contours directly — the envelope opens above 0.5. +- **One honest wrinkle:** `tap.vco~`'s frequency *signal* inlet bypasses + the `smooth` ramp by design ("you are the smoothing") — so sequenced + pitch steps land as hard steps, and slide flags in the pattern won't + glide on their own. Put a one-pole slew (Max's `slide~`, or `rampsmooth~`) + between `mtof~` and the oscillators; the 303's ~60 ms RC is the reference + feel. Short slew = articulation, long slew = the Berlin swoop. +- The oscillator stack, ladder voicing, and envelope tables come from + [Three oscillators into a ladder](minimoog.md) — the bass patch is the + right starting point. One voice instead of three is period-correct for + the sequenced genre and cheaper; add the stack when the line is the whole + arrangement. + +## The line + +The genre's cell is small and the sequencer's phase math does the rest +(one bar per phasor cycle; a `length 8` row divides it into eighths — +polymeter as arithmetic, per [the sequencer chapter](../machine/seq.md)). + +The octave bounce, "I Feel Love"-school — `length 8`, every step gated: + +```text +step: 1 2 3 4 5 6 7 8 +pitch: 33 45 33 45 33 45 33 45 +``` + +```text +pitches 33 45 33 45 33 45 33 45 +gates 1 1 1 1 1 1 1 1 +``` + +The Berlin cell — `length 16`, a contour that repeats but doesn't resolve: + +```text +pitches 33 33 40 36 33 43 36 40 33 33 40 36 31 43 36 38 +gates 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 +``` + +Then the two moves that carry twenty minutes: + +1. **Transpose, sparsely.** `transpose 0 → 3 → 5 → 0` at phrase boundaries + is the harmonic language — one message, and the armed pattern semantics + keep everything on the grid. +2. **Ride the filter, slowly.** The loudness contour stays short and + percussive; your hand (or a very slow LFO into the `+~ base`) opens the + ladder over minutes, not bars. The ostinato doesn't change; the light + on it does. + +## Settings that read as the genre + +| control | setting | +|---|---| +| loudness `tap.adsr~` | `@attack 2 @decay 180 @sustain -12 @release 120` | +| filter `tap.adsr~` | `@attack 2 @decay 160 @sustain -20 @release 160`, amount 1800 Hz, base 150 Hz | +| ladder | `@mode 0 @resonance 0.3 @drive 6` | +| slew (`slide~`) | short; raise it only for deliberate swoops | +| seq | `@swing 0` — the genre is a grid, and the delay does the humanizing | + +Two period tricks worth their lines: pan alternate notes (a `length 8` row +of accents driving `tap.pan~` recreates the famous ping-pong doubling), and +put an eighth-note delay after the voice — the echo, not the sequencer, is +where these records' motion lives. Note `tap.delay~` is a plain +integer-sample delay (no feedback, no interpolation), so use it for the +single slap and patch feedback around it, or reach for Max's delay objects +for modulated regeneration. + +Glue: an 808 closed-hat row in 16ths from the drum scaffold, mixed low. +Accents in this scaffold are honest but blunt: `tap.adsr~` ignores the +gate's 2.0 amplitude today, so accent color comes from the voice you route +the accent lane to — or from leaning the pattern itself. + +## When to leave the recipe + +- **You want the 303's couplings** — slides that bloom, accents that + squelch. That's the [acid recipe](acid-line.md); this scaffold trades the + couplings for a filter and envelopes you choose. +- **You want generative movement.** This sequencer is deliberately + deterministic; probability and ratchets are future emitters, and + randomness belongs to objects that own a `seed`. +- **The line wants to be a song.** Sixty-four steps is the ceiling; past + that you're composing, and a piano roll is kinder than sixty-four `step` + messages. diff --git a/book/src/recipes/shimmer.md b/book/src/recipes/shimmer.md new file mode 100644 index 0000000..d7c0522 --- /dev/null +++ b/book/src/recipes/shimmer.md @@ -0,0 +1,89 @@ +# The staircase and the wash + +Shimmer has a documented birthplace: Brian Eno and Daniel Lanois in the +early eighties, feeding a pitch shifter and a reverb into each other until +a guitar came out sounding like weather. The pitchaccum chapter tells the +half of the story that lives inside one object — the transposer-delay loop +where every pass climbs again — and its recipes sketch the pairing. This +recipe is the whole patch: the spiral, the wash, and the mix decisions +that keep ten seconds of accumulated fifths from eating a track. + +Measured claims are borrowed from [the spiral staircase](../pitchaccum.md) +(the +7-becomes-+14 accumulation, the constant-sum grain envelopes, the +0.99 feedback cap) and [borrowed rooms](../convolve.md). + +## The chain + +```text +source ──▶ tap.pitchaccum~ ──▶ reverb (tap.verb~ or tap.convolve~) ──▶ return + └────────────────── dry path ───────────────────────────────────────▶ out +``` + +Run it as a send: the source stays dry and full-size in the mix, and the +shimmer return comes up underneath it like backlight. On the send, +`tap.pitchaccum~` at `mix 100` (its own dry path stays home) and the +reverb wet-only. + +## The spiral + +| control | setting | +|---|---| +| `trans1` / `delay1` / `fb1` / `gain1` | +12 st / 400 ms / 75 / 50 | +| `trans2` / `delay2` / `fb2` / `gain2` | +7 st / 650 ms / 60 / 50 | +| `xfade` | 60 — smooth flanks, soft attacks | +| `modfreq` / `moddepth` / `modphase` | 0.3 Hz / 0.1 st / 90° | +| `follow` | off for chords and pads; on for monophonic lines | + +The two shadows are doing different jobs: the octave climbs politely +(+12, +24, +36 — always consonant), while the fifth *rotates* the harmony +(+7, +14, +21 — a fifth, then a ninth, then a #11) and is where the +Eno-school mystery comes from. Pull `fb2` down toward 40 when the source +is already harmonically rich; push `fb1` toward 90 for the endless +version — the loop is capped and DC-blocked, so "too long" is an +aesthetic problem, not a stability one. The touch of modulation +(`moddepth 0.1`, with `modphase 90` breathing the shadows against each +other) keeps a long spiral from sounding cloned — depth stays subtle or +the climb turns seasick. + +## The wash + +Either reverb works; they fail differently: + +- **`tap.verb~`** (the designed tail): `@mix 100 @decay 8 @damping 4000 + @lowpass 8000 @delay 60 @modfreq 0.2 @moddepth 0.3`. The damping matters + more than the length — shimmer's accumulated highs need somewhere soft + to land, and 4 kHz of loop damping is the difference between glow and + glass dust. +- **`tap.convolve~`** (the borrowed room): a long church at `@mix 100 + @predelay 20`, and pick the IR by its top end — audition the tail alone + and reject anything that rings metallic up high, because the spiral + will find it. (The [field guide to rooms](rooms.md) has the audition + drill.) + +Order matters and is worth an experiment: spiral → reverb (above) washes +the staircase — the classic. Reverb → spiral transposes the *wash itself* +and is wilder and less controllable; the historical chains did both, +depending on the record. + +## Variants + +- **The descent:** `trans1 -5`, `trans2 -12`, long delays, feedback ~50 — + the staircase into the basement. Darker damping (2–3 kHz); the low + accumulation muddies fast, so shorter reverb. +- **The micro-halo:** `trans1 +0.15`, `trans2 -0.15`, delays 60/90 ms, + feedback ~50, `xfade` wide, modest reverb — no spiral at all, an + expensive-sounding widener that flatters pads. +- **The gesture:** store the halo in slot 1 and the full +12/+7 spiral in + slot 2, then `recall 2 8000` as the chorus lands — the morph engine + glides every parameter, and the *bloom* is the production moment. + +## When to leave the recipe + +- **The mix is dense.** Shimmer is backlight; on a busy arrangement it + reads as mud. It earns its keep on sparse sources — one guitar, one + voice, one held pad. +- **You want rhythmic echoes climbing in pitch.** The delays here serve + the loop, not the grid; that patch is a tempo-synced delay into + `tap.shift~`, built by hand. +- **You want the pitch to stay put.** Then it's just reverb — go straight + to the [field guide](rooms.md). From 001e875433ba7a3bc6e0919fdf4954ce8868db28 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 5 Aug 2026 02:38:42 +0000 Subject: [PATCH 04/12] Add the songbook to the vocoder recipe MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Four studies in casting, with provenance labeled per the part's rule: "In the Air Tonight" as the anti-robot patch (the VP-330 ghost choir — wide bands, slow mouth, no noise layer, mixed under the dry whisper), the front-and-center robots (ELO, Styx, the Beastie Boys, Kraftwerk's monophony) with the talkbox distinction kept straight, "Hide and Seek" honestly labeled a harmonizer rather than a vocoder — with the closer route built from parallel tap.shift~ voices fed by tap.semitone2ratio, capped at close voicings because granular shifting moves formants — and a plugin-era "Orange-school" carrier voiced from the package's own oscillators, with the house rule against reverse-engineering shipping products stated in print. Plan record updated. Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01V6CC6kpK5Lx2YkJWuNNQpw --- book/PLAN-recipes.md | 7 ++- book/src/recipes/robot-voice.md | 83 +++++++++++++++++++++++++++++++++ 2 files changed, 89 insertions(+), 1 deletion(-) diff --git a/book/PLAN-recipes.md b/book/PLAN-recipes.md index d521034..a44a7cb 100644 --- a/book/PLAN-recipes.md +++ b/book/PLAN-recipes.md @@ -90,7 +90,12 @@ scale — corrected in `src/pitchaccum.md`): the honest wrinkle that the vco's signal inlet bypasses `smooth` (→ improvements plan). - **`recipes/robot-voice.md` — The robot on the radio.** Carrier casting (saw pair + 10 % noise as the sibilance budget), the three settings rows (talk/choir/rhythm-transfer), - the left-inlet-is-modulator debugging fact. + the left-inlet-is-modulator debugging fact. Extended with the songbook: "In the Air + Tonight"'s VP-330 ghost choir, the front-and-center robots (ELO/Styx/Beasties/ + Kraftwerk), the talkbox distinction, "Hide and Seek" honestly labeled a harmonizer + (with the `tap.shift~` + `tap.semitone2ratio` stack as the closer route), and an + Orange-school plugin-era carrier — built as our own VA voicing, with the house rule + against reverse-engineering shipping products stated in print. - **`recipes/shimmer.md` — The staircase and the wash.** The full Eno-school chain: pitchaccum spiral (+12/+7) into `tap.verb~` or a convolved church; damping as the make-or-break; descent, micro-halo, and morph-gesture variants. diff --git a/book/src/recipes/robot-voice.md b/book/src/recipes/robot-voice.md index 6d1a767..8877733 100644 --- a/book/src/recipes/robot-voice.md +++ b/book/src/recipes/robot-voice.md @@ -64,6 +64,89 @@ the left inlet** (a synth weakly filtered by your voice means the cables are backwards), and a silent carrier is silence no matter how loudly you speak — pinned by test, and the fastest debugging question in vocoding. +## The songbook + +The famous "vocoder songs" are the best syllabus for the craft — partly +because several of them aren't vocoders, and knowing which is which +teaches more than any preset. Provenance below follows the part's rule: +documented where it's documented, labeled reconstruction where it isn't. + +### "In the Air Tonight" (1981) — the ghost choir + +What's documented: Phil Collins ran the verse vocal through a Roland +VP-330 — a *soft* vocoder, voiced like a string machine, mixed under a +nearly whispered dry vocal. The reconstruction: this is the anti-robot +patch. Carrier: two saws, `detune` ±4, `imperfect 0.3`, **no noise +layer** — sibilance is what you don't want here — through `tap.svf~` +(`@type lowpass @frequency 4000`) to take the glass off. Vocoder: +`q 8–12`, `response_interval 120` — wide bands and a slow mouth blur the +consonants into breath. Mix the vocoded return *under* the dry voice, a +shadow rather than a double. The dry whisper carries the words; the +vocoder carries the dread. + +### "Mr. Blue Sky" / "Mr. Roboto" / "Intergalactic" — the front-and-center robot + +ELO (EMS vocoders, documented), Styx, and the Beastie Boys are the +talking-synth patch played as a *lead*: bright carrier, crisp bands +(`q 20–30`), fast mouth (`response_interval 15–30`), and the melody in +the carrier's held notes while the words ride the modulator. Kraftwerk — +the genre's founders, on custom and commercial hardware across the +years — sit here too, usually with a single unison line rather than +chords: the robot speaks in monophony. Enunciate. Then enunciate more. + +One label to keep straight: Zapp, Roger Troutman, and the P-Funk +talkbox records are **not vocoders** — a talkbox pipes the carrier into +the performer's actual mouth and the room mic hears real articulation. +Chasing that sound with this object gets you a cousin, not the thing. + +### "Hide and Seek" (2005) — the one that isn't a vocoder + +What's documented: Imogen Heap sang into a harmonizer (the DigiTech +Vocalist lineage), a keyboard choosing the chord — so every sound on the +record is her *actual voice*, pitch-shifted into harmony, breath and +formants intact. That's why it doesn't sound like a robot; there is no +carrier. Two routes, honestly ranked: + +1. **The closer one — a shifter stack.** Voice into parallel + `tap.shift~` objects at chord intervals, dry voice summed in the + middle. `tap.semitone2ratio` exists for exactly this: `-5`, `+3`, + `+7` → ratios into each shifter's middle inlet. Keep the voicing + close (within ±7 st) — granular shifting moves formants with the + pitch, and wide intervals go chipmunk where the hardware's + formant-corrected voices didn't. Change the interval set per chord + (messages, or a small Max chord-to-ratios mapping) and you are + playing the record's instrument. +2. **The vibe — the choir patch above.** Speak-sing into the choir row's + settings with an `mc.` carrier holding the chords. It will sound like + a vocoder doing Imogen Heap, which is its own valid sound — just + don't mistake it for the record's mechanism. + +### The plugin-era default — an Orange-school carrier + +The late-90s software vocoders (the Orange Vocoder the most loved of +them) changed the *default sound* of the effect: where hardware +vocoders leaned on whatever synth was nearby, the plugins shipped with +a built-in, very bright virtual-analog carrier — so "the plugin sound" +is really a carrier voicing: wide, glossy, present. One honest line +first: that plugin is still a shipping commercial product, and the +house provenance rule applies — nothing here reverse-engineers it. What +follows is *our* bright VA carrier in that school, built from this +package's own oscillator: + +```text +tap.vco~ (saw, f, detune -6, seed 11) ──┐ +tap.vco~ (saw, f, detune +6, seed 22) ──┼─▶ +~ ─▶ tap.svf~ (highshelf) ─▶ carrier +tap.vco~ (saw, f+12, gain -6, seed 33) ──┤ +tap.noise~ (white) ─ *~ 0.08 ─────────────┘ +``` + +All three oscillators `@shape 2 @imperfect 0.2 @jitter 2`; the octave-up +voice adds the gloss the era is remembered for; `tap.svf~ @type +highshelf @frequency 6000 @gain 4` is the sheen. Vocoder settings: +`q 25`, `response_interval 20`. Play the carrier in fifths and octaves +rather than full triads — the brightness supplies the width, and triads +in a bright carrier smear the consonant bands. + ## When to leave the recipe - **You want tuned speech, not a played carrier** — the corrector From 59d5777f4bca67119ad05d22ab7029aa7e4827de Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 5 Aug 2026 02:54:54 +0000 Subject: [PATCH 05/12] Add the harmonizer kernel: four formant-preserving voices plus aligned dry MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit taptools/harmonizer.h (tap::tools::harmony::harmonizer) is the keyboard-harmonizer effect — up to four pitch-shifted copies of a monophonic source holding musical intervals, summed with a dry path the kernel delays to the voices' emission time so chords land as chords rather than slapback. Each voice is a tap::dsp::pvoc (Laroche-Dolson peak-locked shifting) with LPC formant preservation on by default; both algorithms live in DspTap and come from published literature, so this kernel is composition and control. Intervals are fractional semitones clamped to +/-24 (exactly the pvoc ratio contract) gliding through a semitone-domain one-pole; gains ride their own slews; silent voices are skipped for CPU and re-enter cold by design, stated in the header with the other honest limits (one-frame latency, pvoc transient smearing, voice-oriented formant model). Seven Catch2 scenarios pin the contract, house-style: solo voices land their intervals under the DspTap yin oracle (both directions), the dry path is sample-aligned with a unity voice to 1e-6, chords stay bounded with both intervals present, a synthetic formant bump stays home only with the flag on, glide walks the pitch through the middle, and a re-enabled voice returns finite and audible. The C ABI and ctypes bridge gain the kernel (taptools_harmonizer_*, Harmonizer with a chord() helper) per the verification-layer rule; README's pitch table gains the row. Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01V6CC6kpK5Lx2YkJWuNNQpw --- README.md | 7 +- include/taptools/harmonizer.h | 221 +++++++++++++++++++++++++++++++ notebooks/taptools_py.py | 63 +++++++++ tests/CMakeLists.txt | 1 + tests/harmonizer_test.cpp | 242 ++++++++++++++++++++++++++++++++++ tools/capi/taptools_capi.cpp | 60 +++++++++ tools/capi/taptools_capi.h | 16 +++ 7 files changed, 607 insertions(+), 3 deletions(-) create mode 100644 include/taptools/harmonizer.h create mode 100644 tests/harmonizer_test.cpp diff --git a/README.md b/README.md index d54c2f2..69302ed 100644 --- a/README.md +++ b/README.md @@ -62,12 +62,13 @@ header adds no nested namespace, the class) the kernel lives in. | Kernel | Max object | Contents | |---|---|---| | `tune.h` | `tap.tune~` | Monophonic pitch correction (`tap::tools::tune`) | +| `harmonizer.h` | `tap.harmony~` | Formant-preserving multi-voice harmonizer (`tap::tools::harmony`) | | `grm_comb.h` | `tap.5comb~` | GRM comb-bank recreation (`tap::tools::fivecomb`) | | `grm_pitchaccum.h` | `tap.pitchaccum~` | GRM PitchAccum recreation (`tap::tools::pitchaccum`) | -`taptools.h` is the umbrella header that pulls in every kernel above. `stft.h`, `tune.h` and -`conv_engine.h` reach into `tap::dsp` (the pinned DspTap submodule) for the real FFT and the pitch -primitives; every other kernel is standard library only. +`taptools.h` is the umbrella header that pulls in every kernel above. `stft.h`, `tune.h`, +`harmonizer.h` and `conv_engine.h` reach into `tap::dsp` (the pinned DspTap submodule) for the +real FFT and the pitch primitives; every other kernel is standard library only. Plus, all Max-free: diff --git a/include/taptools/harmonizer.h b/include/taptools/harmonizer.h new file mode 100644 index 0000000..64e38cc --- /dev/null +++ b/include/taptools/harmonizer.h @@ -0,0 +1,221 @@ +/// @file +/// @brief Portable formant-preserving multi-voice harmonizer kernel — no Max/Min dependency. +/// @details The keyboard-harmonizer effect (the DigiTech Vocalist lineage, "Hide and Seek"): +/// up to four pitch-shifted copies of a monophonic source, each holding a musical +/// interval, summed with an internally *latency-aligned* dry path so chords land as +/// chords rather than as slapback. Every voice is a tap::dsp::pvoc — the DspTap +/// phase vocoder's Laroche–Dolson peak-locked shifting — with LPC source-filter +/// formant preservation on by default, so shifted voices keep the singer's envelope +/// (the property that separates a harmonizer from a chipmunk chorus). Both +/// algorithms are implemented in DspTap from the published literature only, per the +/// project's IP policy; this kernel is composition and control. +/// +/// Intervals are set in (fractional) semitones, clamped to ±24 — exactly the pvoc +/// ratio contract [1/4, 4] — and glide toward their targets through a one-pole slew +/// in the semitone domain (`set_glide`), so chord changes are click-free at the +/// default 10 ms and become an audible portamento at hundreds of ms. Gains ride +/// their own short slews (no zippers, the house rule). +/// +/// Honest limits, stated where the next reader will look: +/// - Latency is exactly one FFT frame (`latency()` samples, fft_size; 1024 at +/// 48 kHz ≈ 21 ms). The dry path is delayed inside the kernel to match, so the +/// output is time-coherent but the *object* is not a zero-latency insert. +/// - The phase-vocoder class smears transients; dense percussive input is the +/// wrong material. The formant model (LPC order 48) is speech/voice-oriented. +/// - A voice whose gain sits at zero is skipped entirely to save CPU and its +/// engine is cleared on re-entry: expect one frame of silence, then the gain +/// slew, when a voice is enabled mid-performance. +/// - The source should be monophonic for musical results — polyphonic input +/// shifts, but the formant estimate and the intervals stop meaning anything. +/// @author Timothy Place +// SPDX-License-Identifier: MIT +// Copyright 2026 Timothy Place. + +#pragma once + +#include +#include +#include +#include +#include +#include + +#include "tap/dsp/pvoc.h" + +namespace tap::tools { + namespace harmony { + + constexpr int k_max_voices = 4; + constexpr double k_max_interval_st = 24.0; // == the pvoc ratio clamp [1/4, 4] + constexpr double k_max_gain = 2.0; // linear; wrappers speak dB + constexpr double k_default_glide_ms = 10.0; // click-free, not yet audible + constexpr double k_max_glide_ms = 2000.0; + constexpr double k_gain_slew_ms = 10.0; + constexpr double k_gain_epsilon = 1e-4; // below this a voice is "off" + constexpr size_t k_default_fft = 1024; // the pvoc desktop operating point + + /// Formant-preserving multi-voice harmonizer. House shape: prepare(sr) buys all + /// geometry, process(in) is per-sample and allocation-free, every setter is safe + /// while audio runs. + class harmonizer { + public: + /// Allocate the voice engines and the dry-alignment delay. @p fft_size follows + /// the pvoc contract (power of two, >= 64); the default is the intended + /// desktop operating point. + void prepare(double sr, size_t fft_size = k_default_fft) { + m_sr = sr; + m_fft = fft_size; + + m_voices.clear(); + m_voices.reserve(static_cast(k_max_voices)); + for (int v = 0; v < k_max_voices; ++v) { + auto& voice = m_voices.emplace_back(fft_size); + voice.set_formant(m_formant); + } + + m_dry_ring.assign(fft_size, 0.0); + m_dry_write = 0; + + m_gain_coeff = slew_coeff(k_gain_slew_ms); + set_glide(m_glide_ms); // recompute the glide coefficient for this rate + + for (int v = 0; v < k_max_voices; ++v) { + m_current_st[static_cast(v)] = m_target_st[static_cast(v)]; + m_current_gain[static_cast(v)] = m_target_gain[static_cast(v)]; + m_active[static_cast(v)] = m_target_gain[static_cast(v)] > k_gain_epsilon; + } + m_current_dry = m_target_dry; + } + + bool prepared() const { return !m_voices.empty(); } + + /// Emission delay, in samples: one FFT frame, dry path included. 0 before prepare(). + size_t latency() const { return prepared() ? m_fft : 0; } + + /// Set a voice's interval in fractional semitones, clamped to ±24. The voice + /// glides there through the `set_glide` slew. + void set_interval(int voice, double semitones) { + if (voice < 0 || voice >= k_max_voices) { + return; + } + m_target_st[static_cast(voice)] = std::clamp(semitones, -k_max_interval_st, k_max_interval_st); + } + + double interval(int voice) const { + return (voice >= 0 && voice < k_max_voices) ? m_target_st[static_cast(voice)] : 0.0; + } + + /// Set a voice's linear gain, clamped to [0, 2]. 0 disables the voice (its + /// engine is skipped and re-enters cold — see the header note). + void set_gain(int voice, double gain) { + if (voice < 0 || voice >= k_max_voices) { + return; + } + m_target_gain[static_cast(voice)] = std::clamp(gain, 0.0, k_max_gain); + } + + double gain(int voice) const { + return (voice >= 0 && voice < k_max_voices) ? m_target_gain[static_cast(voice)] : 0.0; + } + + /// Dry-path gain (latency-aligned inside the kernel), linear [0, 2], default 1. + void set_dry(double gain) { m_target_dry = std::clamp(gain, 0.0, k_max_gain); } + double dry() const { return m_target_dry; } + + /// LPC formant preservation on every voice (see tap::dsp::basic_pvoc). On by + /// default — it is the point of the object; off is the chipmunk-chorus bend. + void set_formant(bool on) { + m_formant = on; + for (auto& voice : m_voices) { + voice.set_formant(on); + } + } + bool formant() const { return m_formant; } + + /// Interval glide time constant, ms, clamped [0, 2000]. 0 snaps. + void set_glide(double ms) { + m_glide_ms = std::clamp(ms, 0.0, k_max_glide_ms); + m_glide_coeff = (m_glide_ms <= 0.0 || m_sr <= 0.0) ? 1.0 : slew_coeff(m_glide_ms); + } + double glide() const { return m_glide_ms; } + + /// Zero all running state. Slews jump to their targets so nothing fades in + /// from stale values after a transport reset. + void clear() { + for (auto& voice : m_voices) { + voice.clear(); + } + std::fill(m_dry_ring.begin(), m_dry_ring.end(), 0.0); + m_dry_write = 0; + for (int v = 0; v < k_max_voices; ++v) { + m_current_st[static_cast(v)] = m_target_st[static_cast(v)]; + m_current_gain[static_cast(v)] = m_target_gain[static_cast(v)]; + m_active[static_cast(v)] = m_target_gain[static_cast(v)] > k_gain_epsilon; + } + m_current_dry = m_target_dry; + } + + /// Consume one input sample; produce the harmonized sample for time + /// n - latency(). Passes the input through untouched before prepare(). + double process(double in) { + if (!prepared()) { + return in; + } + + // dry path, delayed to the voices' emission time + const double dry = m_dry_ring[m_dry_write]; + m_dry_ring[m_dry_write] = in; + m_dry_write = (m_dry_write + 1) % m_dry_ring.size(); + m_current_dry += m_gain_coeff * (m_target_dry - m_current_dry); + + double out = m_current_dry * dry; + + for (int v = 0; v < k_max_voices; ++v) { + const size_t i = static_cast(v); + const bool wanted = m_target_gain[i] > k_gain_epsilon; + + if (!wanted && m_current_gain[i] <= k_gain_epsilon) { + m_active[i] = false; + m_current_gain[i] = 0.0; + continue; // fully off: skip the engine entirely + } + if (wanted && !m_active[i]) { + m_voices[i].clear(); // re-enter cold, not with a stale splice + m_active[i] = true; + } + + m_current_st[i] += m_glide_coeff * (m_target_st[i] - m_current_st[i]); + m_current_gain[i] += m_gain_coeff * (m_target_gain[i] - m_current_gain[i]); + + const double ratio = std::exp2(m_current_st[i] / 12.0); + out += m_current_gain[i] * m_voices[i].process(in, ratio); + } + return out; + } + + private: + double slew_coeff(double ms) const { return 1.0 - std::exp(-1.0 / (ms * 0.001 * m_sr)); } + + double m_sr = 0.0; + size_t m_fft = 0; + + std::vector m_voices; + std::vector m_dry_ring; + size_t m_dry_write = 0; + + std::array m_target_st{}; + std::array m_current_st{}; + std::array m_target_gain{}; + std::array m_current_gain{}; + std::array m_active{}; + + double m_target_dry = 1.0; + double m_current_dry = 1.0; + bool m_formant = true; + double m_glide_ms = k_default_glide_ms; + double m_glide_coeff = 1.0; + double m_gain_coeff = 1.0; + }; + + } // namespace harmony +} // namespace tap::tools diff --git a/notebooks/taptools_py.py b/notebooks/taptools_py.py index 20acb6b..6bde0bc 100644 --- a/notebooks/taptools_py.py +++ b/notebooks/taptools_py.py @@ -216,6 +216,17 @@ def load() -> ctypes.CDLL: "taptools_tune_target_midi": ([vp], ctypes.c_double), "taptools_tune_applied_semitones": ([vp], ctypes.c_double), "taptools_tune_process": ([vp, f64p, f64p, ctypes.c_int], ctypes.c_int), + "taptools_harmonizer_create": ([], vp), + "taptools_harmonizer_destroy": ([vp], None), + "taptools_harmonizer_prepare": ([vp, ctypes.c_double, ctypes.c_int], ctypes.c_int), + "taptools_harmonizer_clear": ([vp], ctypes.c_int), + "taptools_harmonizer_set_interval": ([vp, ctypes.c_int, ctypes.c_double], ctypes.c_int), + "taptools_harmonizer_set_gain": ([vp, ctypes.c_int, ctypes.c_double], ctypes.c_int), + "taptools_harmonizer_set_dry": ([vp, ctypes.c_double], ctypes.c_int), + "taptools_harmonizer_set_formant": ([vp, ctypes.c_int], ctypes.c_int), + "taptools_harmonizer_set_glide": ([vp, ctypes.c_double], ctypes.c_int), + "taptools_harmonizer_latency": ([vp], ctypes.c_int), + "taptools_harmonizer_process": ([vp, f64p, f64p, ctypes.c_int], ctypes.c_int), "taptools_yin_create": ([ctypes.c_int, ctypes.c_int, ctypes.c_int], vp), "taptools_yin_destroy": ([vp], None), "taptools_yin_frame_size": ([vp], ctypes.c_int), @@ -814,6 +825,58 @@ def __del__(self): self._h = None +class Harmonizer: + """tap.harmony~'s kernel (tap::tools::harmony::harmonizer): up to four + formant-preserving pvoc voices at fixed intervals plus a latency-aligned + dry path. Intervals are fractional semitones; gains are linear.""" + + def __init__(self, sr: float = 48000.0, fft_size: int = 1024, **params): + self._h = _LIB.taptools_harmonizer_create() + _check(_LIB.taptools_harmonizer_prepare(self._h, float(sr), int(fft_size)), "prepare") + self.set(**params) + + def set(self, *, intervals=None, gains=None, dry=None, formant=None, glide=None) -> "Harmonizer": + if intervals is not None: + for v, st in enumerate(intervals): + _check(_LIB.taptools_harmonizer_set_interval(self._h, v, float(st)), "interval") + if gains is not None: + for v, g in enumerate(gains): + _check(_LIB.taptools_harmonizer_set_gain(self._h, v, float(g)), "gain") + if dry is not None: + _check(_LIB.taptools_harmonizer_set_dry(self._h, float(dry)), "dry") + if formant is not None: + _check(_LIB.taptools_harmonizer_set_formant(self._h, int(bool(formant))), "formant") + if glide is not None: + _check(_LIB.taptools_harmonizer_set_glide(self._h, float(glide)), "glide") + return self + + def chord(self, intervals, gain: float = 1.0) -> "Harmonizer": + """Enable the given intervals at equal gain; silence the remaining voices.""" + sts = list(intervals)[:4] + self.set(intervals=sts + [0.0] * (4 - len(sts)), + gains=[gain] * len(sts) + [0.0] * (4 - len(sts))) + return self + + @property + def latency(self) -> int: + return _LIB.taptools_harmonizer_latency(self._h) + + def process(self, x) -> np.ndarray: + x = _f64(x) + out = np.zeros_like(x) + _check(_LIB.taptools_harmonizer_process(self._h, _p64(x), _p64(out), x.size), "process") + return out + + def clear(self) -> None: + _check(_LIB.taptools_harmonizer_clear(self._h), "clear") + + def __del__(self): + h = getattr(self, "_h", None) + if h: + _LIB.taptools_harmonizer_destroy(h) + self._h = None + + class Yin: """The shared DspTap pitch detector (tap::dsp::yin), passed through the C ABI so the notebooks can track pitch with the same detector the corrector uses.""" diff --git a/tests/CMakeLists.txt b/tests/CMakeLists.txt index ab3f2ba..6e54341 100644 --- a/tests/CMakeLists.txt +++ b/tests/CMakeLists.txt @@ -15,6 +15,7 @@ add_executable(taptools_kernel_tests autowah_test.cpp diode_ladder_test.cpp grm_comb_test.cpp + harmonizer_test.cpp nr_test.cpp overdrive_test.cpp spectra_test.cpp diff --git a/tests/harmonizer_test.cpp b/tests/harmonizer_test.cpp new file mode 100644 index 0000000..fba6d9a --- /dev/null +++ b/tests/harmonizer_test.cpp @@ -0,0 +1,242 @@ +/// @file +/// @brief Unit tests for the multi-voice harmonizer kernel (tap::tools::harmony::harmonizer). +/// @details Drives the kernel with synthesized material and measures the output with the +/// DspTap YIN detector as the oracle (the house pattern) — a solo voice must land +/// its commanded interval, the dry path must be sample-aligned with the voices, +/// chords must stay bounded, formant preservation must keep a synthetic envelope +/// bump in place while the excitation moves, and disabled voices must re-enter +/// cleanly. Saw material throughout, per the shifter family's material contract. +// SPDX-License-Identifier: MIT +// Copyright 2026 Timothy Place. + +#include +#include +#include + +#include +#include +#include + +namespace { + + constexpr double k_pi = 3.14159265358979323846; + constexpr double k_sr = 48000.0; + + /// Band-limited-enough saw for test purposes: 20 harmonics. + double saw(int t, double f) { + double y = 0.0; + for (int h = 1; h <= 20; ++h) { + y += std::sin(2.0 * k_pi * f * h * t / k_sr) / h; + } + return y * (2.0 / k_pi); + } + + std::vector run_saw(tap::tools::harmony::harmonizer& hz, double freq, double seconds) { + const int n = static_cast(seconds * k_sr); + std::vector out(static_cast(n)); + for (int t = 0; t < n; ++t) { + out[static_cast(t)] = hz.process(saw(t, freq)); + } + return out; + } + + /// Fundamental of the signal's tail, via the certified DspTap detector. + double measure_hz(const std::vector& x) { + const size_t tau_min = static_cast(k_sr / 2000.0); + const size_t tau_max = static_cast(std::ceil(k_sr / 55.0)); + tap::dsp::yin det(tau_max, tau_min, tau_max); + REQUIRE(x.size() >= det.frame_size()); + const auto r = det.analyze(x.data() + (x.size() - det.frame_size())); + REQUIRE(r.voiced()); + return k_sr / r.period; + } + + double cents(double f, double ref) { + return 1200.0 * std::log2(f / ref); + } + + /// Projected magnitude at one frequency over the signal's tail (a one-bin DFT). + double band_mag(const std::vector& x, double f, size_t tail) { + std::complex acc{0.0, 0.0}; + const size_t start = x.size() - tail; + for (size_t t = start; t < x.size(); ++t) { + const double ph = 2.0 * k_pi * f * static_cast(t) / k_sr; + acc += x[t] * std::complex(std::cos(ph), -std::sin(ph)); + } + return std::abs(acc) / static_cast(tail); + } + +} // namespace + +SCENARIO("a solo voice lands its commanded interval") { + tap::tools::harmony::harmonizer hz; + hz.prepare(k_sr); + hz.set_dry(0.0); + hz.set_gain(0, 1.0); + hz.set_interval(0, 7.0); // a fifth up + + const auto out = run_saw(hz, 220.0, 1.5); + const double expected = 220.0 * std::exp2(7.0 / 12.0); + REQUIRE(std::abs(cents(measure_hz(out), expected)) < 10.0); +} + +SCENARIO("a downward voice lands too") { + tap::tools::harmony::harmonizer hz; + hz.prepare(k_sr); + hz.set_dry(0.0); + hz.set_gain(1, 1.0); + hz.set_interval(1, -5.0); // a fourth down + + const auto out = run_saw(hz, 220.0, 1.5); + const double expected = 220.0 * std::exp2(-5.0 / 12.0); + REQUIRE(std::abs(cents(measure_hz(out), expected)) < 10.0); +} + +SCENARIO("the dry path is sample-aligned with a unity voice") { + // At interval 0 the pvoc reconstructs its input delayed by exactly one frame + // (pinned in DspTap); the kernel's dry ring must line up with it exactly. + tap::tools::harmony::harmonizer hz; + hz.prepare(k_sr); + hz.set_dry(1.0); + hz.set_gain(0, 1.0); + hz.set_interval(0, 0.0); + + const int n = static_cast(1.0 * k_sr); + const size_t latency = hz.latency(); + REQUIRE(latency == 1024); + + std::vector in(static_cast(n)); + std::vector out(static_cast(n)); + for (int t = 0; t < n; ++t) { + in[static_cast(t)] = saw(t, 220.0); + out[static_cast(t)] = hz.process(in[static_cast(t)]); + } + + // After the slews settle, out[t] must equal 2 * in[t - latency] to numerical noise. + double max_err = 0.0; + for (size_t t = 8192; t < static_cast(n); ++t) { + max_err = std::max(max_err, std::abs(out[t] - 2.0 * in[t - latency])); + } + REQUIRE(max_err < 1e-6); +} + +SCENARIO("a chord stays bounded and both voices contribute") { + tap::tools::harmony::harmonizer hz; + hz.prepare(k_sr); + hz.set_dry(1.0); + hz.set_gain(0, 1.0); + hz.set_interval(0, 4.0); + hz.set_gain(1, 1.0); + hz.set_interval(1, 7.0); + + const auto out = run_saw(hz, 220.0, 1.5); + + double peak = 0.0; + double rms = 0.0; + for (size_t t = out.size() / 2; t < out.size(); ++t) { + peak = std::max(peak, std::abs(out[t])); + rms += out[t] * out[t]; + } + rms = std::sqrt(rms / (out.size() / 2.0)); + + REQUIRE(peak < 4.0); // three summed unit-ish voices, sane headroom + REQUIRE(rms > 0.05); // and actually sounding + const size_t tail = 1 << 15; + REQUIRE(band_mag(out, 220.0 * std::exp2(4.0 / 12.0), tail) > 0.01); // the third is present + REQUIRE(band_mag(out, 220.0 * std::exp2(7.0 / 12.0), tail) > 0.01); // the fifth is present +} + +SCENARIO("formant preservation keeps the envelope bump where the source put it") { + // Source: 220 Hz saw with a strong synthetic formant near 1320 Hz (harmonic 6 + // boosted). Shift up a fifth. With formant preservation the output's energy near + // 1320 Hz must beat the formant-off run's; with it off, the bump rides up to ~1980. + auto run = [](bool formant) { + tap::tools::harmony::harmonizer hz; + hz.prepare(k_sr); + hz.set_dry(0.0); + hz.set_formant(formant); + hz.set_gain(0, 1.0); + hz.set_interval(0, 7.0); + + const int n = static_cast(1.5 * k_sr); + std::vector out(static_cast(n)); + for (int t = 0; t < n; ++t) { + double x = 0.0; + for (int h = 1; h <= 20; ++h) { + const double boost = (h == 6) ? 8.0 : 1.0; + x += boost * std::sin(2.0 * k_pi * 220.0 * h * t / k_sr) / h; + } + out[static_cast(t)] = hz.process(x * (2.0 / k_pi)); + } + return out; + }; + + const auto on = run(true); + const auto off = run(false); + const size_t tail = 1 << 15; + + // The shifted harmonic nearest the source bump: 1320 Hz region on the +7 grid. + const double f_bump = 220.0 * std::exp2(7.0 / 12.0) * 4.0; // ≈ 1318.5 Hz + const double f_moved = 220.0 * std::exp2(7.0 / 12.0) * 6.0; // ≈ 1977.8 Hz — the bump if it rode up + + const double on_ratio = band_mag(on, f_bump, tail) / std::max(band_mag(on, f_moved, tail), 1e-12); + const double off_ratio = band_mag(off, f_bump, tail) / std::max(band_mag(off, f_moved, tail), 1e-12); + REQUIRE(on_ratio > 2.0 * off_ratio); // the envelope stayed home only with the flag on +} + +SCENARIO("interval glide walks the pitch instead of jumping it") { + tap::tools::harmony::harmonizer hz; + hz.prepare(k_sr); + hz.set_dry(0.0); + hz.set_gain(0, 1.0); + hz.set_interval(0, 0.0); + hz.set_glide(300.0); + + auto out = run_saw(hz, 220.0, 0.75); + hz.set_interval(0, 12.0); + // Mid-glide (about one time constant in), the pitch must sit strictly between. + auto mid = run_saw(hz, 220.0, 0.35); + const double mid_hz = measure_hz(mid); + REQUIRE(mid_hz > 240.0); + REQUIRE(mid_hz < 425.0); + // And well past the glide it must settle on the octave. + auto end = run_saw(hz, 220.0, 2.5); + REQUIRE(std::abs(cents(measure_hz(end), 440.0)) < 10.0); + (void)out; +} + +SCENARIO("a disabled voice re-enters cleanly and the kernel stays finite") { + tap::tools::harmony::harmonizer hz; + hz.prepare(k_sr); + hz.set_dry(1.0); + hz.set_gain(0, 1.0); + hz.set_interval(0, 3.0); + + auto a = run_saw(hz, 220.0, 0.5); + hz.set_gain(0, 0.0); // off — the engine is skipped + auto b = run_saw(hz, 220.0, 0.5); + hz.set_gain(0, 1.0); // back on — cleared engine, one frame of silence, gain slew + auto c = run_saw(hz, 220.0, 1.0); + + for (const auto* seg : {&a, &b, &c}) { + for (const double y : *seg) { + REQUIRE(std::isfinite(y)); + } + } + // With the voice off, the tail is dry-only: level near the dry saw's. + double rms_b = 0.0; + for (size_t t = b.size() / 2; t < b.size(); ++t) { + rms_b += b[t] * b[t]; + } + rms_b = std::sqrt(rms_b / (b.size() / 2.0)); + REQUIRE(rms_b > 0.05); + // And the re-entered voice is audible again at the end. + const size_t tail = 1 << 15; + REQUIRE(band_mag(c, 220.0 * std::exp2(3.0 / 12.0), tail) > 0.01); +} + +SCENARIO("the harmonizer passes input through before prepare") { + tap::tools::harmony::harmonizer hz; + REQUIRE(hz.process(0.25) == 0.25); + REQUIRE(hz.latency() == 0); +} diff --git a/tools/capi/taptools_capi.cpp b/tools/capi/taptools_capi.cpp index a2a3ba5..a52e7b4 100644 --- a/tools/capi/taptools_capi.cpp +++ b/tools/capi/taptools_capi.cpp @@ -15,6 +15,7 @@ #include #include #include +#include #include #include @@ -757,6 +758,65 @@ int taptools_tune_process(taptools_tune h, const double* in, double* out, int n) }); } +// ---- tap.harmony~ ------------------------------------------------------------------------------ + +using harmony_kernel = tap::tools::harmony::harmonizer; + +taptools_harmonizer taptools_harmonizer_create(void) { + return static_cast(new harmony_kernel()); +} + +void taptools_harmonizer_destroy(taptools_harmonizer h) { + delete static_cast(h); +} + +int taptools_harmonizer_prepare(taptools_harmonizer h, double sr, int fft_size) { + if (fft_size < 64 || (fft_size & (fft_size - 1)) != 0) { + return -1; + } + return with(h, [&](harmony_kernel& k) { k.prepare(sr, static_cast(fft_size)); }); +} + +int taptools_harmonizer_clear(taptools_harmonizer h) { + return with(h, [&](harmony_kernel& k) { k.clear(); }); +} + +int taptools_harmonizer_set_interval(taptools_harmonizer h, int voice, double st) { + return with(h, [&](harmony_kernel& k) { k.set_interval(voice, st); }); +} + +int taptools_harmonizer_set_gain(taptools_harmonizer h, int voice, double gain) { + return with(h, [&](harmony_kernel& k) { k.set_gain(voice, gain); }); +} + +int taptools_harmonizer_set_dry(taptools_harmonizer h, double gain) { + return with(h, [&](harmony_kernel& k) { k.set_dry(gain); }); +} + +int taptools_harmonizer_set_formant(taptools_harmonizer h, int on) { + return with(h, [&](harmony_kernel& k) { k.set_formant(on != 0); }); +} + +int taptools_harmonizer_set_glide(taptools_harmonizer h, double ms) { + return with(h, [&](harmony_kernel& k) { k.set_glide(ms); }); +} + +int taptools_harmonizer_latency(taptools_harmonizer h) { + auto* k = static_cast(h); + return k ? static_cast(k->latency()) : -1; +} + +int taptools_harmonizer_process(taptools_harmonizer h, const double* in, double* out, int n) { + if (!in || !out || n < 0) { + return -1; + } + return with(h, [&](harmony_kernel& k) { + for (int i = 0; i < n; ++i) { + out[i] = k.process(in[i]); + } + }); +} + // ---- pitch detector passthrough ---------------------------------------------------------------- taptools_yin taptools_yin_create(int window, int tau_min, int tau_max) { diff --git a/tools/capi/taptools_capi.h b/tools/capi/taptools_capi.h index ca6be9f..ef012f6 100644 --- a/tools/capi/taptools_capi.h +++ b/tools/capi/taptools_capi.h @@ -252,6 +252,22 @@ TAPTOOLS_API double taptools_tune_target_midi(taptools_tune h); TAPTOOLS_API double taptools_tune_applied_semitones(taptools_tune h); TAPTOOLS_API int taptools_tune_process(taptools_tune h, const double* in, double* out, int n); +// ---- tap.harmony~ (tap::tools::harmony::harmonizer) ---------------------------------------------- + +typedef void* taptools_harmonizer; + +TAPTOOLS_API taptools_harmonizer taptools_harmonizer_create(void); +TAPTOOLS_API void taptools_harmonizer_destroy(taptools_harmonizer h); +TAPTOOLS_API int taptools_harmonizer_prepare(taptools_harmonizer h, double sr, int fft_size); +TAPTOOLS_API int taptools_harmonizer_clear(taptools_harmonizer h); +TAPTOOLS_API int taptools_harmonizer_set_interval(taptools_harmonizer h, int voice, double st); +TAPTOOLS_API int taptools_harmonizer_set_gain(taptools_harmonizer h, int voice, double gain); +TAPTOOLS_API int taptools_harmonizer_set_dry(taptools_harmonizer h, double gain); +TAPTOOLS_API int taptools_harmonizer_set_formant(taptools_harmonizer h, int on); +TAPTOOLS_API int taptools_harmonizer_set_glide(taptools_harmonizer h, double ms); +TAPTOOLS_API int taptools_harmonizer_latency(taptools_harmonizer h); +TAPTOOLS_API int taptools_harmonizer_process(taptools_harmonizer h, const double* in, double* out, int n); + // ---- pitch detector passthrough (tap::dsp::yin, for the notebooks' pitch tracking) --------------- typedef void* taptools_yin; From 47e8cc96b154252f6814c76ebd8425fd898bb534 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 5 Aug 2026 03:00:48 +0000 Subject: [PATCH 06/12] Add the harmonizer recipe: A choir of one, with the Bon Iver patches MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The chapter the audit demanded: tap.harmony~ documented as an instrument (corrector into harmonizer, formant as the point, chord as the performance surface, glide as the inhuman slide), with the honest latency number and the kernel test battery cited for every claim. Two worked examples carry it: "Woods" as the stacked chapel — with the overdub-honesty note that one harmonizer pass is one performance, and takes are the faithful version — and "715 - CRZZKS" as the Messina-school live stack (dry voice equal citizen inside the chord, the octave-down under falsetto, no reverb this once). The vocoder songbook's Hide and Seek section now ranks tap.harmony~ as the right tool, keeping the shifter stack as the manual fallback; SUMMARY and the plan record grow to match. Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01V6CC6kpK5Lx2YkJWuNNQpw --- book/PLAN-recipes.md | 12 +++- book/src/SUMMARY.md | 1 + book/src/recipes/choir-of-one.md | 117 +++++++++++++++++++++++++++++++ book/src/recipes/robot-voice.md | 26 +++---- 4 files changed, 143 insertions(+), 13 deletions(-) create mode 100644 book/src/recipes/choir-of-one.md diff --git a/book/PLAN-recipes.md b/book/PLAN-recipes.md index a44a7cb..b1c19cc 100644 --- a/book/PLAN-recipes.md +++ b/book/PLAN-recipes.md @@ -109,7 +109,17 @@ scale — corrected in `src/pitchaccum.md`): keepable table (factory, open fifth, just major, dark cluster, √2 bell plate), ringing techniques, the eight-second morph gesture. -New recipes now wait on new objects (or on the improvements plan landing — e.g. the vco +**The audit's first shipped object (2026-08-05):** the songbook's "Hide and Seek" finding +("the mechanism is a formant-corrected harmonizer and no object provides it") became +`tap.harmony~` — kernel `taptools/harmonizer.h` on the DspTap pvoc/LPC substrate, seven +oracle-based test scenarios, capi + bridge, wrapper with reference page and help patcher — +and **`recipes/choir-of-one.md`** documents it: the instrument (corrector → harmonizer), +the Bon Iver worked examples ("Woods" as stacked chapel with the overdub-honesty note; +"715 - CRΞΞKS" as the Messina-school live stack), craft notes, and the robot-vs-choir fork +back to the vocoder chapter. A proper object chapter (Part VI territory) and an executed +verification notebook remain future work — the recipe cites the pinned tests meanwhile. + +Other new recipes wait on new objects (or on the improvements plan landing — e.g. the vco performance section would simplify the Moog chapters' vibrato plumbing). ## Notes for drafting diff --git a/book/src/SUMMARY.md b/book/src/SUMMARY.md index 8cfbc19..39d9fc7 100644 --- a/book/src/SUMMARY.md +++ b/book/src/SUMMARY.md @@ -65,6 +65,7 @@ - [Move a knob while it loops](recipes/acid-line.md) - [The ostinato machine](recipes/sequenced-modular.md) - [The robot on the radio](recipes/robot-voice.md) +- [A choir of one](recipes/choir-of-one.md) - [The staircase and the wash](recipes/shimmer.md) - [Sixteenths into a listening filter](recipes/funk-filter.md) - [A field guide to rooms](recipes/rooms.md) diff --git a/book/src/recipes/choir-of-one.md b/book/src/recipes/choir-of-one.md new file mode 100644 index 0000000..c4409dd --- /dev/null +++ b/book/src/recipes/choir-of-one.md @@ -0,0 +1,117 @@ +# A choir of one + +This chapter exists because this book's own audit demanded it. The vocoder +songbook had to label "Hide and Seek" honestly — a harmonizer, not a +vocoder: pitch-shifted copies of the *actual voice*, formants intact, no +carrier anywhere — and the package had no object for that mechanism. Now it +does. `tap.harmony~` holds up to four formant-preserving voices at +intervals you set in semitones, over a dry path the kernel delays into +alignment so chords land as chords. This recipe is how to sing through it, +and its worked examples are the modern masters of the effect: Bon Iver. + +The claims behind the object are pinned in the kernel's test battery +(`tests/harmonizer_test.cpp`): each voice lands its commanded interval +under the DspTap yin oracle, the dry path is sample-aligned with the +voices to 10⁻⁶, a synthetic formant bump stays where the source put it +only when `formant` is on, and interval glides walk the pitch through the +middle instead of jumping. The engine per voice is the DspTap phase +vocoder — the same peak-locked shifting and LPC formant machinery the +[pitch machine chapter](../machine/pitch.md) derives. + +## The instrument + +```text +voice ──▶ tap.tune~ (@speed 0, key of the song) ──▶ tap.harmony~ ──▶ out +``` + +The corrector upstream is optional but it is the modern sound: hard-snap +the lead first and every harmonizer voice inherits the quantized pitch, so +the stack locks like a keyboard instrument instead of drifting like a +choir. Skip it and the stack breathes with your intonation — older, +warmer, more Crosby-Stills than Vernon. + +Three controls do the character work: + +- **`formant` on** is the entire point: an octave-down voice stays *you*, + bigger. Off is the chipmunk-chorus bend — useful, but it stops being a + choir. +- **`chord`** is the performance surface: `chord -12 3 7` sets three + intervals and silences the fourth voice in one message. Wire a Max + chord-to-intervals mapping (played notes minus the sung root) and the + keyboard chooses the harmony live — the rig the credits of the records + below describe. +- **`glide`** at the 10 ms default snaps chord changes; at 300–500 ms the + stack *slides* between chords, which no group of human singers can do + and is worth featuring, not hiding. + +One honest number: latency is one FFT frame (`fftsize`, default 1024 +samples ≈ 21 ms at 48 kHz), dry path included. For live monitoring that +is audible as a slight remove — performers adapt in minutes, but mix the +monitor wet so they hear the instrument, not the delay ghost. + +## "Woods" (2009) — the stacked chapel + +What's documented: Justin Vernon built "Woods" from many overdubbed +a cappella takes, each hard-tuned — a chapel of his own voice, later the +foundation of Kanye West's "Lost in the World." The record's mechanism is +*overdubs*, and the recipe respects that: + +- The live approximation: `tap.tune~ @speed 0` → `tap.harmony~` with + `chord 3 7 12`, `@dry 1`, all through a long dark reverb + ([the wash](shimmer.md) settings work). One pass, four-voice chapel. +- The faithful version: record *takes* — sing each chord tone through the + corrector alone, layer them, and use `tap.harmony~` per take only to + widen (`chord 12` at `@level1 0.4`). Stacked takes decorrelate the way + overdubs do; one harmonizer pass, however good, is one performance. + The difference is the difference between a choir and a string patch. + +## "715 - CRΞΞKS" (2016) — the Messina + +What's documented: the *22, A Million* credits name "the Messina," the +rig Chris Messina and Vernon built to pitch-stack his live voice into +chords (the Prismizer-school effect associated with Francis and the +Lights, and heard on Chance the Rapper's gospel records). "715 - CRΞΞKS" +is that instrument a cappella: every sound is the processed voice. + +```text +voice ─▶ tap.tune~ (@speed 0) ─▶ tap.harmony~ @dry 1 @formant 1 @glide 10 + chord -12 3 7 (verse color) + chord -12 4 7 (the lift) + chord -5 3 10 (the ache) +``` + +- `@dry 1` — the lead lives *inside* the stack, equal citizen, exactly + what makes the sound read as one multiplied person rather than + lead-plus-backers. +- Chords change per phrase, not per note: bind each `chord` list to a key + or a pedal and play the harmony like slow organ stops. +- The low voice carries the weight: `-12` under a falsetto lead is the + record's signature register trick. Keep it at full level; thin the + upper voices (`@level3 0.7`) when the stack gets glassy. +- No reverb, or almost none — the record's intimacy is the dry stack + right against the microphone. Resist the wash this once. + +## The craft notes + +1. **Feed it one voice.** The formant model and the intervals both assume + monophonic input — the kernel's header says so, and a strummed guitar + through a "choir" proves it right within two bars. +2. **Mind the sum.** Dry plus four unity voices is five voices; + `tap.limi~` or a `*~ 0.5` after the object is the standing advice. +3. **Close voicings beat wide ones.** ±12 is the working span; the + engine's contract runs to ±24 and the top octave of that range is a + *sound effect*, not a singer. +4. **The corrector's `speed` is the era dial.** 0 ms is 2016; 40 ms is + 1970s session stack; bypassed is a folk group. + +## When to leave the recipe + +- **You want the robot.** No carrier here, no bands — that's the + [vocoder](robot-voice.md), and the two chapters together are the + voice-processing fork in the road: wear the voice over a synth, or + multiply the voice itself. +- **You want real ensemble.** Overdub real takes; the "Woods" section's + faithful version is the honest ceiling of one person's choir. +- **You want harmony that follows chords you *sing*.** The object holds + intervals; it doesn't do music theory. The keyboard (or your patch's + chord logic) is the brain — which is exactly how the famous rigs work. diff --git a/book/src/recipes/robot-voice.md b/book/src/recipes/robot-voice.md index 8877733..0dec2b2 100644 --- a/book/src/recipes/robot-voice.md +++ b/book/src/recipes/robot-voice.md @@ -105,18 +105,20 @@ What's documented: Imogen Heap sang into a harmonizer (the DigiTech Vocalist lineage), a keyboard choosing the chord — so every sound on the record is her *actual voice*, pitch-shifted into harmony, breath and formants intact. That's why it doesn't sound like a robot; there is no -carrier. Two routes, honestly ranked: - -1. **The closer one — a shifter stack.** Voice into parallel - `tap.shift~` objects at chord intervals, dry voice summed in the - middle. `tap.semitone2ratio` exists for exactly this: `-5`, `+3`, - `+7` → ratios into each shifter's middle inlet. Keep the voicing - close (within ±7 st) — granular shifting moves formants with the - pitch, and wide intervals go chipmunk where the hardware's - formant-corrected voices didn't. Change the interval set per chord - (messages, or a small Max chord-to-ratios mapping) and you are - playing the record's instrument. -2. **The vibe — the choir patch above.** Speak-sing into the choir row's +carrier. Three routes, honestly ranked: + +1. **The right tool — `tap.harmony~`.** This record's mechanism is + exactly what the object does: formant-preserving voices holding a + chord over the aligned dry voice. Its recipe — with the Bon Iver + patches that extend the lineage — is [A choir of one](choir-of-one.md). + (This object exists because this section's first draft had to work + around its absence; the audit worked.) +2. **The manual fallback — a shifter stack.** Voice into parallel + `tap.shift~` objects at chord intervals (`tap.semitone2ratio` feeds + their ratio inlets). Keep the voicing within ±7 st — plain granular + shifting moves formants with the pitch, and wide intervals go + chipmunk where the formant-corrected routes don't. +3. **The vibe — the choir patch above.** Speak-sing into the choir row's settings with an `mc.` carrier holding the chords. It will sound like a vocoder doing Imogen Heap, which is its own valid sound — just don't mistake it for the record's mechanism. From 2ef1e06a124e6a25ed1bacfa8c2f172b4bad63f3 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 5 Aug 2026 10:12:51 +0000 Subject: [PATCH 07/12] Appease clang-format on the harmonizer files MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Formatting only — the style job caught the harmonizer header, test, and capi include block; no behavior change, suite still green. Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01V6CC6kpK5Lx2YkJWuNNQpw --- include/taptools/harmonizer.h | 22 +++++++++++----------- tests/harmonizer_test.cpp | 6 +++--- tools/capi/taptools_capi.cpp | 2 +- 3 files changed, 15 insertions(+), 15 deletions(-) diff --git a/include/taptools/harmonizer.h b/include/taptools/harmonizer.h index 64e38cc..43c0af6 100644 --- a/include/taptools/harmonizer.h +++ b/include/taptools/harmonizer.h @@ -46,13 +46,13 @@ namespace tap::tools { namespace harmony { constexpr int k_max_voices = 4; - constexpr double k_max_interval_st = 24.0; // == the pvoc ratio clamp [1/4, 4] - constexpr double k_max_gain = 2.0; // linear; wrappers speak dB - constexpr double k_default_glide_ms = 10.0; // click-free, not yet audible + constexpr double k_max_interval_st = 24.0; // == the pvoc ratio clamp [1/4, 4] + constexpr double k_max_gain = 2.0; // linear; wrappers speak dB + constexpr double k_default_glide_ms = 10.0; // click-free, not yet audible constexpr double k_max_glide_ms = 2000.0; constexpr double k_gain_slew_ms = 10.0; - constexpr double k_gain_epsilon = 1e-4; // below this a voice is "off" - constexpr size_t k_default_fft = 1024; // the pvoc desktop operating point + constexpr double k_gain_epsilon = 1e-4; // below this a voice is "off" + constexpr size_t k_default_fft = 1024; // the pvoc desktop operating point /// Formant-preserving multi-voice harmonizer. House shape: prepare(sr) buys all /// geometry, process(in) is per-sample and allocation-free, every setter is safe @@ -119,7 +119,7 @@ namespace tap::tools { } /// Dry-path gain (latency-aligned inside the kernel), linear [0, 2], default 1. - void set_dry(double gain) { m_target_dry = std::clamp(gain, 0.0, k_max_gain); } + void set_dry(double gain) { m_target_dry = std::clamp(gain, 0.0, k_max_gain); } double dry() const { return m_target_dry; } /// LPC formant preservation on every voice (see tap::dsp::basic_pvoc). On by @@ -163,10 +163,10 @@ namespace tap::tools { } // dry path, delayed to the voices' emission time - const double dry = m_dry_ring[m_dry_write]; - m_dry_ring[m_dry_write] = in; - m_dry_write = (m_dry_write + 1) % m_dry_ring.size(); - m_current_dry += m_gain_coeff * (m_target_dry - m_current_dry); + const double dry = m_dry_ring[m_dry_write]; + m_dry_ring[m_dry_write] = in; + m_dry_write = (m_dry_write + 1) % m_dry_ring.size(); + m_current_dry += m_gain_coeff * (m_target_dry - m_current_dry); double out = m_current_dry * dry; @@ -184,7 +184,7 @@ namespace tap::tools { m_active[i] = true; } - m_current_st[i] += m_glide_coeff * (m_target_st[i] - m_current_st[i]); + m_current_st[i] += m_glide_coeff * (m_target_st[i] - m_current_st[i]); m_current_gain[i] += m_gain_coeff * (m_target_gain[i] - m_current_gain[i]); const double ratio = std::exp2(m_current_st[i] / 12.0); diff --git a/tests/harmonizer_test.cpp b/tests/harmonizer_test.cpp index fba6d9a..31d3e78 100644 --- a/tests/harmonizer_test.cpp +++ b/tests/harmonizer_test.cpp @@ -139,8 +139,8 @@ SCENARIO("a chord stays bounded and both voices contribute") { } rms = std::sqrt(rms / (out.size() / 2.0)); - REQUIRE(peak < 4.0); // three summed unit-ish voices, sane headroom - REQUIRE(rms > 0.05); // and actually sounding + REQUIRE(peak < 4.0); // three summed unit-ish voices, sane headroom + REQUIRE(rms > 0.05); // and actually sounding const size_t tail = 1 << 15; REQUIRE(band_mag(out, 220.0 * std::exp2(4.0 / 12.0), tail) > 0.01); // the third is present REQUIRE(band_mag(out, 220.0 * std::exp2(7.0 / 12.0), tail) > 0.01); // the fifth is present @@ -195,7 +195,7 @@ SCENARIO("interval glide walks the pitch instead of jumping it") { auto out = run_saw(hz, 220.0, 0.75); hz.set_interval(0, 12.0); // Mid-glide (about one time constant in), the pitch must sit strictly between. - auto mid = run_saw(hz, 220.0, 0.35); + auto mid = run_saw(hz, 220.0, 0.35); const double mid_hz = measure_hz(mid); REQUIRE(mid_hz > 240.0); REQUIRE(mid_hz < 425.0); diff --git a/tools/capi/taptools_capi.cpp b/tools/capi/taptools_capi.cpp index a52e7b4..3dece29 100644 --- a/tools/capi/taptools_capi.cpp +++ b/tools/capi/taptools_capi.cpp @@ -9,13 +9,13 @@ #include #include #include +#include #include #include #include #include #include #include -#include #include #include From f1e0eb5e5bded8b5255a00e8522ad2b09a012911 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 5 Aug 2026 10:17:43 +0000 Subject: [PATCH 08/12] Add the executed harmonizer verification notebook notebooks/harmonizer.ipynb drives the shipping kernel through the capi bridge, house-style: solo voices across two octaves of voicings land within 0.04 cents of their equal-tempered targets under the DspTap yin oracle; the dry path aligns with a unity voice to a 3.7e-8 residual (why chords land as chords, not flams); the formant section shifts a synthetic 960 Hz-bump voice up a fifth and quantifies the preservation honestly with a band centroid (1058 -> 1154 Hz with the flag on, 1439 riding the full ratio with it off); and the last section plots the "715"-school chord spectrum and the 300 ms glide walking unison to octave. The book's choir-of-one recipe now cites the notebook's numbers instead of leaning on the tests alone, and the plan record marks the notebook shipped. Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01V6CC6kpK5Lx2YkJWuNNQpw --- book/PLAN-recipes.md | 6 +- book/src/recipes/choir-of-one.md | 20 +- notebooks/harmonizer.ipynb | 390 +++++++++++++++++++++++++++++++ 3 files changed, 406 insertions(+), 10 deletions(-) create mode 100644 notebooks/harmonizer.ipynb diff --git a/book/PLAN-recipes.md b/book/PLAN-recipes.md index b1c19cc..eb7bd6c 100644 --- a/book/PLAN-recipes.md +++ b/book/PLAN-recipes.md @@ -116,8 +116,10 @@ oracle-based test scenarios, capi + bridge, wrapper with reference page and help and **`recipes/choir-of-one.md`** documents it: the instrument (corrector → harmonizer), the Bon Iver worked examples ("Woods" as stacked chapel with the overdub-honesty note; "715 - CRΞΞKS" as the Messina-school live stack), craft notes, and the robot-vs-choir fork -back to the vocoder chapter. A proper object chapter (Part VI territory) and an executed -verification notebook remain future work — the recipe cites the pinned tests meanwhile. +back to the vocoder chapter. The executed verification notebook shipped the same day +(`notebooks/harmonizer.ipynb` — 0.04-cent interval accuracy, 3.7e-8 dry-alignment +residual, the formant-centroid measurement — cited by the recipe). A proper object +chapter (Part VI territory) remains future work. Other new recipes wait on new objects (or on the improvements plan landing — e.g. the vco performance section would simplify the Moog chapters' vibrato plumbing). diff --git a/book/src/recipes/choir-of-one.md b/book/src/recipes/choir-of-one.md index c4409dd..57a97b2 100644 --- a/book/src/recipes/choir-of-one.md +++ b/book/src/recipes/choir-of-one.md @@ -9,14 +9,18 @@ intervals you set in semitones, over a dry path the kernel delays into alignment so chords land as chords. This recipe is how to sing through it, and its worked examples are the modern masters of the effect: Bon Iver. -The claims behind the object are pinned in the kernel's test battery -(`tests/harmonizer_test.cpp`): each voice lands its commanded interval -under the DspTap yin oracle, the dry path is sample-aligned with the -voices to 10⁻⁶, a synthetic formant bump stays where the source put it -only when `formant` is on, and interval glides walk the pitch through the -middle instead of jumping. The engine per voice is the DspTap phase -vocoder — the same peak-locked shifting and LPC formant machinery the -[pitch machine chapter](../machine/pitch.md) derives. +The claims behind the object are measured in the executed +[verification notebook](https://github.com/tap/TapTools/blob/main/notebooks/harmonizer.ipynb) +and pinned in the kernel's test battery (`tests/harmonizer_test.cpp`): +across two octaves of voicings every interval lands within **0.04 cents** +of its equal-tempered target under the DspTap yin oracle; the dry path is +sample-aligned with the voices to a 3.7×10⁻⁸ residual — why chords land +as chords, not flams; a synthetic formant bump stays near home only when +`formant` is on (band centroid 1058 → 1154 Hz on a +7 shift, versus 1439 +riding the full ratio with it off); and interval glides walk the pitch +through the middle instead of jumping. The engine per voice is the DspTap +phase vocoder — the same peak-locked shifting and LPC formant machinery +the [pitch machine chapter](../machine/pitch.md) derives. ## The instrument diff --git a/notebooks/harmonizer.ipynb b/notebooks/harmonizer.ipynb new file mode 100644 index 0000000..0b81bb1 --- /dev/null +++ b/notebooks/harmonizer.ipynb @@ -0,0 +1,390 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "id": "f5f79df2", + "metadata": {}, + "source": [ + "# tap.harmony~ — the harmonizer, measured\n", + "\n", + "The multi-voice harmonizer behind `tap.harmony~` (`taptools/harmonizer.h`): up to four\n", + "formant-preserving phase-vocoder voices at fractional-semitone intervals, summed with a dry\n", + "path the kernel delays into alignment. Every measurement below drives the **shipping C++**\n", + "through `tools/capi` via ctypes — the same code the Max external compiles — and uses the\n", + "shared DspTap YIN detector as the pitch oracle, the house pattern.\n", + "\n", + "Sections: **1** every interval lands · **2** the dry path is sample-aligned ·\n", + "**3** formants stay home · **4** a chord, and the glide." + ] + }, + { + "cell_type": "code", + "execution_count": 1, + "id": "15e55c68", + "metadata": { + "execution": { + "iopub.execute_input": "2026-08-05T10:17:11.169185Z", + "iopub.status.busy": "2026-08-05T10:17:11.168973Z", + "iopub.status.idle": "2026-08-05T10:17:11.828675Z", + "shell.execute_reply": "2026-08-05T10:17:11.827248Z" + } + }, + "outputs": [], + "source": [ + "import numpy as np\n", + "import matplotlib.pyplot as plt\n", + "\n", + "import taptools_py as tap\n", + "\n", + "plt.rcParams.update({\n", + " \"figure.dpi\": 96, \"figure.figsize\": (9, 3.2),\n", + " \"axes.grid\": True, \"grid.alpha\": 0.3,\n", + "})\n", + "C = tap.PALETTE\n", + "\n", + "sr = 48000.0\n", + "HOP = 256\n", + "\n", + "def saw(freq_or_track, seconds=None, harmonics=12):\n", + " \"\"\"Band-limited saw; freq may be a scalar or a per-sample frequency track.\"\"\"\n", + " if np.isscalar(freq_or_track):\n", + " f = np.full(int(seconds * sr), float(freq_or_track))\n", + " else:\n", + " f = np.asarray(freq_or_track)\n", + " phase = np.cumsum(f) / sr\n", + " x = sum(np.sin(2 * np.pi * h * phase) / h for h in range(1, harmonics + 1))\n", + " return x / np.abs(x).max()\n", + "\n", + "def track_hz(x):\n", + " \"\"\"Pitch track (Hz, NaN where unvoiced) via the shared DspTap detector.\"\"\"\n", + " periods = tap.Yin().track(x, hop=HOP)\n", + " hz = np.where(periods > 0, sr / np.maximum(periods, 1e-9), np.nan)\n", + " t = (np.arange(len(hz)) * HOP + tap.Yin().frame_size) / sr\n", + " return t, hz\n", + "\n", + "def cents(f, ref):\n", + " return 1200 * np.log2(f / ref)\n", + "\n", + "def spectrum_db(x, tail=1 << 15):\n", + " \"\"\"Hann-windowed magnitude spectrum of the signal's tail, in dB re max.\"\"\"\n", + " seg = x[-tail:] * np.hanning(tail)\n", + " mag = np.abs(np.fft.rfft(seg))\n", + " f = np.fft.rfftfreq(tail, 1 / sr)\n", + " db = 20 * np.log10(np.maximum(mag, 1e-12))\n", + " return f, db - db.max()" + ] + }, + { + "cell_type": "markdown", + "id": "02e93e42", + "metadata": {}, + "source": [ + "## 1 · Every interval lands\n", + "\n", + "One voice solo (`dry 0`), a 220 Hz sawtooth in, the commanded interval swept across two\n", + "octaves of useful voicings. The YIN oracle measures the output; the bars are the error in\n", + "cents against the exact equal-tempered target. The kernel's Catch battery pins ±10 cents;\n", + "the measured errors sit far inside it." + ] + }, + { + "cell_type": "code", + "execution_count": 2, + "id": "3d0f9137", + "metadata": { + "execution": { + "iopub.execute_input": "2026-08-05T10:17:11.831557Z", + "iopub.status.busy": "2026-08-05T10:17:11.831154Z", + "iopub.status.idle": "2026-08-05T10:17:13.821274Z", + "shell.execute_reply": "2026-08-05T10:17:13.820085Z" + } + }, + "outputs": [ + { + "data": { + "image/png": "iVBORw0KGgoAAAANSUhEUgAAAukAAAE+CAYAAAAwF44BAAAAOnRFWHRTb2Z0d2FyZQBNYXRwbG90bGliIHZlcnNpb24zLjExLjEsIGh0dHBzOi8vbWF0cGxvdGxpYi5vcmcvctoD+AAAAAlwSFlzAAAOxAAADsQBlSsOGwAARFxJREFUeJzt3X1cVGX+//E3IgqoiKKSeH8DmqiokKRleV/eJWqJZpppllbr1tZmu/aotd3Kbdt2q59plrZpq6iZumrmfYp35X3q17s0zZskBFFRkLvr94fLrOOADCPOHJzX8/Hokec61znX5/rMOcOHw5kzPsYYIwAAAACWUcbTAQAAAACwR5EOAAAAWAxFOgAAAGAxFOkAAACAxVCkAwAAABZDkQ4AAABYDEU6AAAAYDEU6QAAAIDFUKQD0MWLF5WQkKAzZ854OhQHZ86cUUJCgi5evHhbjudut/v8rOqnn37S119/rY0bN+r8+fM33S8nJ0eJiYlatGiRfvzxR6diSElJUUJCgo4fP17g+kWLFmnjxo1O7QvArUeRDkCnTp3S4MGDtWvXLk+H4mDXrl0aPHiwTp06ZenxTp06pYSEBKWnp9+iyEqGu/Pp7datW6e7775bLVq00P/7f/9Pzz//vOrWrav333/fpX6StH//ft15550aNWqUPv30U7Vq1UpPPvmk8vLybhjL4cOHNXjwYCUmJha4/umnn9Y//vEP1ycLoESV9XQAAHAjNWvWVHx8vIKCgiw93tatWzV48GAdPnxYjRs3vkXRobRZvHix7rjjDi1dulQhISGSpI8++kjPPvus6tWrp7i4uGL1y83N1YABA9SwYUMtXbpUZcuW1e7du9W2bVs1a9ZMv/vd7zwxTQC3AEU6UMoZY7R9+3adPn1atWvXVosWLeTn52fXJz09XVu2bFF6erruvPNONWnSxKl9u7Ldr7/+qjVr1qhTp04KDQ21W3f06FF9//336t27typWrChJSk1N1ffff6+srCy1atVKdevWtdsmNDRUcXFxqlSpkl37lStXtHXrVqWkpKh58+Zq1KiRQyyZmZn67rvvlJqaqkaNGqlly5ZFxn/9eD///LM2bdqkvn37ysfHR+vWrZOPj486dOiggIAASdLx48e1YcMGSdLSpUtt846Li5O/v79TsVw/TmJionx8fNSyZUun8pmTk6NvvvlGkuTj46PQ0FBFRkaqevXqRc75emlpacXalzOvxY36HDp0SDt27NCgQYPsttm1a5d+/vlnPfTQQzfMUdeuXUss5uTkZK1evfqG+e7Tp48qVKjgTCr1yCOP6K677lKZMv/7w/Uzzzyj8ePH68svv7QV3872++abb7R//35NnTpVZcte/REeFRWlfv366f333y/RIn3RokXKyMhwaC9fvrz69etX6HbZ2dnatm2bkpOT1bBhQ0VGRsrHx0eSc8fWlStXtGDBArVr10716tWTdPW9aMmSJapfv77uvvtuW9+lS5fqjjvuUHR0dInMGbAUA6DUOn36tImMjDR16tQxffv2NW3btjXNmzc327dvt/WZO3euCQ4ONs2aNTNdu3Y1gYGBpl+/fiY9Pd3WZ//+/UaSWbZsWbG2K8jFixdNYGCgee211xzWDR061NSpU8fk5uYaY4x5//33TUBAgImOjjb333+/KV++vBk9erTJycmxbbNs2TIjyezfv9/WNm/ePFO9enXToEED06tXLxMeHm4GDRpk8vLybH3mz59vqlWrZpo0aWJ69uxpQkJCTI8ePczFixdvGP/1482ePdtIMmvXrjXR0dGmR48eJiwszNSrV8+cOHHCGGNMYmKiuffee40k06tXLxMfH2/i4+NNWlqa07Hkj7N8+XITFRVl+vTpY1599VWn83ns2DHbuAMHDjTt27c3/v7+5s9//vMN51cQZ/fl7GtRVJ9//OMfpqAfRy+++KKpVatWkTkqyZgvX75sgoODzSuvvOKwXXx8vGnUqJHd3FyRk5NjgoKCTL9+/Yrd76WXXjJly5Y1WVlZdn0nTZpkJJkjR44Uur/NmzcbSWbmzJkFrg8NDTUDBgywLT/99NO2nOb/V6lSJRMSElLoGHv27DF169Y1ERERpm/fvqZVq1YmNjbW/PTTT8YY51+n0NBQu9dgwYIFRpJp1aqVre3ixYumbNmyZvLkyYXGA5RmFOlAKfbMM8+YZs2a2f3APnz4sNm0aZMxxph9+/YZPz8/89vf/ta2/ocffjCVKlUyTz31lK3t+iLd2e0KM2TIENOwYUO7tvT0dFOxYkXbD96VK1caSea9996z9Vm9erUpU6aMeeutt2xt1xeVW7ZsMb6+vuall16yFfvGGJOQkGBb3rZtmylbtqz54x//aCuokpKSTMOGDc3TTz99w9gLK9Ifeughc/bsWWOMMampqaZmzZpmzJgxtu3yi4jDhw/b7c/ZWPLH6dmzp0lOTi52PguyevVq4+PjYzseCpqfswralzOvhTN9ilukF5Sjkoz5ueeeMzVr1jTZ2dm29SkpKaZ8+fLm7bffLnLconzxxRcOx76z/fr3729q167t0Hfx4sVGklm5cmWh+8sv0p999lkze/Zsh/8qV65sV6Rf75NPPjGSzMsvv1xon549e5pu3brZte3YscPs3bu30G0Kep3i4+NNbGysbXns2LGmYcOGxsfHx6SkpBhjjPn666+NJHPgwIFC9w2UZhTpQCnWr18/ExsbW+iVveeff95UqFDBXLhwwaG9XLlytqvi1xfpzm5XmG+++cZIMhs2bLC1zZw500gy+/btM8YYExcXZ+rXr29XKOW3h4WF2ZavLyrj4+NNrVq1HK4kXmvIkCGmVq1adkWWMcZ88MEHpnz58iYzM7PQbQsr0v/973/b9XvmmWdMeHi4bbmwIt3ZWPLHmT59ukNMzuQz35EjR8yKFStMQkKCmT17tgkKCjITJ04sdH43UtS+nHktnOlT3CK9oByVZMx79uwxksyiRYtsbf/85z+Nn5+fOXPmTKHbOePkyZOmWrVqpmHDhjc8jwrr1717dxMREeHQf/Xq1UaSWbBgQaH7zC/S7777bocr5PHx8cbf37/QIn3Dhg2mXLlypkePHg7n7LVat25tBg4cWOj6fEW9Th9//LHx9fU158+fN8YY07x5c/Pee++ZKlWqmPnz5xtjrv5V4dr3CuB2wz3pQCn26KOPauDAgWrdurUeeeQRde3a1e6+1j179ig8PNzhfu7o6GhlZWXpwIEDBd7L6ex227Zts3v8W4MGDRQbG6uuXbuqZs2amjlzpu655x5J0syZMxUdHa1mzZrZxmjVqpXdPbj5YyxcuFApKSm2D9Bda/v27YqOjna47/5aW7duVY0aNfTll1/atZ8+fVpXrlzRkSNHbHE4q1WrVnbLtWvXduoJKcWNpXXr1g77cCaf6enpGjhwoNavX6/Y2FiFhISoTJkyysnJKfajNZ3dlzOvhTN9iqugHJVkzM2bN1e7du00bdo02/3w06dP10MPPeRwn3pxXLx4Ub1791ZmZqaWL19e6H3tN+pXrlw5ZWdnO2yT31a+fPki43j22Wf12GOPObTfcccdBfY/ceKEBgwYoAYNGmj27NkO5+y1hgwZopdeekmnT59WXFycunXrZvf5C2dfp06dOik3N1eJiYlq27at9u3bpy5dumj9+vVau3at+vfvr7Vr16pTp05FzhcorSjSgVLs4Ycf1pYtW/T5559r5syZevXVV9W4cWPNmTNHbdq0UXZ2tu3DjdcKDAyUJGVlZRW4X2e32717t1auXGlbf//99ys2Nla+vr569NFHNX36dH3wwQdKTU3V6tWr9fe//73YY1wvKyurwO2ulZmZqaysLC1cuNBhXXx8vO3DnMVx/dNe/Pz8dOXKlSK3K24sBf1i4kw+X3/9de3YsUOHDx9WzZo1be3BwcEyxhQZ57Wc3Zczr4UzffKLPmOM7QOG+dsWpKAclWTM0tXHET755JM6c+aMTpw4oR9++EHvvPNOkdsVJisrS/369dP+/fu1dOlStWnTxqV+tWrV0tq1ax22S0pKkiSFhYW5HGNBMjIyFBcXp8zMTP3nP/9R5cqVb9j/xRdfVFRUlGbNmqUPP/xQL730ktq0aaP58+erfv36Tr9O4eHhql27ttasWaNLly6pWrVqatGihTp37qwpU6YoLS1NO3fu1JgxY0p0voCVUKQDpVzbtm3Vtm1bSdLBgwfVs2dPPf/881q/fr3q1aunlStXOhQ/+Ve/69evX+A+nd1u5MiRGjlyZIH7GDp0qP7+979r6dKl+umnn+Tj46PBgwfbjXHkyBGH7X788UcFBgYW+lSORo0a6eDBg4Vk46qGDRsqOztbCQkJN+xXkq7N083EUth+isrnli1bdP/999sVPqdPn77hF+IUxtl9OfNaONOnRo0akq5+2U61atVs7UePHi2wf0E5KsmYJWngwIF6/vnn9a9//Us//fST6tevr27duhW5XUHy8vI0dOhQffvtt/ryyy/VpUsXl/vFxMTo448/1uHDhxUeHm5r37FjhypUqKCmTZu6FGNhRowYoV27dmnJkiWKiIhwapuuXbuqa9eukqTvv/9eDz74oF577TXNmDGjWMdpp06dtHbtWl2+fFkdO3aUj4+POnfurLFjx2ru3LnKy8tT586dS2aigAXxZUZAKXb9Nwc2adJE0dHRunTpkiSpf//+OnPmjN1V3MzMTE2bNk3t27e3+0F5LVe3u1ZUVJRatmypmTNnaubMmXrggQdsxVj+GN9//7127Nhha0tNTVVCQoLi4uJsj5e7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QkKUkpJy239xk7PIiSNy4oicOCInjshJwciLI3LiyFtyYoxRZmamgoODVaZM4XeecyVdUpkyZVS1alVPh+FWAQEBt/UJ4Apy4oicOCInjsiJI3JSMPLiiJw48oac3OgKej4+OAoAAABYDEU6AAAAYDEU6V6mbNmyev3111W2LHc65SMnjsiJI3LiiJw4IicFIy+OyIkjcmKPD44CAAAAFsOVdAAAAMBiKNIBAAAAi6FIBwAAACyGO/Nvc3v37tXevXttywMGDJCfn59dn9TUVG3dulX+/v6Kjo5WxYoV3R2mR23YsEEnT550aL/rrrvUqFEjD0TkeefPn9eyZcvs2ipVqqRevXp5KCLrOHLkiP7v//5PYWFhio6O9nQ4HpOTk6MdO3bo7Nmzat68uerWrevpkCwjMzNTixYtUv369RUbG+vpcDzm5MmT2rBhg0N79erV1aVLFw9E5BmrVq3S2bNnJUnVqlVT165dHfqkpaVpw4YNKleunDp06HDbPyN869atOnLkiCTJz89PAwYMcOiTlJSk7du3KygoSG3btlW5cuXcHabHUaTf5g4cOKCFCxcqJSVFq1at0rlz5xQcHGxbP378eM2YMUORkZE6e/asjh8/rjlz5qhz586eC9rNvvvuO23dutW2fO7cOa1YsUIrV6702iL9xIkTGjx4sOLj421td9xxh1cX6enp6Ro6dKgOHDigiIgI7dixQ2FhYVq+fLndOeUNvv/+e40cOVJBQUEKCgpSYmKinnvuOU2cONHToVnCH/7wB02aNEmPPvqoVxfpp06d0sKFC+3ali1bpn79+nlVkb5u3TodPnxYe/fuVcWKFR2K9MTERD300EOKjIxUenq6UlNTtXr1aoWHh3so4ltv586dWrNmjU6ePKldu3bZFenGGI0aNUorVqxQixYtdOzYMV24cEFLlixRVFSUB6P2AAOvsHnzZiPJnDt3zq79s88+M5mZmbblsWPHmiZNmrg5Omt5++23TaNGjUxeXp6nQ/GYPXv2GN4e7J09e9asXLnStpyRkWEaN25s/vznP3swKs/YsGGDOXHihG05//1l//79HozKGtatW2datWpl+vfvbx5//HFPh2Mpx48fN2XKlDEbN270dCge8frrr5vY2Fi7try8PNO4cWMzbtw4W9vDDz9sHnzwQXeH5xHz5s0zFSpUsGvLzc0106ZNMzk5OcaYqzkaMGCA6dKliydC9CjuSfdyw4cPV/ny5W3LUVFRtj/LeSNjjD755BM99dRT8vHx8XQ4Hrdq1SotW7ZMJ06c8HQoHhcSEmJ3Bczf31+1atXSpUuXPBiVZ9xzzz2qXbu2bblx48aS5JW5uFZ6erqefPJJffrppw63FUKaOnWqIiMj1b59e0+HYhl79+7Vjz/+qDFjxtjaRo8erRUrVnjt+VSmTBmNGDFCvr6+kiQfHx+1bNnSK2sTbneBTXZ2tqZOnar+/ft7OhSPWb58uU6ePKknnnjC06F4VHBwsOLj4/Xpp5/q119/1ebNm/Xcc8/pb3/7m6dD87hVq1bpl19+0ebNm5WSkqLnnnvO0yF5REZGhhYtWqSLFy9qxowZGjFihFffoy9JL774oh5++GGvz0NBcnJyNH36dL366queDsVSjh49Kl9fX7vPdDRo0EB5eXk6fvy4mjVr5sHorOHChQuaMWOGhg0b5ulQ3I4i/TZx5swZffvtt7bl3r17F+sDoLm5uRo6dKhyc3P13nvv3YIIPS+/qMjXoUMH1apVy67PlClTNGDAAFWvXt3d4XnMV199paysLElSy5Yt1axZM9WuXVsJCQm2Pjt27NA999yjjh07esV96atXr1ZycrIkqV69emrXrp1t3bp167Rv3z7t2bNHLVu29Nq/uGRkZGjhwoW6ePGiTpw4oc6dOysvL09lynjnH2iXL1+uxMRE7dy509OhWNLChQt14cIFPfbYY54OxVJycnLk5+dn9z6S/9ftnJwcT4VlGZcvX1ZcXJzCw8P1xz/+0dPhuB1F+m0iKSnJ7gM6nTp1crpIz8rK0qBBg3TmzBmtWrXqtn26S35Rka9x48Z2RfqpU6e0ZMkSrV692gPRec7SpUttf1YtX758gVdu2rRpozZt2ui7777ziiI9MTFRBw4ckCS1b9/erkj/85//LOnqrVFxcXH6zW9+o/nz53skTk+qWrWq7Re5M2fO6M4771TTpk01ePBgD0fmGb/5zW/Uu3dvLViwQJL0888/y8/PT3PnztXAgQM9HJ3nTZkyRYMHD1ZQUJCnQ7GU0NBQZWZm6vz586pcubKkq+dT/jpvduHCBfXu3VvBwcGaN2+eypb1vpLV+2Z8m4qKirK78umsjIwM9evXT1lZWVqxYsVtW6BL9kVFQT755BNFRETo/vvvd2NUnjdt2jSHtqSkJLsfEOnp6Tpy5Igef/xxd4bmMX/6058c2n799VfVqFHDtuzj46MGDRpoz549bozMGq4/PqpXr66goCClpaV5LigP69ixo06fPm27EHDq1CmVKVNGixYt8voi/ccff9SaNWvsnqKFq/Ife7x06VI9+uijkqQlS5aoSZMmXl2kp6am6oEHHlDDhg31xRdfeO1nPCjSb3OnTp1SYmKifvzxR0lXb20IDAxUr169bM+93rt3r9555x0tWbLEtt3DDz/sVb+15ubm6tNPP9Xvf/97T4diCdOmTdN3332n7t27Ky8vT5999plCQkI0ZMgQT4fmMevXr9ekSZPUu3dvVa1aVdu2bdOnn36quXPnejo0t3v55ZdVtmxZ3X333crOzta8efMkyas/zzJ16lS75UGDBsnf31//+te/PBOQhUyZMkXR0dFee6/+tm3b9OOPP2rv3r1KSUlRQkKCKlSooD59+iggIECvvfaannvuOZ0+fVrp6emaOHGiZs2a5emwb6nDhw9r+/bt+u6775STk2O7gPbwww8rNzdXHTt21KVLl/T888/b/lJZrlw5r3uP8THGGE8HgVtn27Ztevfddx3a33vvPYWFhWnYsGG2+5Gv9fnnn9s99eV2d+DAAU2YMEEfffSRqlSp4ulwLGHlypVasmSJcnJyFBUVpWHDhsnf39/TYXnUjh07NGfOHJ09e1Z169bVoEGD1KRJE0+H5XbGGM2dO1fffvutypQpo8jISA0ZMsT253pIH3zwgfz8/Oye2uGtnnvuOT3wwAPq06ePp0PxiGnTpmnlypV2bdWrV9eHH35oW16wYIGWLl0qPz8/DR48WPfdd5+7w3SrFStWaPr06Q7tn3/+ubKysjRq1CiHdRUqVCjwL7+3M4p0AAAAwGK882P4AAAAgIVRpAMAAAAWQ5EOAAAAWAxFOgAAAGAxFOkAAACAxVCkAwAAABZDkQ4AAABYDEU6AFjAmjVr9PDDD3tseyvKzc1VTEyMjh8/fsN+CQkJeuutt9wUVemSkZGh7t276/z5854OBUAxUaQDgAWkpqZq7969t2R7Z4tdqzHGaPv27crIyCi0z5UrV/Tyyy+rb9++bozsf6ye24CAADVr1kx//etfPR0KgGKiSAeA25yvr6+mTJmi0NBQp/pnZWUpJiZGJ0+evMWR3bz58+erVq1aioyM9Mj41+fWirkbMWKEPv74Y125csXToQAoBop0APACMTEx8vf3d6pvXl6etm/frszMzFsc1c1LSEjQQw895NEYrs2tFXPXsmVLVapUSStWrPB0KACKgSIdgOVkZGTo7bffVq9evRQXF6c1a9bY1p07d06///3v1blzZw0cOFBLly612y4mJkZff/21nnjiCd133316+eWXlZmZqalTp6pr167q1auXvv3225vaRpI6deqkmJgYtW/fXsOHD9eBAwcc9pmYmKiRI0eqY8eOeuGFF+zuC05KStLo0aPVuXNn/fa3v9W5c+fs9p+Zmam33npLPXr0UJ8+ffTZZ5/ZrS9q+2tdf0tGUfH169fP9v+YmBi9//77RcaUv89169ZpxIgRat++vcaMGaMPPvjALpY1a9aoe/fuysvLKzKPztiwYYNiYmLs2qZNm6ZevXqpa9eueuedd5STk+NUXl05Fq7PbWG5c+a4vdHxUtTxcKM5S9Jdd92lxMTEYuUWgIcZALCQ3Nxc065dO3PvvfeaRYsWmUWLFplu3bqZM2fOmKysLNOsWTPTp08fs3LlSjN58mRTqVIlM3v2bGOMMRcvXjSSTGRkpPnqq6/MkiVLTO3atc2dd95pRo0aZdauXWv+/Oc/m0qVKpmUlBSXtzHGmJ07d5qtW7eaDRs2mNdff90EBwcXuM958+aZlStXmjZt2phRo0YZY4zJysoyERERZuDAgWb16tXmvffeM0FBQaZJkybGGGPy8vLMvffeax588EHzzTffmIULF5omTZqYd955x6ntr5ednW0kmf379zsV39atW40ks2DBArN161Zz4sSJImPK32d4eLhJSEgwW7duNZ9//rmpX7++ycvLs8XyyCOPmGeeecapPF4f9/XOnz9vJJm9e/fa2hYuXGiqVatm5syZY9auXWv+8Ic/mIkTJzqVV1eOhetjLCh3xTluC3o9ior7RnPON3bsWDNw4MAC8wjAmijSAVjKf/7zH1OlShVz/vx5W1tubq7Jzs42X375pQkJCTGXL1+2rXvzzTdNixYtjDH/K3ZWrVplW//qq6+a8PBwu0KxZs2aZsWKFS5vU5AHH3zQTJ061W6fK1eutK2fN2+eiYiIsP27Zs2a5sqVK7b1v/3tb21F9pIlS0yNGjVMZmambf3atWtNaGioU9tfr7AivbD4MjIyjCRz+PBh2/qiYsrf58KFC23rL1++bCpXrmzWrFljjDEmNTXVlC9f3mzbts2pPBZVpP/6669Gkjl06JCt7aOPPjL33nuv3WuXH7OzcyjOsXB9jAXlztnjtrDXo6i4bzTnfL///e9N3759C8wjAGsq664r9gDgjH379ql58+YKCgqytZUpU0ZlypTRoUOHFBkZqYCAANu6mJgYvfHGG3b7aNSoke3flStXVsOGDeXj42NrCwoKcngkXXG3+frrrzVjxgydPHlSmZmZOn78uKKjo+322bhxY9u/g4ODbdsfPnxYLVq0ULly5Wzro6Oj9c0339hycPnyZd1zzz229dnZ2UpKStLFixeL3N5ZhcVXkKJiys9V8+bNbesDAgI0aNAgffbZZ+rUqZNmzZqlJk2a2OXJmTwWpmrVqvL19VVqaqqtbdiwYdq0aZNatmypdu3aqUuXLrZHUzo7B1eOnxtx9rgt7PUoKu4bzTlfamqqqlev7nTMADyPIh2ApVSvXl1JSUkFrgsJCdHZs2ft2s6ePauQkBB3hGazYcMGDR48WO+8846aNWumgIAAjR8/3ukPC1atWlUpKSl2bdfOq2rVqqpdu7amTJnisG1AQECR29+sawtSZ2PKn7uvr6/duieeeEKdO3fWpEmT9Nlnn2nEiBG2dTebR19fX0VFRWnfvn2KjY2VJFWoUEEzZ85Udna2du7cqQkTJmjRokWaNWuW03O4GQXl7maP26LiLlu2bKFzzvfDDz/Y5R6A9fHBUQCW8uCDD+qXX37R5MmTbW1z5sxRcnKyunXrpiNHjmjBggWSpAsXLuif//yn+vTp49YYDxw4oNq1a2vEiBHq0KGDKlasqO3btzu9fffu3bVnzx4tX75ckpSSkqKpU6fa1vfo0UNJSUk6fvy4YmJiFBMTozp16mj9+vUqW7ZskdvfrPLlyyswMFDJyclOx1SY2NhY1a9fX6+99pr27NmjIUOG2NbdbB4lOXyQc+7cudqxY4f8/PzUtm1bdevWTbt3776pORRHQbm72eO2qLhvNGdJSktL0549e/Tggw+WyBwBuAdFOgBLqVWrlubOnau33npLtWrVUq1atbRo0SJVrlxZDRo00GeffaaRI0cqPDxcderUUfXq1fX222+7NcZ+/frJ19dXtWrVUrNmzfTQQw/pzjvvdHr7Bg0aaPLkyerfv78iIiIUGRmpNm3a2NbXqlVLX375pV555RXVrl1bERERiomJUVhYmFPbl4Qnn3xSPXv2VHR0tN5///0iY7qRJ554wlaUVqtWzdZ+s3mUrj4DfMmSJbp06ZIkKSIiQqNHj1bt2rXVpEkTvfXWW3rzzTclFZ3XknJ97m72uC0q7hvNWbr6LPmOHTuqfv36JTpPALeWjzHGeDoIALieMUbHjx9XYGCgatSoYbcuJydHR48eVUhIiN0tA3l5edqxY4datmxpu187KSlJFy5cUHh4uK3fvn37FBYWpipVqri0Tf5YR44cUV5ensLDw3XixAn5+vqqdu3aBe7z4sWLOnr0qKKiomz7zMjI0M8//6yGDRsqPT1dp0+fdvhSntOnTysjI8Phvmhnt8+3bds2NW/eXP7+/k7H98svv+iXX35RjRo1VLt27RvGVNA+8126dEn79+9XnTp1HL5Q6UZ5vD7uwjz11FNq0qSJXnzxRVvbqVOndOnSJTVo0EB+fn4O2zg7B2eOhYJiLCh3xTluC3o9Cov7RnPOy8tTy5YtNX36dLVt27bQHAKwHop0AECpduHCBZ05c0YRERGeDsVyrly5okOHDqlFixaeDgVAMVGkAwAAABbDPekAAACAxVCkAwAAABZDkQ4AAABYDEU6AAAAYDEU6QAAAIDFUKQDAAAAFkORDgAAAFgMRToAAABgMRTpAAAAgMVQpAMAAAAW8/8BrcLl9DPXn1wAAAAASUVORK5CYII=", + "text/plain": [ + "
" + ] + }, + "metadata": {}, + "output_type": "display_data" + }, + { + "name": "stdout", + "output_type": "stream", + "text": [ + "max |error| = 0.04 cents\n" + ] + } + ], + "source": [ + "intervals = [-12, -7, -5, -3, 3, 4, 7, 10, 12]\n", + "errors = []\n", + "for st in intervals:\n", + " hz = tap.Harmonizer(sr, dry=0.0).chord([st])\n", + " y = hz.process(saw(220.0, seconds=1.5))\n", + " _, track = track_hz(y[int(0.5 * sr):])\n", + " measured = np.nanmedian(track)\n", + " errors.append(cents(measured, 220.0 * 2 ** (st / 12)))\n", + "\n", + "fig, ax = plt.subplots()\n", + "ax.bar([str(s) for s in intervals], errors, color=C[0])\n", + "ax.set_xlabel(\"commanded interval (semitones)\")\n", + "ax.set_ylabel(\"error (cents)\")\n", + "ax.set_title(\"solo-voice interval accuracy, 220 Hz saw\")\n", + "plt.show()\n", + "print(f\"max |error| = {np.max(np.abs(errors)):.2f} cents\")" + ] + }, + { + "cell_type": "markdown", + "id": "8f14398a", + "metadata": {}, + "source": [ + "## 2 · The dry path is sample-aligned\n", + "\n", + "At interval 0 the phase vocoder reconstructs its input delayed by exactly one FFT frame\n", + "(pinned in DspTap). The kernel delays the dry path by the same amount, so `dry 1` plus a\n", + "unity voice at interval 0 must equal exactly **2 × the delayed input**. The residual is\n", + "numerical noise — this is why chords land as chords instead of flams." + ] + }, + { + "cell_type": "code", + "execution_count": 3, + "id": "dc80a199", + "metadata": { + "execution": { + "iopub.execute_input": "2026-08-05T10:17:13.823615Z", + "iopub.status.busy": "2026-08-05T10:17:13.823430Z", + "iopub.status.idle": "2026-08-05T10:17:13.960988Z", + "shell.execute_reply": "2026-08-05T10:17:13.959908Z" + } + }, + "outputs": [ + { + "data": { + "image/png": "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6y3h7e0thg4dKvz9/cW4ceOEwWCwuu727dtF+/btRc+ePUVkZKRwd3cXr732mp0jpuooPz9fREZGiiZNmoghQ4YIT09PER0dXeZ2RqNRhIeHC41GIxYvXmyHSKm6u3nzpujQoYNo166d6N+/v/D09BT/+9//St3m7bffFt7e3mLw4MGiV69e4oUXXrBTtFSdHT58WPj5+YnQ0FDRo0cP0ahRI3HixIkS11++fLlwd3cXgwcPlnNvzZo1doyYqqupU6eKqKgo0aJFCzFhwoQy11+9erXw9PQUAwcOFK1btxZdunQRqampdojUOhbg1cyBAweESqUSx48fF0IIkZSUJOrXry9Wrlxpdf0tW7aIixcvysuHDh0SAMThw4ftEi9VX4sXLxZNmjSR32B2794tVCqV+OOPP0rd7tNPPxVPP/20CAoKYgFOQgghnn/+eREWFiZ0Op0QwpRbvr6+Ijc31+r6K1asEA0bNhQXLlyQ2zZt2mSXWKl669Kli3jppZfk5WeffVaEhYVZXddoNIp69eqJL774Qm776KOPRLNmzao8Tqo5JkyYUGYBnpGRIby8vMTXX38thDB1UD300EPi5ZdftkeIVnEMeDUTGxuL3r17yx/XNmnSBI8++ihiY2Otrj906FAEBgbKy506dYKTkxNSU1PtEi9VX7GxsRg3bhz8/PwAAH379kWHDh2wYcOGErc5e/YsPvvsMyxatMheYVINEBsbiylTpsgf106ePBnZ2dn47bffrK7/2WefYebMmcjPz8ePP/6IP//8E8OGDbNnyFQNXbp0CcePH8eMGTPkthkzZmDv3r24fft2sfWFENDr9RbDKlu2bImCggK7xEu1x6+//gqj0YiJEycCAJydnfH888+XWFvZA8eAVzMXL15Eq1atLNoCAwMRFxdn0/ZLly6Fn58f+vTpUwXRUU1y8eJFjB492qItMDAQFy9etLq+wWDAs88+i08++QS+vr52iJBqgoyMDKSlpVm8L7m7uyMgIMBqLhmNRpw4cQKNGzfGt99+i7Zt22Lv3r0YP348lixZYs/QqZox50vRXDJ3IF26dAn+/v4W66tUKnz66ad4++23ceXKFej1eixduhQLFy60W8xUO1y8eBFNmzaFs7Oz3BYYGIikpCQUFBRYtNsLC/BqRq/XF0sEFxcX6PX6Mrddt24d3n33XWzcuBFeXl5V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", + "text/plain": [ + "
" + ] + }, + "metadata": {}, + "output_type": "display_data" + }, + { + "name": "stdout", + "output_type": "stream", + "text": [ + "max |residual| after settle = 3.68e-08\n" + ] + } + ], + "source": [ + "hz = tap.Harmonizer(sr, dry=1.0).chord([0.0])\n", + "x = saw(220.0, seconds=1.0)\n", + "y = hz.process(x)\n", + "lat = hz.latency\n", + "err = y[8192:] - 2.0 * x[8192 - lat:-lat]\n", + "\n", + "fig, ax = plt.subplots()\n", + "t = (np.arange(len(err)) + 8192) / sr\n", + "ax.plot(t, err, color=C[1], lw=0.8)\n", + "ax.set_xlabel(\"time (s)\")\n", + "ax.set_ylabel(\"out − 2·in(t − latency)\")\n", + "ax.set_title(f\"dry/wet alignment residual (latency = {lat} samples)\")\n", + "plt.show()\n", + "print(f\"max |residual| after settle = {np.max(np.abs(err)):.2e}\")" + ] + }, + { + "cell_type": "markdown", + "id": "a546b527", + "metadata": {}, + "source": [ + "## 3 · Formants stay home\n", + "\n", + "The point of the object. A synthetic \"voice\": 240 Hz source whose harmonics are shaped by\n", + "a fixed resonance at 960 Hz — the envelope is the identity, the harmonics are the pitch.\n", + "Shift a fifth up (+7) with `formant` on and off. Off, the whole spectrum — bump included —\n", + "rides up the full ratio to ~1440 Hz: the chipmunk. On, the harmonics move while the LPC\n", + "correction holds the envelope most of the way home (the band centroid below quantifies\n", + "exactly how far): the same person, higher." + ] + }, + { + "cell_type": "code", + "execution_count": 4, + "id": "6a0cced6", + "metadata": { + "execution": { + "iopub.execute_input": "2026-08-05T10:17:13.963453Z", + "iopub.status.busy": "2026-08-05T10:17:13.963176Z", + "iopub.status.idle": "2026-08-05T10:17:14.175395Z", + "shell.execute_reply": "2026-08-05T10:17:14.174379Z" + } + }, + "outputs": [ + { + "data": { + "image/png": "iVBORw0KGgoAAAANSUhEUgAAAvgAAAFbCAYAAACgQvo+AAAAOnRFWHRTb2Z0d2FyZQBNYXRwbG90bGliIHZlcnNpb24zLjExLjEsIGh0dHBzOi8vbWF0cGxvdGxpYi5vcmcvctoD+AAAAAlwSFlzAAAOxAAADsQBlSsOGwAAtDVJREFUeJzsnXecFEXax389YSMb2F1YcloRQRADWVHxQKIRFVQQPVBU9NRDj/MAPe/E7GtAEU8UMaKYUDEBIgIGFAUFCZKUuOwubJzZCd31/jHTvd0Tu2ema2aK+n4+sDPdPV2xq59++ldPCYQQAg6Hw+FwOBwOh8MElmRngMPhcDgcDofD4SQObuBzOBwOh8PhcDgMwQ18DofD4XA4HA6HIbiBz+FwOBwOh8PhMAQ38DkcDofD4XA4HIbgBj6Hw+FwOBwOh8MQ3MDncDgcDofD4XAYghv4HA6Hw+FwOBwOQ3ADn8NhiEceeQSdOnVKdjaSxvPPP4+SkpJkZ+O4hcX+V1JSgueff56ZdDgczvEBN/A5nDTk6aefRqtWrYK2OxwOVFZWJiFHqYHT6URVVVWysxET4do0FTme+l9VVRWcTicAwOVyoaSkBC+++GJM54r0e3U6HA6HEy+2ZGeAw+EYh0VD6ngnndo0nfIaLxUVFWjWrBkAgBASlyEe6ffqdDgcDideuAefw0kzHnzwQfz3v/+FKIooKSlBSUkJysrKNMc4nU5MmzYNnTp1Qq9evUJ6DPfv348bb7wR3bp1Q7t27TBq1CisX79eVx70/FaWa0TKyxdffIGSkhL89NNPQWlMnToVp59+etz5/eWXX3DZZZehY8eO6NKlC6655hrs3r07ZF5ra2sxefJkdOzYEaeeeipeeOGFmMoeiurqakyfPh2nnHIKOnXqhBEjRuCTTz4BELlN33//fWVbaWkpTjvtNPztb39DeXm5cu6VK1eipKQEP/zwQ1C6U6ZMQd++faPmQS/p0P+2bt2KNm3a4N5779X87sknn0RpaalST4QQvPjiizj77LPRrl07DBgwAM8//zwkSVJ+c9JJJ2HRokU4evQo2rVrBwD45z//qZR98eLFAICTTz5ZUx8jRozAZ599ppwn2u/ldGRcLhf++9//onfv3mjbti3OPPNMvPrqq5ry1NbWoqSkBK+99ho++ugj9O3bF+3bt8eECROiPoCpf/vuu+/i9NNPR1lZGWbPng1CCFwuF/7+97/jhBNOQK9evfDWW28FnUNPHvv27YupU6cG/fann35CSUmJ0v8IIXjhhRdw5plnom3btjjllFPw0EMPQRRFze/ef/99DBkyBB07dkSfPn1w9913o7a2NmJZOZzjEsLhcNKKhoYGMnv2bGK1WklFRQWpqKggVVVVhBBC7r33XpKbm0tuuOEG8tZbb5Fdu3aRf//73wQAWbNmjXKOP/74g5SWlpIhQ4aQb775hvz+++9kxowZJCsri/z4448R09f7Wz15cblcpKioiNx+++2aNOrr60lubi65++67DaX5xBNPEPWwtmnTJpKbm0vGjh1LNm3aRH744QcyePBg0qJFC/Lnn38G5XXChAnkrbfeIjt37iSPP/44sVqt5IUXXkhIvV100UXk1FNPJevWrSP79u0jK1asIGPGjCG7du2K2KYul0vZdujQIbJmzRoyePBg0rt3b+LxeAghhHi9XtKuXTsydepUTZpHjx4lWVlZ5P7774+aB72kS/975JFHiMViIatWrSKEELJhwwaSkZFB/vWvfynHTJkyheTk5JC5c+eSHTt2kO+//57ceOON5NNPP1WOAUCeeOIJIkkS2b9/PwFAHnroIaXsjY2NhBBCqqqqlG07duwgDz30ELFareSLL74ghJCov5fTkbngggtISUkJeffdd8nOnTvJY489RqxWK3nooYeUY44dO0YAkIkTJ5KpU6eSLVu2kK+//pq0b9+eXHbZZRHrUf7tVVddRf72t7+Rbdu2kaVLl5Lc3Fwyd+5ccsMNN5BXX32V7Ny5k9x5553EarWSHTt2aM6hJ4+zZs0iubm5pL6+XvPb2267jRQWFirlv/HGG0l+fj554YUXyK5du8iyZctI27ZtyfXXX6/85ssvvyRWq5U888wzZO/evWTTpk3kkUceIbNmzYpYVg7neIQb+BxOGvLggw8Sq9UatP3ee+8lAMiiRYs027t160YmTZqkfL/qqqtImzZtgm66Q4YMIaNGjYqYtt7f6s3LTTfdREpLS4nX61W2vfLKKwQA+e233wylGWjgjxkzhrRv314xhAnxGb3NmjUjN9xwQ1Be1cY8IYRMnTqVtGrVSjFC4qm37OxsMnfu3KDtkiQRQsK3aSj27t1LAJDVq1drypCfn08aGhqUbU8//TSx2Wzk4MGDuvKgl3To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jQkCX8V1ySviITI5xwX5+flUI/7U1NQoAT3C8d5772HAgAEoKCiglCs66Cn7X//6V3z11Vd47bXXsGzZMmzduhUTJkxQ9u/cuRMDBw5E165d8cUXX+Cpp57CU089pex/+eWXMWvWLDz88MP4/PPPceTIEVx66aVh06utrQ25hkBNTQ3q6+t1l23UqFFYsmSJ7uNpw8RoLggCHn30UdTW1uLQoUPYtm0b+vXrl+xscTjHLbKB39DQQC1iAHc+x4Zcbw0eNyReiZzjgHHjxmHevHnK94suuggPPvggJkyYgLKyMvTv3x9ffvmlZv+cOXMwbtw4dOnSBUOGDMEPP/yg7B88eDA++ugj5XtDQwNKSkqwb98+3Hnnnfj6668xa9YslJSUYODAgSHz9M033+C0004L2n748OGw6Z599tlh05XzPXv2bFxxxRXo0qULBg4ciB9++AFLlizBGWecgc6dO+OOO+7QrD4crayB3HTTTSgpKUGLFi1w+umn4/HHH1fe2uopu9PpxLvvvosHHngAp512Gnr06IEnn3wSH374IXbt2gUAmD17NoYOHYo5c+bgpJNOwumnn47Fixcr53j66adx6623YvTo0ejRowfmz5+PtWvX4ueffw6b72hs2LABJSUlQf/U9X3GGWcEvUlIJZgw8GXsdjsKCwuTnQ0O57hHNupdLhdFiQ43TmNB9uBXuxt5HXIShtfrxZEjR6j9U4e/jkZNTY1momNNTQ0effRRjB07FqtWrcKoUaMwbtw4uFwuZf/999+PMWPGYOXKlTjvvPNw3nnnobzcN8H/2LFjyrGAbyyqqqqCKIq47777MHDgQNx9993Ytm0bPv3005B52rdvH0pLg0P9Pv744zGlK+d73rx5mDhxIlatWoWTTjoJo0aNwiuvvIJXX30V77zzDpYsWYI33nhDUxeRyhrIo48+im3btmHLli144oknMH/+fLzyyisAoKvsHo8HkiRpFBfyZ/nB4osvvkCvXr1w/vnno0OHDhg2bBi+++475fe//PKL5uGhU6dOaNWqFTZs2BAyz3ro3bs3tm3bpvybNWsWcnNzldDPgG+C+v79+2NOw2yYmGTL4XBSC9lQzMnJ4RKdNKF9swJYuUSHkyCOHj2K5557jlp6N910E1q2bBnz76dOnYpLLrkEAPCvf/0L//nPf7Bnzx6cdNJJAICrr74a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", + "text/plain": [ + "
" + ] + }, + "metadata": {}, + "output_type": "display_data" + }, + { + "name": "stdout", + "output_type": "stream", + "text": [ + "spectral centroid of the 0.6-2.2 kHz band: input 1058 Hz, formant on 1154 Hz, off 1439 Hz\n" + ] + } + ], + "source": [ + "def formant_voice(f0=240.0, center=960.0, seconds=1.5):\n", + " t = np.arange(int(seconds * sr))\n", + " x = sum((np.exp(-(((f0 * h) - center) / 180.0) ** 2) + 0.05)\n", + " * np.sin(2 * np.pi * f0 * h * t / sr) for h in range(1, 26))\n", + " return x / np.abs(x).max()\n", + "\n", + "x = formant_voice()\n", + "runs = {}\n", + "for on in (True, False):\n", + " hz = tap.Harmonizer(sr, dry=0.0, formant=on).chord([7.0])\n", + " runs[on] = hz.process(x)\n", + "\n", + "fig, ax = plt.subplots(figsize=(9, 3.6))\n", + "f, db = spectrum_db(x)\n", + "ax.plot(f, db, color=\"gray\", lw=1.0, label=\"input (bump at 960 Hz)\")\n", + "f, db = spectrum_db(runs[True])\n", + "ax.plot(f, db, color=C[0], lw=1.2, label=\"+7 st, formant on\")\n", + "f, db = spectrum_db(runs[False])\n", + "ax.plot(f, db, color=C[3], lw=1.2, label=\"+7 st, formant off\")\n", + "for fc, c in [(960.0, \"gray\"), (960.0 * 2 ** (7 / 12), C[3])]:\n", + " ax.axvline(fc, color=c, lw=0.8, ls=\":\", alpha=0.7)\n", + "ax.set_xlim(0, 3000)\n", + "ax.set_ylim(-70, 3)\n", + "ax.set_xlabel(\"frequency (Hz)\")\n", + "ax.set_ylabel(\"dB re max\")\n", + "ax.set_title(\"the envelope stays, the excitation moves\")\n", + "ax.legend(loc=\"upper right\")\n", + "plt.show()\n", + "\n", + "def bump_centroid(y):\n", + " f, db = spectrum_db(y)\n", + " band = (f > 600) & (f < 2200)\n", + " w = 10 ** (db[band] / 20)\n", + " return float(np.sum(f[band] * w) / np.sum(w))\n", + "\n", + "print(f\"spectral centroid of the 0.6-2.2 kHz band: input {bump_centroid(x):.0f} Hz, \"\n", + " f\"formant on {bump_centroid(runs[True]):.0f} Hz, off {bump_centroid(runs[False]):.0f} Hz\")" + ] + }, + { + "cell_type": "markdown", + "id": "f5112027", + "metadata": {}, + "source": [ + "## 4 · A chord, and the glide\n", + "\n", + "Left: the \"715 - CRΞΞKS\"-school stack from the book's recipe — `chord -12 3 7` with the\n", + "dry voice inside it — as a spectrum: four fundamentals from one input. Right: the `glide`\n", + "control walking one voice from unison to the octave through a 300 ms one-pole — the pitch\n", + "travels, it doesn't jump (and no group of human singers can do this)." + ] + }, + { + "cell_type": "code", + "execution_count": 5, + "id": "e36f6f7b", + "metadata": { + "execution": { + "iopub.execute_input": "2026-08-05T10:17:14.178476Z", + "iopub.status.busy": "2026-08-05T10:17:14.178258Z", + "iopub.status.idle": "2026-08-05T10:17:14.993701Z", + "shell.execute_reply": "2026-08-05T10:17:14.992831Z" + } + }, + "outputs": [ + { + "data": { + "image/png": "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tG3blvnz54e83+v1ctNNN9GqVSuSk5Np3749t912G4cPHw5uU1BQUGXtntdff520tLQyfwMfe+yxkGGlgXhXrlzJTTfdRJMmTUhKSuL8888PSUyU/lzDiXPjxo2MGTOGpKQkEhMT6dmzZ5nrhHCPX9fCiRX85+i0adPIyMggMTGRbt268cwzz6CUYtGiRZxzzjmA/1wJXDv98ssv7N69O2TIbEpKCoMHDw558HD48GFatGjBww8/XOa4/+///T+aNWvGvn37gnFE8mdFNBBKiCj59ddfVXp6uho1apT65ZdflGVZatWqVWrq1KnBbZ588kkFqMsvv1wtWrRI+Xw+9d577yld19ULL7wQ3O6nn35SCQkJasqUKWr//v0qOztbXX311co0TfXtt9+W2d9FF12kvvjiC2VZVnDdv/71L+V2u9XLL7+sPB6P+umnn9T48eNV69at1a233lrr7/fqq69WCQkJYW9/4403KkD99NNPYW2fl5encnJy1LJly9QJJ5ygjj32WFVYWFitGO+66y4FqO+//77KbZ944gllGIZ65plnVGFhodq4caMaOHCg6ty5szp8+LBSSqnt27crTdPUM888E/LeRYsWKUB9/PHHSimlXn/9daVpmrrvvvvUoUOH1KFDh9Sf/vQn1bRpU7V9+/bg+8aMGaP69++vxo8fr3777bcqY5w4caIaPHhwmeVjxoxRAwYMUOeff7767bffVGFhobr55puVy+VSO3bsCG4XblzlCfd8quh72rdvn3K73erxxx8P2e+HH36oAPXNN9+Ue9xw2zycz08ppS6++GI1aNCg4OuXX35ZaZqmZsyYofbu3asKCwvVggUL1MyZMyPSbkIIEQnZ2dkqPT1djR8/XmVlZanDhw+ru+66S40cOVIZhhHc7ocfflCA+vrrr8t9ffDgQZWRkaHGjRun9uzZow4dOqRuu+22Mvs5fPiw6tGjhzr22GPV6tWrlWVZ6rPPPlPNmzdX9957b1gxe71elZubq7Zv364eeughlZCQoObPnx9cf/311yvTNJVt2yHvW7x4sQLUO++8U63tyvPpp58qQJ177rnq3XffVV6vV7333ntK0zQ1d+5cdc4556iNGzeqwsJCdcUVV6imTZuq3Nzc4PtnzJih2rZtq37++WellFJ79uxRTzzxRMgxe/Toofr3719pW8yZM0cBat++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G9xxxx0qMzMz+PqXX35RaWlpaty4cWrt2rVqw4YN6rzzzlPJyckhhYYq2p9SSj3//PPKMAz1xBNPqJ07d6pPPvlEnXvuuapt27Y1Ljhn27bKzc1Vubm5atq0aSohISH4umShyeuuu04BatasWcH1gS+v11vpMUaMGKFef/11tWnTJrVnzx61cOFCNWDAANW6deuQGQ4qc/bZZ6tmzZqpoqKisL+35557Tmmapv7+97+r7du3qyVLlqju3burPn36lCm8Y1mWyszMVJmZmUrXdbVr166Q9QsXLlRut1tdc801avXq1SorK0t9++236qabblKPPPJIcLsxY8aok08+OewYH3nkEZWUlKRWrFihcnNzg597Rfvp37+/mjJlSrXjKk+451M439PkyZMVUG6l5YpU1ebhfn6lZ4X48MMPlWmaatq0aWr16tVq+/bt6oUXXgj5nmrTbkIIEQl5eXmqXbt26pRTTlGrVq1SmzdvVtdcc40aP358tYo3BvYzfPhw9fPPP6tff/1VXXHFFWX2U1hYqAYPHqy6d++u5s2bp3bv3q3Wr1+vXnjhhTLFdEv7xz/+of7yl7+oZcuWqb1796q1a9eq2267TQHBgsIBd955p2rSpImaP3++2rt3r3rooYeUruvqo48+qtF2pQWKEa5cuTJk+dVXX6169OhRZvumTZuqGTNmBF+PGTNGPf3002rNmjVq3759asGCBSo9PV3dfffdwW3CmRVCKaUGDx6s+vfvr9asWaN++eUXdfnll6tJkyaVW7yxdLzPP/+8AoLFO0t/rlXFefDgQdWxY0c1aNAg9cMPP6gtW7aoW265Rem6rt57771qH78mbr755pBZQSoSbqwFBQVq4MCBqlOnTsFz9Ntvv1UTJkxQe/bsUUopdejQIZWUlKRuueUWdeDAAZWbm6ts21YvvPCC0jRNzZ49W+3Zs0d98MEHavjw4apv377q4osvLhPT3//+d5WUlKTS0tLKFAKtzc+KaNgksSCiateuXeqqq65SnTp1UpmZmeqMM84IqUQ7a9YslZKSUuaG9+6771ZdunQJWbZ69Wo1YcIElZmZqVq1aqXGjBmjVqxYEbJNRfsrub5Xr16qRYsWavz48Wr37t2qe/fu6q677qrR97du3TqVkpJS7lfJfTZt2rTC7WbNmlXlMa688krVs2dP1apVK3Xssceqv/zl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G9M0sC0LlIOuO8VtALoGls+HroGuK3w+L0bx7YtlO7hMA8dRKFcLlGqJZVlomlarNij5N68ykliIpA/f8D+B374ZZj4NxwzwL887DHNnw86t/q7qLjdceas/wSBC6fqRdqtrO7dC+05lj7vgLVi6CNKaQs4BOHcqDDyhfmKqjtxD/mKNzZqHxv/D17BxzZHtft8O506BwSdHJUwhhKhPt99+OwMGDOCkk04CYPfu3bRt2zZkm7Zt2/LVV1+Ftb60+++/n5kzZ5ZZPm/ePE499VQ++eQTOnToQK9evXj99dcZMWIELVq0YPbs2UyYMIEDBw7wySefcPHFF7Nx40Y2b97MWWedxdKlS9E0jcGDB/PRRx9x9NFHc/TRR/Pyyy9z1llnkZqaygsvvMBVV13Fnj17+Prrrzn//PNZt24du3btYtSoUSxZsoSkpCQGDRrEBx98QN++fencuTMvvPACEyZMwDRNXnvtNa688kp27NjBDz/8wLnnnsuqVas4cOAAI0aMYNGiRWRkZNCvXz/eeecdjjvuODp06MDs2bOZPHkylmXx7rvvMnXqVLZs2cLq1as5++yzWbFiBYWFhQwdOpRPP/2Udu3accwxx/DGG28wbNgwWrduzX//+1+mTp1KXl4eCxYs4JJLLmHTpk1s2rSJ0aNH8/3336OUYsiQISxYsICuXbvSvXt3XnnlFc444wyaNm3Kc889x5VXXsmWLVt44403uPDCC1m/fj07duzg9NNP55tvviEhIYFjjz2WefPm0bt3b7p06cKLL77IOeecQ0JCAi+//DLTp09n586dLF26lPPOO4/Vq1ezb98+Tj31VL788kuaNm3KgAEDePfddxk0aBBHHXUUzz77LBdccAFKKd566y0uv/xytm7dys8//8w555zDypUryc3NZfjw4Xz++edkZmbSp08f3nzzTU466STatm3LrFmzmDJlCgUFBXz44Ydceuml/Prrr/zyyy+MGTOGH374AZ/Px4knnsjChQvp2LEjPXv25LXXXmPkyJE0b96cZ599lmnTppGdnc3nn3/O5MmT2bBhA9u2beOMM87g22+/xeVycdxxx/Hhhx/So0cPunXrxpw5cxgzZgzJycm8+OKLXHXVVfz666+88847TJo0iTVr1pCVlcXIkSP56quvSEtL4w9/+APvv/8+/fv3p1OnTjz//POcd955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IyOjyvZooH1xt2zZgh9//BFr1qzB6tWrAajHjv8dlJycHP2zV9UeyR5++GH069cPX3/9NdavX4+DBw+isLAQ69evR2lpadDPrk2ZqKo9moiiiNtuuw179+6Foij6z9/781+8eFFvq6o90mVkZGDAgAF6Flhqair69euHAwcO6O2N9XvlbcWKFZg5c6bPSik0NvWrpuNJ428sIyMDZWVl+jRCoOL3W3XGJi4uDjfffDN2795dZ32MVnRM1o20tDTceOONdEx6SJKEqVOn4tixY/jiiy+QlJRkuF1MTAyaNGlCx2QlPv30U9x444146623MH78+Gq/rl27drjuuutMPyYpsFBD/fr1AwBs27ZNf27Lli36sotVtUe60tJSjB49GhzH4ZNPPkFCQoLeZrFYcM011+Djjz/Wn9uxYwecTif69+9fZXuky83N9XmclpaG1NRUFBUVAQAGDRqErVu36hFYm82GHTt26MuZVtUeya644goIgoDNmzdj8+bN+PXXX1FYWIjNmzejtLQUgwYNwsmTJ/X0f0D93niPTWXtkczpdOrHiObAgQNo2bIleJ5H27ZtkZWV5fO92bJlC1JTU9G9e/cq2yPdkCFDfGpFMMZw9OhRPU160KBBPp/93Llz2L9/v8+xU1l7NPjyyy9x5MgRzJw50+f5QYMGYc+ePT5zLj/++GOfsamsndTMoEGDsG3bNv3GgsPhwPbt2/XxzM3Nxfr16/VpPFVt31j17t0b8fHxAb/TLrvsMn35yK1bt+LgwYMAgOLi4oDaCwcOHNDrFZHgjh8/7rMEnf/vy9zcXOzdu7fRH5PV8f777+vp+Xl5eQEZlT/99BMdk1B/z40fPx65ubn4/PPPA5Y/PXjwILZu3ao/9j8mf/zxR+Tk5OjTjBuz999/H1OnTsX69esDggoulwvr16/Xr038r1FkWcbhw4fNPybrtDRkhPr222/ZunXr2OjRo1mPHj3YunXr2NatW/X2xx57jGVkZLAlS5awRx99lFmtVvb5559Xuz1SKYrCrr76apaZmcneeusttm7dOv0/zVdffcViYmLYgw8+yF566SWWmZnps2RiVe2RbM6cOWzGjBls+fLlbNmyZWzEiBGsRYsW7NSpU4wxtSJrVlYWGzt2LFu+fDkbOHAgu/LKK/VVNqpqjybPPPNMwHKTN998M+vUqRNbunQpmz17NktISGAHDx6sdnukKiwsZF27dmWPP/44e/PNN9m9997LYmJi2Nq1a/Vt/vWvf7HY2Fj29NNPs+eff54lJSWxV199tdrtkSwnJ4dlZmayqVOnslWrVrHJkyez5s2bs5ycHMYYYydOnGBpaWls+vTpbNmyZaxHjx4+q/lU1R4NJk+ezMaPHx/wvKIobPDgweyqq65ir732mj52Z8+erVY7qZmSkhLWoUMHNmrUKLZ8+XI2ZMgQdtlll+kV0D///HMGgF28eLFa2zdmzz77LEtLS2Mvvvgie+KJJ1hMTIzP0tSXXXaZvmrEr7/+yi6//HL29NNPs1WrVrHbbruNWa1W9sUXX4Sr+w1GUVERW7duHXv99dcZALZo0SK2bt06/Tu+cuVKlpCQoG9/+vRp1rRpU3bzzTezZcuWsSuvvJINGzYs6BJ2jcmOHTvYunXr2IABA9iAAQPYunXr2I4dO/T2hIQEtnLlSsaYunJRnz592HPPPcdef/11Nn78eJaUlORTxb+xGj58OEtPT2dvvvmmz3WEdq47f/58dtlll+nb//jjjywuLo7NnTuXvfrqq6x9+/bszjvvDFf3G4wPP/yQCYLA5syZ4zOO2nmxthKMdv25Zs0aNmTIELZkyRK2bNkyNmjQIJaZmamfS5mFY4xK5/p75ZVX8O233/o817ZtW585fOvXr8e2bdsQHx+PW265BVdffbXP9lW1RyJFUQwL7wHwmbejTQEoKyvDddddp1dwrW57JNu4caNeqbZLly6YNm0a0tLS9Pbc3Fz885//xMmTJ9GlSxfcc889SE5OrnZ7tNi0aRP27t2LRYsW6c/JsoxVq1bhu+++Q3p6OmbOnIkuXbpUuz2S5efnY9WqVfjtt9+QmZmJiRMnokePHj7b/Oc//8GGDRugKApuuOEGjBkzpkbtkSwnJwevvfYaTp06hezsbMyePdtnatmJEyewfPly5OTkoGfPnpgzZ44+J7s67ZFMlmXceeeduOuuuwwzv+x2O1577TX89NNPyMzMxN/+9je0adOm2u2kZvLy8rB06VIcP34cnTp1wty5c/VpPIcOHcLChQuxcuVKPfW3su0bu/fffx+ffPIJYmJicPPNN+urlwDAQw89hN69e+srBZ0+fRqrV6/G6dOncckll+CWW24JKELYGJ05cwYPPvhgwPOPPPIIrrzySuzYsQNr167FmjVr9LZTp07htddew/nz53HllVdizpw5PlX8G6tFixbpWTKa7t27Y/78+QDU1Q5uvfVWDBkyBADwyy+/4J133sHFixfRoUMH3H777ZS+D3WcjFZ3efPNNxEfH493330XP/zwA1544QW97dChQ1i1ahUKCwsxcOBA3HbbbT7T/hqjd999Fxs3bgx4fsKECZgwYQJKS0sxa9YsPP744+jWrRsAdWXD9957D2VlZejSpQtuv/12068xKLBACCGEEEIIIYSQkFGNBUIIIYQQQgghhISMAguEEEIIIYQQQggJGQUWCCGEEEIIIYQQEjIKLBBCCCGEEEIIISRkFFgghBBCCCGEEEJIyCiwQAghhBBCCCGEkJBRYIEQQgghhBBCCCEho8ACIRGsoKAAs2bNQt++fbF27dpwd6dBYIzhr3/9K44ePWrae7733nt4+umnTXs/QgghhNQ9WZZx/fXX4/z581Vuu3r1aixZsqQeekVIdKLAAiER7KGHHkJJSQlefvlljBw5MtzdaRD+/e9/o7CwENnZ2aa958iRI7Fs2TKcPHnStPckhBBCGovXX38djzzySL3v980330RMTAxatmxZ5bZjxozB4sWLceHChXroGSHRhwILhESwr7/+GnfccQeuvvpqtGjRItzdaRBeeukl3HnnnfrjLVu2YNSoUQHbrVu3DhMmTKjWeyYlJWHcuHF47bXXTOsnIYQQEo1ee+01zJ8/3+e5MWPGYPbs2fXel5dfftnnnKAyzZo1w+DBg7Fq1ao67hUh0YkCC4REsPz8fCQkJIS7Gw3G6dOnsXv3bowZM0Z/Li8vDwcOHAjYNjc3F4cOHar2e48bNw7r1683o5uEEEJI1Dp79iyOHTvm81xmZibat29fr/34+eefcfz4cYwYMaLar6G/9YSEjgILhESgsrIy9OrVCyUlJZg5cyZ69eqFU6dO4dixY+jVqxd2796N6dOno3///gCAgwcP4s4778TgwYNxxx134MiRIz7v98EHH2DcuHEYN24c3n77bcyePRvvvvsuADXav3DhQp/tZ86ciY0bN+qPK3v/tWvX4oEHHsDatWsxduxYjB49Ghs2bPB5v4MHD2LmzJkYMmQI/v73v6OoqAgXL15Enz59cO7cOZ9t77rrLqxcudJwXHbu3Ins7Gw0adKkhiMKDBkyBL169fL5z/tz9+7dG6dPn8bp06dr/N6EEEJIY7Blyxa8+eab2LZtm/63tKysLGAqxNKlSzF//ny8+OKLGD16NK6//np8+eWXOHnyJO644w4MHDgQ8+bNg81m83n/H374AbfeeisGDx6Mu+66q9K/yTt37sTll18Oi8WiP3fq1CnMmTMH1157LaZPn479+/f7vKZ37944ePAgioqKzBkQQhoRCiwQEoHi4uKwfPlyxMXF4aGHHsLy5cuRkZEBu92OH3/8Effeey8mTZqEV155BXv27EH//v3RuXNnPP300+jQoQP69OmDnJwcAOpJwPTp0zF69Gjcd999ePfdd7FmzRp9juGff/4ZUFvgt99+09urev/z589j2bJl2LlzJ+bNm4dx48Zh+vTp+OmnnwAA3333Ha6++mpkZmbi//2//4f27dvj0UcfRbNmzdCkSRO88cYb+n5PnjyJN998E4MHDzYcl5MnTyIzMzOkMV2yZAmWL1+O5cuXY8GCBfjjjz987q5kZGRAFEWcOnUqpPcnhBBCot0111yD0aNHo3fv3vrf1Li4OJw7d84ni+HMmTN44YUXkJOTg0cffRSXXnopxo4diylTpmDYsGF48skn8fnnn/sUTt6+fTuGDx+Onj174umnn0azZs3Qp0+foEEAo3OCCRMmwGazYeHChRg7dizmzp0Ll8ult2dmZoIxhj///NPcgSGkERDD3QFCSM0JgoBevXpBEARceuml6NWrl0/7ypUr0aNHDwDA6NGjce+99+Khhx4CAFx77bXYv38/3njjDTz++ON48cUXMW/ePNx9990AgL59+6J169bV7suTTz5Z6fsDQLt27fD666+D4zgMHjwYGzZswNdff40ePXrgqaeewqxZs/SThyFDhsDpdAIA/va3v+H+++/H/PnzIQgCVqxYgYEDB6Jjx46GfXE6nbBarQHP5+fnB4zRhQsXEB8frz++4oorAKjZILNnz8ZDDz2Em2++2ec1FotF7xshhBBCfKWnp6Nly5YoLy8P+Lvrr2fPnnjxxRcBAP3798fSpUtx9913639777//frz++uv69k888QTmz5+P+++/H4B6vrF792688847mDt3bsD7G50TnDt3Dk8//TSuvfZaAMBNN90EUay4HIqJidFfSwipGQosEBKFunXrpv/78OHD+OOPP/DZZ5/pz509e1avzXDkyBHMmzdPb0tMTMSll15a7X1V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", + "text/plain": [ + "
" + ] + }, + "metadata": {}, + "output_type": "display_data" + } + ], + "source": [ + "fig, (ax1, ax2) = plt.subplots(1, 2, figsize=(11, 3.4))\n", + "\n", + "hz = tap.Harmonizer(sr, dry=1.0).chord([-12, 3, 7])\n", + "y = hz.process(saw(220.0, seconds=1.5))\n", + "f, db = spectrum_db(y)\n", + "ax1.plot(f, db, color=C[0], lw=1.0)\n", + "for st in (-12, 0, 3, 7):\n", + " fc = 220.0 * 2 ** (st / 12)\n", + " ax1.axvline(fc, color=C[2], lw=0.8, ls=\":\", alpha=0.8)\n", + " ax1.text(fc, 1, f\"{st:+d}\" if st else \"dry\", ha=\"center\", fontsize=8, color=C[2])\n", + "ax1.set_xlim(80, 700)\n", + "ax1.set_ylim(-60, 6)\n", + "ax1.set_xlabel(\"frequency (Hz)\")\n", + "ax1.set_ylabel(\"dB re max\")\n", + "ax1.set_title(\"chord -12 3 7 over the dry voice\")\n", + "\n", + "hz = tap.Harmonizer(sr, dry=0.0, glide=300.0).chord([0.0])\n", + "a = hz.process(saw(220.0, seconds=0.5))\n", + "hz.set(intervals=[12.0])\n", + "b = hz.process(saw(220.0, seconds=2.0))\n", + "t, trk = track_hz(np.concatenate([a, b]))\n", + "ax2.plot(t, cents(trk, 220.0), color=C[1], lw=1.4)\n", + "ax2.axhline(1200, color=\"gray\", lw=0.8, ls=\":\")\n", + "ax2.set_xlabel(\"time (s)\")\n", + "ax2.set_ylabel(\"pitch (cents re 220 Hz)\")\n", + "ax2.set_title(\"glide 300 ms: unison → octave\")\n", + "plt.tight_layout()\n", + "plt.show()" + ] + }, + { + "cell_type": "markdown", + "id": "a3eec574", + "metadata": {}, + "source": [ + "---\n", + "\n", + "Every number above is the shipping kernel measured through its C ABI; the same contract\n", + "points are pinned CI-side in `tests/harmonizer_test.cpp` (intervals under the YIN oracle,\n", + "dry alignment to 1e-6, the formant bump staying home, the glide walking through the\n", + "middle). The book's recipe — *A choir of one* — cites this notebook and those tests." + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "Python 3", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.11.15" + } + }, + "nbformat": 4, + "nbformat_minor": 5 +} From 0d9993aeae55a1e234757661b79957398d0b88fb Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 5 Aug 2026 10:22:46 +0000 Subject: [PATCH 09/12] Add CI badges to the README build, Tap House Style, and Docs workflow badges under the title, each linking to its workflow's run history. Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01V6CC6kpK5Lx2YkJWuNNQpw --- README.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/README.md b/README.md index 69302ed..5e21782 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,9 @@ # TapTools kernel +[![build](https://github.com/tap/TapTools/actions/workflows/build.yml/badge.svg)](https://github.com/tap/TapTools/actions/workflows/build.yml) +[![Tap House Style](https://github.com/tap/TapTools/actions/workflows/style.yml/badge.svg)](https://github.com/tap/TapTools/actions/workflows/style.yml) +[![Docs](https://github.com/tap/TapTools/actions/workflows/docs.yml/badge.svg)](https://github.com/tap/TapTools/actions/workflows/docs.yml) + The portable DSP library behind the TapTools Max package: header-only, plain C++20, **no Max SDK, no min-api, no Jamoma**. One self-contained header per object under `include/taptools/`, each in its own `tap::tools::` namespace. The TapTools Max externals are thin From 5767f255d480e8e6b51e77bcd5556426969478fb Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 5 Aug 2026 11:22:53 +0000 Subject: [PATCH 10/12] Point the formant-shifting cross-references at tap.harmony~ The pitchaccum, vocoder, and tune chapters' wrong-tool lists predate the harmonizer and recommended workarounds for exactly what it now does; each names the object. Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01V6CC6kpK5Lx2YkJWuNNQpw --- book/src/pitchaccum.md | 5 ++--- book/src/tune.md | 7 ++++--- book/src/vocoder.md | 4 +++- 3 files changed, 9 insertions(+), 7 deletions(-) diff --git a/book/src/pitchaccum.md b/book/src/pitchaccum.md index 79e5999..ad44695 100644 --- a/book/src/pitchaccum.md +++ b/book/src/pitchaccum.md @@ -102,9 +102,8 @@ spirals and a timed `recall` between them is a gesture in itself. - **One clean transposition, no loop:** `tap.shift~` is the plain shifter — same modernized engine, none of the plumbing. - **Formant-true vocal shifting:** granular transposition shifts formants - with the pitch; chipmunks live this way. A vocoder-based resynthesis - (`tap.vocoder~` has other talents) or a dedicated formant tool is the - answer there. + with the pitch; chipmunks live this way. `tap.harmony~` is the dedicated + tool — formant-preserving voices at fixed intervals, chords included. - **Rhythmically exact multi-tap echoes:** the delays here serve the loop; `tap.multitap~` serves the grid. diff --git a/book/src/tune.md b/book/src/tune.md index 072ba98..52afeb7 100644 --- a/book/src/tune.md +++ b/book/src/tune.md @@ -150,9 +150,10 @@ so what you see is what it acted on. coloration to sustained noise. For processing unpitched material there are better rooms in this house. - **Creative shifting.** If the goal is *an interval* rather than - *intonation*, `tap.shift~` is the plain shifter and `tap.pitchaccum~` - the spiral; `tap.tune~` always measures first and that measurement is - latency you don't need. + *intonation*, `tap.shift~` is the plain shifter, `tap.harmony~` the + formant-preserving chord stack, and `tap.pitchaccum~` the spiral; + `tap.tune~` always measures first and that measurement is latency you + don't need. ## Checkpoint diff --git a/book/src/vocoder.md b/book/src/vocoder.md index 8fcf510..5ba40c0 100644 --- a/book/src/vocoder.md +++ b/book/src/vocoder.md @@ -95,7 +95,9 @@ either input. Linear, boring, necessary. - **High-fidelity cross-synthesis.** Twenty-four bands is a *voice*, not a spectrograph; for surgical spectral morphing you want FFT-domain tools (`tap.spectra~` is the start of that corridor). -- **Formant preservation while shifting** — related, but a different machine. +- **Formant preservation while shifting** — related, but a different machine: + `tap.harmony~`, which multiplies the voice itself instead of wearing it + over a carrier. ## Checkpoint From a2921ba48eb8cea2b742e8323e5be0df2b0eb6e3 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 5 Aug 2026 11:29:53 +0000 Subject: [PATCH 11/12] Add the virtual-analog ADSR kernel; keep the Jamoma curves as modes taptools/adsr.h (tap::tools::adsr::generator) rebuilds the envelope as a circuit model, per the recipes-improvements plan: the default analog mode charges its attack toward a 1.4x overshoot target and truncates at full scale (the CEM 3310 architecture from the datasheet; standard Electronotes ADSR practice), and its decay/release are true RC discharges that taper into their targets. Contract numbers documented and pinned: attack reaches full scale at the knob time with the truncated-charge midpoint at 0.652; decay/release close 95 percent of their gap at the knob time (tau = t/3); release ends at exact zero below 1e-6. Retrigger always rises from the current level. The 2003 Jamoma TTAdsr curves are ported verbatim as hybrid/linear/exponential compatibility modes, magic constants and all. The family trigger contract lands at last: the gate opens above a threshold (default 0.005 - above the trigger bus's 1e-3 floor, below the sequencer's 0.01 plain level, retiring the old hard-coded 0.5 that a default accented row could never open), and gate amplitude is velocity under a sensitivity control (1 + s*(amp - 1), so 303-style 2.0 accents hit twice as hard at full sensitivity; s = 0 is the legacy amplitude-blind behavior). Eight Catch2 scenarios pin all of the above, including the legacy hybrid curve's linear attack and dB-linear decay. The C ABI, ctypes bridge (Adsr class), and the executed notebooks/adsr.ipynb ship alongside per the verification-layer rule - the notebook measures 99.8 ms to full scale on the 100 ms knob, midpoint 0.652 on the law's 0.652, 95.0 percent decay closure, and the plain-hit threshold test. Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01V6CC6kpK5Lx2YkJWuNNQpw --- README.md | 1 + include/taptools/adsr.h | 356 +++++++++++++++++++++++++++++++++++ notebooks/adsr.ipynb | 259 +++++++++++++++++++++++++ notebooks/taptools_py.py | 60 ++++++ tests/CMakeLists.txt | 1 + tests/adsr_test.cpp | 189 +++++++++++++++++++ tools/capi/taptools_capi.cpp | 60 ++++++ tools/capi/taptools_capi.h | 17 ++ 8 files changed, 943 insertions(+) create mode 100644 include/taptools/adsr.h create mode 100644 notebooks/adsr.ipynb create mode 100644 tests/adsr_test.cpp diff --git a/README.md b/README.md index 5e21782..a569985 100644 --- a/README.md +++ b/README.md @@ -32,6 +32,7 @@ header adds no nested namespace, the class) the kernel lives in. | `autowah.h` | `tap.autowah~` | Snow White-style envelope filter (`tap::tools::autowah`) | | `overdrive.h` | `tap.overdrive~` | LGW-voiced feedback overdrive (`tap::tools::od`) | | `vca.h` | `tap.vca~` | Voltage-controlled amplifier (`tap::tools::vca`) | +| `adsr.h` | `tap.adsr~` | Virtual-analog ADSR envelope, legacy Jamoma curves as modes (`tap::tools::adsr`) | **Voices, drums, and sequencing** diff --git a/include/taptools/adsr.h b/include/taptools/adsr.h new file mode 100644 index 0000000..2ce17e7 --- /dev/null +++ b/include/taptools/adsr.h @@ -0,0 +1,356 @@ +/// @file +/// @brief Portable virtual-analog ADSR envelope kernel — no Max/Min dependency. +/// @details The envelope behind tap.adsr~, rebuilt as a circuit model. The default `analog` +/// mode is the classic analog EG shape from the published sources (the CEM 3310 +/// datasheet's architecture; standard Electronotes ADSR practice): the attack stage +/// is an RC charge toward an asymptote *above* full scale — the 3310 charges toward +/// its +7 V rail and a comparator ends the stage at the +5 V peak, a 1.4× overshoot +/// target, which is where the perceived punch of an analog attack lives — and the +/// decay and release stages are true RC discharges that approach their targets +/// asymptotically instead of stopping dead. Retrigger always rises from the current +/// level, like the capacitor it models. +/// +/// The three curves of the 2003 Jamoma TTAdsr are preserved verbatim as the +/// `hybrid` / `linear` / `exponential` compatibility modes (straight lines in +/// amplitude or in dB, hard stops, the −120 dB floor) — a faithful port, magic +/// constants and all. +/// +/// Trigger contract (the family's, at last): `process(gate)` opens above a +/// `threshold` (default 0.005 — above the trigger bus's 1e-3 edge floor, below the +/// sequencer's 0.01 plain level, and far below the old hard-coded 0.5), and the +/// gate's amplitude is velocity: with `velocity` sensitivity s, peak and sustain +/// scale by 1 + s·(amp − 1), so the 303 convention (1.0 plain / 2.0 accented) and +/// the 808 rows' amplitudes land meaningfully. s = 0 (the default) is exactly the +/// legacy amplitude-blind behavior. The captured amplitude is the maximum gate +/// level seen during the attack stage. +/// +/// Contract numbers, pinned by the test battery: the analog attack reaches full +/// scale at exactly the attack time (the truncated-charge law τ = t_a / ln(T/(T−1)), +/// T = 1.4, so the midpoint sits near 0.65, not 0.5); analog decay and release +/// close 95 % of their gap at the knob time (τ = t/3) and keep closing +/// asymptotically. Honest limit: an asymptotic release never *reaches* zero, so the +/// stage ends (exactly zero, state inactive) once the level falls below 1e-6. +/// @author Timothy Place +// SPDX-License-Identifier: MIT +// Copyright 2003-2026 Timothy Place. + +#pragma once + +#include +#include + +namespace tap::tools { + namespace adsr { + + constexpr double k_attack_target = 1.4; // CEM 3310: +7 V asymptote, +5 V comparator peak + constexpr double k_noise_floor_db = -120.0; // Jamoma TTAdsr's dB basement (legacy modes) + constexpr double k_default_threshold = 0.005; // above the 1e-3 trigger floor, below seq plain 0.01 + constexpr double k_min_time_ms = 1.0; // legacy clamp, kept + constexpr double k_max_time_ms = 60000.0; + constexpr double k_end_level = 1e-6; // release ends (exact zero) below this + constexpr double k_settle_fraction = 0.95; // decay/release close this much at the knob time + + enum class mode : int { analog = 0, hybrid, linear, exponential }; + + /// Virtual-analog ADSR generator. House shape: prepare(sr), per-sample process(gate), + /// allocation-free setters safe while audio runs. Output is 0..1 at unity velocity + /// (up to 2 with full velocity sensitivity and an accented 2.0 gate). + class generator { + public: + void prepare(double sr) { + m_sr = sr; + update_coeffs(); + } + + bool prepared() const { return m_sr > 0.0; } + + void set_attack_ms(double ms) { + m_attack_ms = std::clamp(ms, k_min_time_ms, k_max_time_ms); + update_coeffs(); + } + void set_decay_ms(double ms) { + m_decay_ms = std::clamp(ms, k_min_time_ms, k_max_time_ms); + update_coeffs(); + } + /// Sustain level in decibels (unclamped, the legacy contract). + void set_sustain_db(double db) { + m_sustain_db = db; + m_sustain_amp = std::pow(10.0, db * 0.05); + } + void set_release_ms(double ms) { + m_release_ms = std::clamp(ms, k_min_time_ms, k_max_time_ms); + update_coeffs(); + } + void set_mode(mode m) { m_mode = m; } + void set_mode(int m) { m_mode = static_cast(std::clamp(m, 0, 3)); } + /// Gate-open threshold (0..1). The default hears the sequencer's plain level. + void set_threshold(double t) { m_threshold = std::clamp(t, 0.0, 1.0); } + /// Velocity sensitivity, 0..1: peak and sustain scale by 1 + s·(gate amp − 1). + void set_velocity(double s) { m_velocity = std::clamp(s, 0.0, 1.0); } + + double attack_ms() const { return m_attack_ms; } + double decay_ms() const { return m_decay_ms; } + double sustain_db() const { return m_sustain_db; } + double release_ms() const { return m_release_ms; } + mode curve() const { return m_mode; } + double threshold() const { return m_threshold; } + double velocity() const { return m_velocity; } + bool active() const { return m_state != state::inactive; } + + /// Reset to silence and idle; parameters keep their values. + void clear() { + m_state = state::inactive; + m_output = 0.0; + m_output_db = k_noise_floor_db; + m_amp = 1.0; + } + + /// Consume one gate sample (amplitude-as-velocity above `threshold`); produce the + /// envelope sample. Returns 0 before prepare(). + double process(double gate) { + if (!prepared()) { + return 0.0; + } + + const bool open = gate > m_threshold; + if (open) { + if (m_state == state::inactive || m_state == state::release) { + m_state = state::attack; + m_amp = std::max(0.0, gate); + } + else if (m_state == state::attack) { + m_amp = std::max(m_amp, gate); // velocity = max gate level during attack + } + } + else { + if (m_state != state::inactive && m_state != state::release) { + m_state = state::release; + } + } + + switch (m_mode) { + case mode::analog: + process_analog(); + break; + case mode::linear: + process_linear(); + break; + case mode::exponential: + process_exponential(); + break; + case mode::hybrid: + default: + process_hybrid(); + break; + } + return m_output; + } + + private: + enum class state : int { inactive = 0, attack, decay, sustain, release }; + + // ---- the analog model -------------------------------------------------------- + + /// Peak scale for the current gate amplitude: 1 + s·(amp − 1), floored at 0. + double scale() const { return std::max(0.0, 1.0 + m_velocity * (m_amp - 1.0)); } + + void process_analog() { + const double sc = scale(); + switch (m_state) { + case state::attack: + // RC charge toward the overshoot target, truncated at the peak. + m_output += m_attack_coeff * (k_attack_target * sc - m_output); + if (m_output >= sc) { + m_output = sc; + m_state = state::decay; + } + break; + case state::decay: + case state::sustain: + // True RC toward sustain — asymptotic, never a hard stop. + m_output += m_decay_coeff * (m_sustain_amp * sc - m_output); + break; + case state::release: + m_output += m_release_coeff * (0.0 - m_output); + if (m_output < k_end_level) { + m_output = 0.0; + m_state = state::inactive; + } + break; + case state::inactive: + default: + break; + } + } + + // ---- the Jamoma TTAdsr curves, ported faithfully ----------------------------- + + static double db_to_amp(double db) { return std::pow(10.0, db * 0.05); } + static double amp_to_db(double amp) { return (amp <= 0.0) ? k_noise_floor_db : 20.0 * std::log10(amp); } + + void process_linear() { + switch (m_state) { + case state::attack: + m_output += m_attack_step; + if (m_output >= 1.0) { + m_output = 1.0; + m_state = state::decay; + } + break; + case state::decay: + m_output -= m_decay_step; + if (m_output <= m_sustain_amp) { + m_state = state::sustain; + m_output = m_sustain_amp; + } + break; + case state::sustain: + break; + case state::release: + m_output -= m_release_step; + if (m_output <= 0.0) { + m_state = state::inactive; + m_output = 0.0; + } + break; + case state::inactive: + default: + break; + } + } + + void process_exponential() { + switch (m_state) { + case state::attack: + m_output_db += m_attack_step_db; + if (m_output_db >= 0.0) { + m_state = state::decay; + m_output = 1.0; + } + else { + m_output = db_to_amp(m_output_db); + } + break; + case state::decay: + m_output_db -= m_decay_step_db; + m_output = db_to_amp(m_output_db); + if (m_output <= m_sustain_amp) { + m_state = state::sustain; + m_output = m_sustain_amp; + } + break; + case state::sustain: + break; + case state::release: + m_output_db -= m_release_step_db; + if (m_output_db <= k_noise_floor_db) { + m_state = state::inactive; + m_output = 0.0; + } + else { + m_output = db_to_amp(m_output_db); + } + break; + case state::inactive: + default: + break; + } + } + + void process_hybrid() { + switch (m_state) { + case state::attack: + m_output += m_attack_step; + if (m_output >= 1.0) { + m_output = 1.0; + m_output_db = 0.0; + m_state = state::decay; + } + else { + m_output_db = amp_to_db(m_output); + } + break; + case state::decay: + m_output_db -= m_decay_step_db; + m_output = db_to_amp(m_output_db); + if (m_output <= m_sustain_amp) { + m_state = state::sustain; + m_output = m_sustain_amp; + } + break; + case state::sustain: + break; + case state::release: + m_output_db -= m_release_step_db; + if (m_output_db <= k_noise_floor_db) { + m_state = state::inactive; + m_output = 0.0; + } + else { + m_output = db_to_amp(m_output_db); + } + break; + case state::inactive: + default: + break; + } + } + + // ---- geometry ---------------------------------------------------------------- + + void update_coeffs() { + if (!prepared()) { + return; + } + const double attack_samples = std::max(1.0, m_attack_ms * 0.001 * m_sr); + const double decay_samples = std::max(1.0, m_decay_ms * 0.001 * m_sr); + const double release_samples = std::max(1.0, m_release_ms * 0.001 * m_sr); + + // Analog: attack knob = time to reach the peak on the truncated charge + // (tau = t / ln(T / (T - 1))); decay/release knobs = time to close 95 % + // of the gap (tau = t / 3). + const double attack_tau = attack_samples / std::log(k_attack_target / (k_attack_target - 1.0)); + const double settle_logs = -std::log(1.0 - k_settle_fraction); // 3 for 95 % + m_attack_coeff = 1.0 - std::exp(-1.0 / attack_tau); + m_decay_coeff = 1.0 - std::exp(-settle_logs / decay_samples); + m_release_coeff = 1.0 - std::exp(-settle_logs / release_samples); + + // Legacy: straight-line steps, exactly the TTAdsr math. + m_attack_step = 1.0 / attack_samples; + m_decay_step = 1.0 / decay_samples; + m_release_step = 1.0 / release_samples; + m_attack_step_db = -(k_noise_floor_db / attack_samples); + m_decay_step_db = -(k_noise_floor_db / decay_samples); + m_release_step_db = -(k_noise_floor_db / release_samples); + } + + double m_sr = 0.0; + + double m_attack_ms = 50.0; + double m_decay_ms = 100.0; + double m_sustain_db = -6.0; + double m_sustain_amp = 0.5011872336272722; // -6 dB, the legacy default + double m_release_ms = 500.0; + mode m_mode = mode::analog; + double m_threshold = k_default_threshold; + double m_velocity = 0.0; + + double m_attack_coeff = 0.0; + double m_decay_coeff = 0.0; + double m_release_coeff = 0.0; + + double m_attack_step = 0.0; + double m_decay_step = 0.0; + double m_release_step = 0.0; + double m_attack_step_db = 0.0; + double m_decay_step_db = 0.0; + double m_release_step_db = 0.0; + + double m_output = 0.0; + double m_output_db = k_noise_floor_db; + double m_amp = 1.0; + state m_state = state::inactive; + }; + + } // namespace adsr +} // namespace tap::tools diff --git a/notebooks/adsr.ipynb b/notebooks/adsr.ipynb new file mode 100644 index 0000000..b8742c4 --- /dev/null +++ b/notebooks/adsr.ipynb @@ -0,0 +1,259 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "id": "367a410d", + "metadata": {}, + "source": [ + "# tap.adsr~ — the envelope, measured\n", + "\n", + "The rebuilt envelope kernel (`taptools/adsr.h`): the default `analog` mode is a circuit\n", + "model — an RC attack charging toward a 1.4× overshoot target and truncated at full scale\n", + "(the CEM 3310 architecture), with decay and release as true RC discharges that taper into\n", + "their targets — while the 2003 Jamoma curves survive verbatim as the `hybrid` / `linear` /\n", + "`exponential` compatibility modes. Every trace below drives the **shipping C++** through\n", + "`tools/capi` via ctypes.\n", + "\n", + "Sections: **1** analog vs. the legacy curves · **2** the contract numbers ·\n", + "**3** gate amplitude is velocity." + ] + }, + { + "cell_type": "code", + "execution_count": 1, + "id": "6423d298", + "metadata": { + "execution": { + "iopub.execute_input": "2026-08-05T11:28:58.446923Z", + "iopub.status.busy": "2026-08-05T11:28:58.446701Z", + "iopub.status.idle": "2026-08-05T11:29:01.142472Z", + "shell.execute_reply": "2026-08-05T11:29:01.140867Z" + } + }, + "outputs": [], + "source": [ + "import numpy as np\n", + "import matplotlib.pyplot as plt\n", + "\n", + "import taptools_py as tap\n", + "\n", + "plt.rcParams.update({\n", + " \"figure.dpi\": 96, \"figure.figsize\": (9, 3.2),\n", + " \"axes.grid\": True, \"grid.alpha\": 0.3,\n", + "})\n", + "C = tap.PALETTE\n", + "sr = 48000.0\n", + "\n", + "def gate_square(on_s, off_s, level=1.0):\n", + " return np.concatenate([np.full(int(on_s * sr), level), np.zeros(int(off_s * sr))])" + ] + }, + { + "cell_type": "markdown", + "id": "fc94d8fa", + "metadata": {}, + "source": [ + "## 1 · The shape of the circuit\n", + "\n", + "One gate, four modes: attack 100 ms, decay 300 ms, sustain −12 dB, release 400 ms. The\n", + "analog attack is convex — fast off the mark, easing into the peak, the truncated charge —\n", + "where the legacy hybrid/linear attacks are straight lines. And the analog decay *tapers\n", + "into* sustain asymptotically while the legacy curves hit it and stop dead: the difference\n", + "between a capacitor and a ramp." + ] + }, + { + "cell_type": "code", + "execution_count": 2, + "id": "00cf8541", + "metadata": { + "execution": { + "iopub.execute_input": "2026-08-05T11:29:01.146590Z", + "iopub.status.busy": "2026-08-05T11:29:01.146012Z", + "iopub.status.idle": "2026-08-05T11:29:01.832417Z", + "shell.execute_reply": "2026-08-05T11:29:01.830751Z" + } + }, + "outputs": [ + { + "data": { + "image/png": "iVBORw0KGgoAAAANSUhEUgAAAuEAAAFbCAYAAAB7+VAcAAAAOnRFWHRTb2Z0d2FyZQBNYXRwbG90bGliIHZlcnNpb24zLjExLjEsIGh0dHBzOi8vbWF0cGxvdGxpYi5vcmcvctoD+AAAAAlwSFlzAAAOxAAADsQBlSsOGwAAqShJREFUeJzs3XecU1XawPHfTZveeweGjoCiKCoiIhYsKL6uDTsuspZd3aJrWRVdsa5d17Iq9l4QUIoC0kHpvQ7Te++Tct4/QgJhCpkhmcwwz9ePH8jNOec+Ockdnjk59xxNKaUQQgghhBBCdBqdrwMQQgghhBCip5EkXAghhBBCiE4mSbgQQgghhBCdTJJwIYQQQgghOpkk4UIIIYQQQnQyScKFEEIIIYToZJKECyGEEEII0ckkCRdCCCGEEKKTSRIuhA/ce++9nH766R2q+9tvv/GXv/yFtLQ0oqOjqaqqarFcWVkZd9xxB+np6fTu3Ztbb72VgoKCDpfztPHjx/OnP/3J6+fxBrPZzMcff8yFF15Ir169GD58OLfffjv79+9vVrarvw9dzaOPPsqwYcN8GoM711hxcTFPPfUUY8aMIS0tjTPPPJNnn32WxsbGDp/3yGvihRdeIDo62vl/fHw8I0aM4O9//zvFxcUdPo83DBs2jEcffdTXYRyzvLw85/u+bt26Zs+vWrWKCy+8kOTkZE488UReeOEFbDZbh8uJnk2ScNFj/fOf/2TEiBFuH/ek6upqysvL213vp59+4o477qB3795ccskllJaWtviDvampiXHjxrF+/Xq+/fZb5syZw/79+xkzZgw1NTXtLucNFRUVVFdXe/Uc3vLqq6+yYsUK/v73v7N06VJef/11tm3bxogRI8jIyHCW6w7vg6cd6/VTW1tLWVmZByNqH3evsQsuuID33nuPu+++m2XLlnHffffx8ssvc95553U42Trymqirq6O0tJSlS5eyc+dONmzYwFNPPcU333zDhRdeiNls7vDr9LSysjJqa2t9HcYxu+OOO6iurqa0tLRZ/65du5ZzzjmHYcOGsXLlSp588kmeeOIJ/v73v3eonBAoIXqoO++8U6Wlpbl93JOmTJmiBgwY0O56VqvV+fdHH31UAaq8vLxZuTfffFNpmqb27NnjPJaTk6MMBoN65pln2l3OG04++WQ1efJkr57DW2w2W7Nj+/fvV4B6/PHHnce6w/vgacd6/dTW1qqysjLPBdRO7l5j9957r6qqqnI59tVXXylA/fjjjx0695HXxBNPPKEAlZ+f71Luf//7nwLUunXrOnQeb0hKSlJ/+9vffB3GMfnss89USEiIeuaZZxSgVq1a5fL82LFj1ciRI12Ovfzyy0qv16v9+/e3u5wQMhIujjtvvPGGy9e3I0eO5MEHH6SystJZ5u677+bdd98lOzvbWfass85q9bi77Trs2rWLm2++mX79+tG3b19uvvlmsrOz24z7s88+Iy4ujtdee63VMjqde5fst99+y7Bhw+jbt6/zWFJSEqeffjrffvttu8sdq9mzZ3P66aeTkpLCFVdcQVZWVovldu3axY033kh6ejopKSlceeWV7Ny5s8VybfWvO+/VRx99RGxsLDk5Oc3av+iii7jssstafT2apjU7FhoaCri+R13pfcjLy+P2229nyJAh9OnTh4kTJ7JixQrn85MnT+b//u//mtU755xzuPvuu91qxxPXzzPPPMPZZ5/tfOyYulVWVsYNN9xAamoqJ598Mt9//71H+uVI7l5jL7zwAiEhIS7HhgwZAsDevXuPWt/da6IlgYGBADQ0NLhdpy2OPi4qKuL6668nLS2Np556yvn8V199xbhx40hOTmbQoEE8+OCD1NfXH7Vdd+qNHz/e+bno1asX48aN4/PPP2/W1uLFi7nwwgvp3bs3w4cP5+6776aoqKjd52tNaWkpf/7zn5k+fTqJiYktPr906VKuuOIKl+NXXnklVquVWbNmtaucEICMhIvjT11dnSouLlbFxcUqLy9PLVy4UA0bNkxdcMEFzjLV1dVqypQpKiUlxVm2vLy81ePutquUUr///rsKDg5WF110kVqxYoXau3ev+uCDD9RNN93kLHPkSPgLL7ygDAaD+u9//+v262xrlC4hIUFdffXVzY7/8Y9/VIGBge0udyx++eUXpdPp1N/+9je1a9cutXDhQjVhwgQ1bNgwl1G/DRs2qJCQEPV///d/at26dWrHjh3q1ltvVREREerAgQPOcu70rzvvVWVlpQoKClJPPPGES7y7d+9WgJo5c6bbr7GiokLdfPPNKiYmRmVnZzuPd6X34eSTT1bjxo1Tv//+u8rMzFRz585VZ511lmpoaFBKKXXxxRerc889t1m94cOHu/RtW+144vr529/+ppKSkpyPp0yZovr166euueYaNXfuXLV37151xx13KL1er/bu3euRvmlNW9dYS9544w0FqO+++67Ncu5eEy2NhGdlZamRI0eqfv36qcbGxo68rGYcfXz55ZeruXPnqoKCAlVbW6uUUurJJ59Ufn5+6j//+Y/as2ePWrJkiRo4cKC66KKLXNo4ciTc3XoVFRXOz8W+ffvUm2++qfz9/dV7773nLLN161ZlMpnUY489pvbt26e2b9+u3njjDTVt2rR2n6811113nRo2bJgym83qo48+ajYS/uuvv7b63oaEhKhbb721XeWEUEopScJFj7B8+XIFqH379jmPeWI6SkvtnnHGGWrQoEEuX2sr5TqFwZGE22w2dd999yk/Pz/19ddft+s1tZUgGI1Gdfvttzc7ft999ylA1dfXt6tcS7799lsVFRWl5s+f32acp512mho3bpzLsWXLlinAJeEYM2aMGjp0qLJYLM5jVqtVDRw4UE2dOtV5zJ3+bUlL79WUKVNU7969Xered999Kjw8XNXV1bXZnlJKjR49WkVERChApaamqo0bN7o831Xeh9LS0qMmh+4k4e60c6zXT0tJOKB++eUX57HGxkYVERGhHnroIbfO01HtScKLi4tVfHy8SktLc/5i0xp3rwlHEh4ZGamioqJUWFiYAtSgQYPc+gXE3WvU0cfz5s1zOZ6VlaUMBoPLFCullFq3bp0C1KJFi5zHDk/C21OvJXfddZfLdI7XX39d+fn5NSvnuG6P9Xxz5sxRmqapFStWKKVUi0n4N998owC1ePHiZvVTU1PVZZdd1q5yQigl01HEcaipqYlXX32Vs846y3mX+6WXXgrAvn37vNpueXk5q1at4rrrrmv2tfaRUxgsFgs33XQTb731FvPmzWtxKkBHKaVanDLhiMlx45i75VrS2NhIaWkpTU1NrZZpaGhg7dq1zaZ2jB49mujoaOfjyspKli1bxpVXXoler3eJY9y4cSxZsgRwv3/d/QzcfvvtZGRksGjRIsD+nnz44Ydcf/31BAQEtPq6HGbPns327dtZunQp6enpnHfeeWzfvt35fFd5H8LCwoiOjuaZZ55h2bJlWK3Wo742T7dzLNdlcHAw48aNcz42mUwMGDCgxdVofMFsNnPNNddQUlLCBx98gJ+fX6tl3b0mDrds2TJ27tzJ7t27Wb16NUlJSZx//vnk5eW1GZc7nw0Hf39/zj//fJdj8+bNw2KxcPXVV7scHzFiBJGRkc7r8kjtqZeVlcVdd93FiBEjiI+PJzo6mvfee8/lM5Genk5jYyN//etfXd5zxzXT0TgBqqqqmDZtGrfccgtnnHFGq+WUUi7nPJxOp3O5lt0pJwTI6ijiOHTPPfcwffp07rrrLpYsWcKOHTuYM2cOwDEtH+ZOu0VFRSilSE5OPmp7eXl5fPrpp1x22WWMHTu2w3G1JDw8vMVl1SorKzGZTM45pe6Wa8kVV1xBcXExF1xwQatlcnNzUUoRHx/f7LnDjxUUFKCU4rnnnnNZki06Opr333+fkpISwP3+dfczMHLkSE466STeffddAObOnUtBQQFTp05ts32H8PBw4uPjOeuss5g1axYWi4XHHnvM5fmu8D7o9Xq+++47GhsbGTNmDJGRkVxxxRUsX77crdfpiXaO5bpMSEhodiwsLOyoKwx9/fXXzT5PLf3v7vvdEqUUt9xyC4sWLeK9995zmc/eEnevicNFRkYSHR1NbGwsp512Gp999hkZGRk899xzbZ7Lnc+GQ0JCQrPE0ZHkn3HGGc36rLKy0nldHsndepWVlZx99tns2LGDl19+mfXr17Nz507+9Kc/uXwmLrjgAp566ik+/vhj0tPT6dOnD/fee69zTnhH4wR46qmnqKur45lnnmmzf8LDwwFavU4jIiLaVU4IAIOvAxDCk2w2Gx988AGPPPKIy6jIhg0bOqVdxw/YI28YaklqaiqPPvooN9xwA9HR0fznP/85phgPN2jQoBZHF/fu3cvAgQPbXa4lJpOp1ZE7h7i4OMB+s9KRDv+HMSwsDICHHnqI2267rVlZx4iwO/3b3s/A1KlTueeeeygrK+N///sfp512GkOHDm3zdbUkJCSEAQMGsHv3buexrvI+gH2kdf369eTk5LBo0SLefPNNxo4dy+rVqznllFMIDg5ucWnAwsLCdrXTkmO9Llu7WdIx6tiaSy+91K1fcNsauT6av//973zyySe8/PLL3HDDDUct7+410Zbo6GhiYmLYtGlTm+Xc/Ww4yh7JcV2uXLmSyMjIZs+39m2Ru/UWL17MgQMHWLJkCWlpac7nW/oc/vOf/+S+++5j48aNzJ8/nxdffJF58+axbdu2DscJkJ+fT01Njct15vgF4MILL6RPnz6sX7+eQYMGAc2/tSkrK6O8vNxZ391yQoCMhIvjTENDA/X19c7RCIeWVpgICAhocZ3dlo67225sbCxDhgzhhx9+cCvea6+9lk8++YRXXnmFv/71r27VccdFF13E+vXrXZLVyspKVqxYwUUXXdTuch0VHBzMgAEDnNM9HLZv3+6yEU18fDxDhgxh6dKlLY5UOv5hdad/2/MZAPuqIEajkeeee46ffvqpw6OijY2N7N27l969ezuPdZX34XDJycnceOONzJs3D6vVytKlSwFIS0tj3759Ll+X79ixo1kSfrR2juX68TQ/Pz+3RsKPXOXEXc888wwvvPAC06dP589//rNbddy9JtpSV1dHWVlZiwmnJ5177rkArF69usV+CwoKOqZ6jm8yDv9cNDY28uOPP7bYrk6nY8SIETzwwAM8+eST7Ny5k4KCgg7HCfDaa6+Rm5vLzp07nf87vmH44osv+OWXXwBITExk+PDh/PTTTy71HbE6rlN3ywkByOoo4vgzatQodeKJJ6qCggLV1NSk3n//fXXhhRcqQM2ePdtZ7q233lIGg8HlprC2jrvb7ty5c5VOp1P33HOPKi0tVVarVa1du9blJrIjV0f58ssvlcFgUH/5y1/cfp1t3TRWXl6uEhMT1aRJk1R1dbWqq6tTkydPVlFRUS4rLbhb7lh8/PHHSq/Xq/fee0+ZzWaVnZ2tJk2apPr37+9yE9r8+fOVXq9X9913nyotLVVKKVVUVKTeeecdl7Wy3elfd98rh9tuu01pmqZCQ0NVTU3NUV/TtGnT1OLFi50rSBw4cEBdeeWVymQyOW/uUqrrvA/btm1T06ZNU1u2bFEWi0VZrVb1v//9T2mappYvX66Usq9OA6jnn39eWa1WdeDAAXX11Verfv36OW/MdKedY71+Wroxs6U19S+44IJmK6t4WlvX2MyZMxWg7r333na36+410dLqKBUVFerWW29Vmqapn376qUOv60ht7Vtw2223qaioKPXtt9+qxsZGZbVa1c6dO9W9996rVq9e7Sx35Ooo7tTbs2ePMhqN6h//+Icym82qtLRUXXvtteqcc85RQUFBzrZee+019eqrrzr7oaKiQk2aNEmlpaU5b850N053tHRjplJKzZo1S2mapt59911n/GlpaeqKK67oUDkhJAkXx53du3erM888U+n1ehUcHKxuuukmtXnz5mb/2NfW1qrx48crg8GgIiMj1ejRo9s87m67Sik1b948dfLJJytN01RwcLAaNWqUS3LW0j9633zzjTIajerPf/5zq6+ttLRURUVFqaioKBUQEOCycsLhy3UppdSOHTvU2WefrUwmkzKZTOq0005T69evb9amu+WOxbPPPqsiIiKUyWRSAwYMUGvWrGlxs54lS5aos846S+n1ehUYGKji4uLU1KlTm21wcbT+bc97pZRSa9euVUCzPmzN8uXL1aWXXqrCwsJUQECAioiIUBMnTmxx85Su8D40NTWpt956Sw0fPlwFBgYqf39/NWjQIPXJJ5+4lHvhhRdUaGio8vPzU8OHD1fbtm1zWR3FnXaO9frxdRLu7jWWnJzs8tzh/8+YMeOo53HnmjhydZSIiAjl7++vTj311A5vCNSStpJwq9WqnnvuOdW7d2+l1+tVUFCQGjRokHrxxRddVu05Mgl3t96nn36qEhMTlclkUvHx8erdd99VTzzxhEsSnpOTo+655x6VkJCggoKCVEBAgJowYYLasWNHu8/njtaScKWU+vDDD1VqaqoKDAxUAQEBasqUKaq6urrD5UTPpil1lEl1QnRTjY2NGAwG9Ho9NpuNsrIywsLCMBqNLuWampqorq5Gr9e7fC3a2nF323WU1TSt2XzLmpoaLBZLs6/nKysrMZvNREZGtjgPVinV4lxSsK9uEBwc3GIMSin8/f1brNfech2llKKurs751XBlZSV6vb7FmC0WC42NjW1+jeyIuaX+Pfx5d96refPmMWHCBDZs2MCJJ57YrtdVV1fX5o2Th8fSFd6HpqYmNE1r8fMK9vnb9fX1zr6vqKjAYDA0e5+O1k5Hr5+6ujoaGxud8/9bu1YcN745NknyFHevsfLy8lZXhwkMDHTrM3G0a6K+vt5lK3idTkdERESLK28ci9b6+Eh1dXUYjcYW3/Py8nL8/PxafN1t1XOora119kN9fT11dXVERUW12NbR+tad87WlsbGR6upqwsPDMRhavnWupqaGwMDAo27u5G450TNJEi6E6NHq6uo455xzCA0NZeHChb4ORwghRA8hv5oJIXqs8ePHExkZSV1dHW+99ZavwxFCCNGDyEi4EKLHqqysRKfTdXh1DCGEEKKjJAkXQgghhBCik8l0FCGEEEIIITqZJOFCCCGEEEJ0sh6xbb3NZqOiogJ/f3+PL+0khBBCCCGEg1KKhoYGwsPD21yeskck4RUVFS2uNyqEEEIIIYQ3lJaWEhkZ2erzPSIJd2x6UVpaSkBAQKeeWylFYWEhcXFxMgrvYdK33iN96z3St94jfes90rfeI33rPb7q2/r6eqKioo666VqPSMIdHR8QEOCTJNxxXrm4PEv61nukb71H+tZ7pG+9R/rWe6RvvcfXfXu0c8qNmUIIIYQQQnQyScKFEEIIIYToZJKECyGEEEII0cl6xJxwIYQQQhz/lFJYrVasVquvQ3GbUgqLxUJjY6PMCfcwb/at0Whsc/lBd0gSLoQQQohuz2w2k5+fT21tra9DaTer1Up1dbWvwzgueatvdTodKSkpBAYGdrgNnyXhX3/9Na+99prz8eeff058fHybdVatWsXrr79OSUkJp59+On//+98JCgrydqhCCCGE6MKUUmRkZKDX60lOTsZoNHabUWXHaK3BYOg2MXcX3upbpRQlJSVkZ2fTr1+/Do+I+ywJHzVqFNHR0WRlZXHTTTfR0NDQZvnffvuNc845h/vuu4/LL7+cZ599lpUrVzJ//vxOilgIIYQQXVFTUxNWq5WUlJROX4r4WCml0Ov1koR7gTf7Njo6murqasxmM35+fh1qw2dJeHJyMsnJyezcudOt8k8//TSXX345jz/+OACnnnoqvXr1YvXq1YwaNcqboQohhBCiGzjWObpCuMsTSX23mRO+cuVK/v3vfzsfp6amMmDAAFauXNksCTebzVgsFufj+vp6wP4bkVKqcwI+yHHOzj5vR6zcuprVBeu4ZsRVJEbG+Dqco+pOfdvdSN96j/St90jfek9X71tHXF05xrYcHr/wLG/1bVufOXfP1W2S8OLiYmJiXBPDmJgYiouLm5V98sknmT59erPjhYWFPtkxs6KiAvDMb03etKJsFdlB6fxv8wJuHzTe1+EcVXfq2+5G+tZ7pG+9R/rWe7p631osFqxWKxaLBb1e7+tw2sWxogt4tm+vu+46xowZw7Rp0zzWZnfjrb6FQ5+5kpISDAbXdNox+Hs03SYJ9/Pza/ai6urqWpyH89BDD3H//fc7H9fX1xMVFUVcXJxPknCAuLi4LvmDy6Gs0kyNLhSAEr8QbCGBJASG+DiqtnWXvu2OpG+9R/rWe6Rvvaer921jYyPV1dUYDIZmCVF3YTQaPdpedXU1DQ0N3bY/PMnTfQv2VVf0ej3R0dHNctHjLgnv168fu3fvdj62WCxkZGTQr1+/ZmWNRmOLHa5pmk9+eDjO2xV/cDksWV9ElV+48/GcrB1MHXSa7wJyU3fo2+5K+tZ7pG+9R/rWe7py3zpi6qrxtUUp5RK/J3XH/vAkb/et488j23b3XF32DoZPP/2Ua665xvn46quv5v3336esrAyA999/H7PZzIQJE3wV4nFly76tWDUjvcy7MTQ0sqW8gP1Vpb4OSwghhBDiuOSzJHzjxo2MHTuWG2+8EYBrrrmGsWPHsn37dgCysrJYvXq1s/xf//pXhgwZQnp6OkOHDuXvf/87M2fOJDIy0ifxH0+Ky5toUNkAJJkzicvOBOD7zO1yk4gQQgjhBX/605+Ijo4mNjaWU089lf/85z/YbDbn85dddhlPPfUU119/Penp6Zx22mksWrSoWf2YmBhGjBjRrP6R6uvrue+++xg6dCiDBg3izjvvpKqqyvl8dXU1U6dOpW/fvpx55pl8+eWXREdHk5GR4Z0OEL6bjtKrVy8ee+yxZseTk5MB+w0FY8eOdR738/Nj9uzZ7Nmzh9LSUoYMGUJISNees9xdLN1QSXBkHbVAnDWHunIdhfXDyKCMLeUFDItM8HWIQgghRLtd9/B2autbT0w9KShAx6f/Hux2+eeee44nnngCq9XK1q1bmTZtGtHR0dx8880AVFZW8txzz/Huu+8yY8YM3n//fa6++mpycnLw8/Nz1rfZbOzYsYPbbruNqKgoZ/0j/fGPf2Tnzp3MnDkTPz8/7rrrLv7whz8491uZMmUKRUVFfP/995jNZqZNm0ZpaanzxkbheT5LwsPDw12S7COlpqaSmpra7Hi/fv1anAcuOm7JugrihtnvJo+35FJoiKVwfSRRZ+YxO3M7QyLi0GtdduaSEEII0e0EBwcTHByMUooxY8bwz3/+ky+//NIlib799tuZNGkSAA8++CCPP/44GRkZDBw40FkfIDY2lgceeKBZfYfKyko++eQT1qxZw8knnwzAu+++S9++fdmzZw/R0dF89dVXbNu2jcGD7b9IvPzyy5x++une7YQertvcmCm8o7Csie0ZdQSPCkWnrMRYC4gNs1K43chJ50aSVV/G2qJsTo9L83WoQgghRLu0Z2S6sy1fvpwZM2awc+dOqquraWxsJC3N9d/apKQk598di07U1NS4Xd8hM9M+zdSRYAOkp6fj5+fHgQMHqKurA6B///7O5wcOHOiZFypaJcObPdzSDZWEBlVSow8j2lqAAQuxYWZAI77GPjXox+ydNFktbTckhBBCCLc0NDRw4YUXcv7557NgwQI2bdrEjBkzMJvN7a6/cOFCtm/fzlNPPdVq/fj4eACys7Odx4qKimhsbCQhIcH5fG5urvP5nJycjr484SZJwnu4JesqSI63X2jxmv2364gg+0V8YLfGiKgkKpoaWJK/32cxCiGEEMeT6upqamtrGTlyJOnp6dTV1fHee+8dU/1333231fKxsbGMGzeOf/7zn1RXV1NfX89f//pXTjzxRAYPHkxcXBxjxozhwQcfpL6+npqaGh566CFPvFTRBknCe7CC0iZ2HqgjMbkSgER/+2LzIX6NGPQaG/fUcnHqQHSaxs+5e6g1N/kyXCGEEOK4EBMTw7///W/OP/98QkNDGT9+PKed5v7eHIfXDwkJ4eyzz2bUqFFt1vnwww+xWq3Ex8cTFRVFXl4eX3/9NTqdPRX84IMPyMzMJDw8nD59+jBs2DDAOxvdCDuZE96DrdhkT76Do+13jieHJkE+aLZ6BvYKYOu+OuorDIyO68XSggwW5O5mUq8TfBmyEEIIcVx46KGHeOCBB6ipqSEgIACbzeay0+KsWbOa7cSYm5tLWFiYS/3a2lpCQkJoampyzu0G+PLLL10S6KSkJObMmYPVasVmszVLrnv16sXy5ctpbGzEz8+P33//naeffto5VUV4noyE92COJLzGZL8Qk2PsCbay1jG8n/2O6427a7gweQB+Oj1L8zMoa6hruTEhhBBCtItOp3Mut2wymQgPD3c+FxYWhr+/v0v5qKgol23o26ofGhpKQEBAs3Pq9foWR7cXLFjA/PnzMRgMFBUVcd9993HJJZc0+0VAeI4k4T1UVa2FLftqiQ6DYl04AbY6IsIPLv1orefE/vYkfMPuGkJMfoxL6otF2ZibvdOHUQshhBDCG0466SReffVVIiIi6NWrF+Hh4bz99tu+Duu4JtNReqg1W6uw2eDsEZXs0PxIpgCdTg/6AJSljhPSgzAZNTbuqsFqU4xLTGd5wQF+K85mXGI6SUFhvn4JQgghhPCQmJgY5syZQ1NTEwaDwTlXXHiP9HAPtWKzfavalJQiABJMGgCaPhBlrcNk1DE0PYjqOit7surx1xu5MHkACvghc4evwhZCCCGEF5lMJknAO4n0cg/UZLbx2/ZqAvx0WIz2eeGOkW3NEAjWepSycfIg+zyzdTurATgzLo0Y/yC2VxSyp7LEN8ELIYQQQhwHJAnvgTbsqqGh0cbIwSEUNNmXHUwKP7jLlj7Q/qe1gRED7fPC1+2wJ+F6nY5LUgcBMCtzG0qpzg1cCCGEEOI4IUl4D7Ris330+4xhYRRYA9CUjaSoIYB9OgrYV0hJTwogPNjAtv111DdaATgxKpHUoHAyayrYVJbvmxcghBBCCNHNSRLew9hsilWbq9Dp4MT+Vsp0EUSqCvz97FNPNL19OSNlrUen0zhpYDAWq2LL3loAdJrGxF6DAfghcztWm803L0QIIYQQohuTJLyH2Z1VT1mVhWF9g6ms2wVAgr7hUAHDwekoFvt64Cc7pqTsrHEWGRAWw6DwWIoballVlNk5gQshhBDHkfr6esxms8/qt6ampkamm3YSScJ7mLXb7auinDYkhJyKbAASD9sM4PDpKAAjBh68OfPgvHCHiWmD0YAfs3fRaLV4O2whhBDiuDJhwgTeeuutTq3f0NDQZuLe0NBASEgI+/bt63Bcwn2ShPcwa7fZk+lTh4SSV2efG54YEut8/sgkPC7SRHKsHxl5DZRVHrpwk4PCOCUmmWpzI4vz5GIVQgghurprr72W//73v74OQxwkSXgPUlljYeeBOmIjjKQl+JFnXxiF5Mh+hwo5pqNY652HTh5kn5KyftehKSkAF6cMwqDp+CVvL9XmRq/GLoQQQohj89133/HnP//Z12GIgyQJ70HW7ahGKRg5JASlFAWEYVINRIenO8s4R8IPzgkHOHmg63rhDlH+gYyO70WD1cL8nN2d8AqEEEKI44/VanV53NTURENDQ7NydXV1WCzNp4DaWlgk4fA541arFYvF0up0lJbqC++TJLwHcU5FGRxKWdV+GrUA4qlEr9M7yxxaHeVQEn5i/2D0Ovh9ezU2m+vNGhck98dfb2B5QQYlDbWd8CqEEEKI48OuXbs466yziIyMJD4+nk8//RSA2bNn07dvX5fkPCcnh7CwMPbs2eM8tmPHDk477TQCAwPp3bs3s2bNcj43YcIE7r33Xs444wwiIyP54IMPuPzyy3n55ZedZfLz87nwwgsJDAwkOTmZ119/vRNetXAw+DoA0TlsNsVv26sx6DVGDAxmd+5KABKMR9wB7dys51ASHhSg54T0IDbtqWVvTj39UwOdzwUb/Rif1I85WTuYm7WTm/qf7PXXIoQQQrijcuFIsFQfvaAnGEIIO++3dlX59ttvmT17NieccAIff/wxU6dO5fLLL+eyyy7jL3/5C7Nnz+byyy8H4J133mHUqFEMGjTIWf+jjz5i7ty5nH766Xz22WdcddVV7Nixgz59+gDwxRdfMHfuXE499VQAvvrqK5fz33zzzQQEBFBYWIjFYuG66647hg4Q7SUj4T3Enux6KmosnJAeRKC/ntzqAgASA0NdymmGgyPhh01HATjtBHs5x2j64cYm9CHU6MfvJTlk11R4IXohhBDi+DN16lROOukkNE3jxhtvpKGhgf3792MwGPjjH//Im2++Cdink7z77rtMnTrVpf7NN9/MWWedhcFg4IYbbuDUU0/lyy+/dD4/ZcoUZwJ+pOLiYhYsWMALL7xAWFgYUVFRPPvss957saIZGQnvIQ6timKf3513cK5ZcliyS7lDq6PUuxw/bUgob3+Xz5qtVVw/Ic7lOT+9gYtSBvL5/k38kLWdOwef4ZXXIIQQQrRHe0emO1tUVJTz73q9HoPB4JwLPnXqVGbMmEFGRgYbN26ktraWK6+80qV+Wlpas8d5eXnOx8nJrv/GH85RLjU1tdX2hHfJSHgPsXabfX1wRxKeb/EDIDl6iGvBFqajAKQl+BEbaWTHgToqa5rfFDIqLpXYgGB2VhSzs6LIw9ELIYQQPUtCQgITJ07krbfe4s033+T6668nICDApczu3bubPU5JSXGrfUe5w+eYH9me8C5JwnuAmjorOw/UERNupFeCP43mGkq0CMJtFQQGRLqUbW06iqZpnDYkFKXg9x3Np6ToNR0TU+3z1H7I3I5NdtsSQgghjskdd9zBW2+9xcKFC/njH//Y7PmPPvqIb775hoKCAl544QW2bt3q9rzuyMhIJk2axF133cWePXvYsWMH9957r6dfgmiDJOE9wMbdNdgUjBgYjKZp5JVsR2k6EnT1zcoeuVnP4Ryj6Gu2VrV4nmGRCfQKjiC7tpINpbkefAVCCCHE8SUgIACTyeRyLDg4GL3+0Ipl55xzDvHx8YwcOZJhw4Y1q/+3v/2NDz74gBEjRvDll18yb948kpKSWm3/yGPvvfceSUlJjB07lsmTJ/OnP/2JoKAgdDpJDzuDzAnvATbsso9cnzTAnkTnVGQCJhL8jc0LtzIdxV4/GKNB47ft1VhtCr1Oc3le0zQuSxvMy9tWMCdzB8MjEzHIhSyEEEI089NPPwGgDvvmuKSkxKWM1WqlqqqKv//9763WP1r7h/vuu+9cHoeHh/Phhx+6HLv++uvbDlx4jGRIPYBjp8uTBth3vsyrLQcgKTi6WVnN0HyzHocAPz3D+wVRVWtlV2bz5wH6hkVzQkQcJY11rCg84InwhRBCiB6ntraWN954g6amJlk68DglSfhxrqTCTFZBI6nxfkSH20e+85vsO2MlR6Q3K9/a6igOpw6xL1W4Zmvr665emjoYDZiXvYt6S/OduYQQQgjRtmHDhvHCCy/w/vvvN7shUxwfJAk/zm04OAo+4uAouM1mI98WikE1ERvZv3mFgztmtjQdBQ6tF97avHCAxKBQTotNpcbSxKK8fccQvRBCCNEz7du3j4yMDC655BJfhyK8RJLw49z6I+aDV9bmUqcLIk5VYNCbmpXXDEFAy9NRAJJj/UiKMbEnu57i8qZWz3tRykAMmo5FeXupamo41pchhBBCCHFckST8OKaUYsPOGnQanNjfPhKeU7ITgASjtcU6ms4EOhPKUtNqu2cODwNg5ebWR8Mj/AI4O6EPTTYr83J2dfQlCCGEEEIclyQJP47lFDVRXGGmX2oAwYH2JY9yq/IBSAwIbrWeZghqMwk/Y5h9SsrKzZVtnv+8pH4E6I2sKMykqL719oQQQgghehpJwo9jjqUJRwwMcR7Lq68FICksqdV6miEYrHUoZWvx+cF9gggPNrBhVw01dS2PqAMEGU2cn9wPm1LMydrRkZcghBBCCHFckiT8OLb+iJsyAfIt9hVSkqMGtl5RHwQoaGWFFL1O4/RhoVhtsHZb61NSAMbE9yHc5M+G0jwOVJe37wUIIYQQQhynJAk/Timl2LS7BqNBY0gf+82WZksDxVoEIbYqQoMTWq2rGexJuztTUla0MS8cwKTXc3GKPeH/IXO7y6YEQgghRE+VmZlJaWmpr8MQPiRJ+HEqs6CRqlorA3sF4meyv80FZTuxagbidbVt1j20Qkrr5U4eGIK/ScfabVU0mVuetuJwamwqCQEh7KkqYUdFUTtfiRBCCHH8uf3223n//fedjyUp73kkCT9ObdljH8Ue1jfIeSynfD8AiSZ9m3UPJeGtj4T7mXSMHBxCXYONjbvbvulSp2lcmjYYgFmZ27HJaLgQQgjh4qmnnmL27Nm+DkN0IoMvT26xWFiyZAklJSWMHDmS9PTmOzgerra2lhUrVlBZWcnAgQMZOnRoJ0Xa/Wzeax/FHtb30HzwvJoyIIak4Mi2Kx+cjkIbSTjYp6Qs21jJys1Vzp00W3NCRBx9QiLZX13G78U5nBqbctTXIIQQQvQUb775Jpqm+ToM0Yl8NhJeWVnJaaedxp133snHH3/MiSeeyOuvv95q+c2bN9O7d2/+9a9/8dVXX3H22Wdz8803d17A3YhSis17a9HpYHCfQOfxvEYLAMkRfdqs75wT3squmQ6nnRCKTmdfqtBma3t0W9M0Lu81BIA5WTsw21pfVUUIIYToaY6cjpKRkUFZWRkA2dnZ1NS0PDBWU1NDdnZ2s3uucnJy2Lp1K9u2baOqqvn9W4e3n5OTQ3m5LJ7Q2XyWhD/11FOYzWY2bdrEnDlz+Pjjj/nrX/9Kfn5+i+WfeeYZRo0axZo1a/jyyy9ZuXIlH3zwARs2bOjkyLu+/NImSirM9EsJIND/0NSTfFsQOmUlPmpQm/U1vT1xb2s6CkBYsIFhfYMprbSw40DbCTtA75BIhkUmUN5Uz7KCA0d/IUIIIUQPMW3aNJc54rfccgt33303ffv25eyzzyYqKornn3/e+XxBQQGXXHIJSUlJjB49mpSUFBYtWuR8/vXXX+eaa67hD3/4A0lJSVx66aVUV1e7tH/XXXfRu3dvxo8fz8KFCzvnhQonn01HmTVrFrfeeiv+/v4ATJw4kYiICH766SduvfXWZuWtVisJCYdW9IiPj0fTNFltowVbWpiKUlVbQLUulDhbCUaDf5v13VkdxWHMSWFs3F3Dr+srnKuwtOXS1EFsKctnfs4uTo9NJcBgPGodIYQQoiMeXbeAeoulU84VYDAw/eTzPdrmunXrWL58OfHx8SxYsIBLLrmEqVOnEhoays0330xsbCxFRUX4+fnxzTffcM0117B3715CQ0N56qmneOqppwD7dN4rrriCF154gUcffdTZ/sqVK1m+fDnJyckejVu4x2dJeEZGBr1793Y+1jSNtLQ0MjIyWiz/yCOP8Ic//IEHHniA1NRUPv/8c+68805GjBjRrKzZbMZy2EVXX29f71op1elJu+OcnXnezQdvyjwhPdB53pwS+2Y5CYamo8fiuDHTXHPUsqOHh/Lql7ksXV/J7ZMS0Onans8WFxDM6bFprCzK5OfcPVyS2vaofFt80bc9hfSt90jfeo/0rfd09b51xOXrGNt77sPjdvx5eBs33ngjcXFxKKUYP348SikyMjJITExk/vz5/Pjjj+zevRuA/v37YzKZWLNmDePHjwfs+VB+fj7V1dWcc845LFiwoFn7SUlJXfZ99YQj+9gb7R7Ztrvn8lkSbrVaMRhcT280GrFaW54rbLVaiYqKYsWKFezbt4+ioiJCQkKw2WzodK6zap588kmmT5/erI3CwkICAgI89yLcoJSioqICoNNuuNiwyz73Ky60jsLCBgD2F+0HoonS6SksLGyzvr7WihGoriyk4ihlAQamGtmRaWbF+hz6p5iOWv4U/0jWatksytvHAH0woYaj12mJL/q2p5C+9R7pW++RvvWert63FosFq9WKxWJBrz80DfPhYed0ehzuUkphs9kwm81YrVZsNhs2m83ZhlKKoKAglzb1ej319fXk5OQA8Pe//92lzbCwMKqrq7FYLLz00kvMmDGD4OBgQkJCqK2tJTAw0KX9qKiodsXc3SilnHmlpz+3js9cSUlJs3zWMfh7ND5LwuPj4ykoKHA5lp+fT3x8fIvlr732Wi6//HL+/e9/A1BRUUH//v0ZPHgw119/vUvZhx56iPvvv9/5uL6+nqioKOLi4nyShAPExcV1yg+u0kozhWWF9Er0p2/vQ9N3SjPNAPSJ6UVcXFybbZitidRlQJA/BBylLMB5owzsyMxlywE9Z51y9PJxwDhrDQty97CuoYxr0ocftU5LOrtvexLpW++RvvUe6Vvv6ep929jYSHV1NQaDoVlC1FVpmoZOp8NotE/L1Ol06HQ6Z/yO5498PXq9ngEDBmAwGPjoo4846aSTnM/ZbDaUUlRVVXH//fezdu1aTj75ZABee+01Xn/99aO2fzxy9LEnWa1W9Ho90dHR+Pn5uTzX5ZPwc845hx9++IFp06YBsG3bNvbv38/YsWMB2LJlC7t27eLKK68EoLi4mKSkJGf9sLAwQkNDKSkpada20WhsscM1TfPJDw/HeTvj3Fv32W+QHNY3yOV8+RY9aJASNfCocWhGxxKFtW7FfNZJYbz2ZS5LN1Typ/9LPOqUFIDxSf1YXniAVUWZnJOYTnxgyFHrtBhrJ/ZtTyN96z3St94jfes9XblvHTF11fhac3jcjj8Pj7+l16NpGoGBgTz44INcd911TJ8+nT59+rBz505efvll5s2bh7+/P/7+/ixcuBBN09i6dSszZswgLCzsqO0fT5RSzfrYU9r6zLl7Lp8l4Q8//DCnnnoqN954I8OHD+e///0vN9xwA8OGDQNg7ty5vPnmm84k/LbbbuOhhx6isLCQuLg4fvrpJ8rLy5k0aZKvXkKXtHlv8016rDYLhYQTaKslLPjoN19o+qPvmHm4yFAjw/oFs3F3Ddsz6jgh/eg3aAYYjFyQPIDvDmxldtYO/jjwVLfOJYQQQhwPevXqRXR0tPNxWlqay+PevXsTFRXlUmfIkCHOb/SnT5/OkCFD+Oyzz8jLy2PQoEG89957zjZ++OEHnn/+eb7++muGDh3KU089xbfffttm+6Jz+SwJ79+/P+vXr+fdd99lz549PPzww9xwww3O54cOHepMwME+z/uss85i0aJFbN68mdGjR/P222+3On2lp9q6z544n3DYyiiFZbuwaCZStbJm8+dbcmidcPeScICxI+yrpCxZV+FWEg5wVnwvfs3fx+ayfDKqy+gdcpRNhIQQQojjxJtvvgkcmupz5GY9hy9X6LBu3TqXx1dddRVXXXVVi+2PHz/eeYOmw+H7q7TUvuhcPp0I1KdPH5588skWn7v44ou5+OKLXY5deOGFXHjhhZ0RWrdU12AlI7eB2EgjMeGHpuPklu8DIMHk5lcxbu6YebjRJ4Xxyhe5LN1QwR1XujclxajTc3HKID7au57vD2zjnhNGH9dfiwkhhBBCOPhssx7hebsy67EpGNwr0OV4bnUxAElB4W61oxkcm/W4PxIeEWLkxP72jXu27ne/3ikxySQFhrK/uoyt5UdfiUUIIYQQ4nggSfhxZHuGPfkdfMSmOXmN9pVRksLT3GqnPZv1HO7sk8MBWPRbhdt1dJrGxLTBAPyQuR3bcbxWqRBCCCGEgyThx5Ht++0rowzu7ToSXmANQFM2kiIHu9eQzg80Q7tGwgHOHhGG0aCxZF0FZovN7XqDwmPpFxpNQX01a4uy2nVOIYQQQojuSJLw44RSih0HajEaNPqmHFoLva6+jHJdOFGqHD8/95YB1DQNzRDc7iQ8JNDAqBNCqa6zsnZbtdv1NE3jsoOj4XOzd9LUyoZNQgghhBDHC0nCjxO5xU1U1ljpnxqA0XDobc0p2Q5AgqGxfQ0aAsFy9G3rjzT+1AgAFq4tb1e9tJAITopKpKKpgaUF+9tVVwghhBCiu5Ek/Dix/eDNkIN7u84Hz63MBiDR379d7dnnhdvA6t6uTw6nDgkhJFDP6i1V1NS1b0T7ktRB6DSNBTl7qDU3tauuEEIIIUR3Ikn4cWJ7xsH54H1c54Pn1VUBkBRy9O3kD3dorfC6dtUzGXWcPSIcs0Xx64aKdtWNDQjmzLg06q1mFubuaVddIYQQQojuRJLw44RzZZQjRsLzzPZ1t5Mi+7ervUO7ZrZvhRSA8aeGA/DzmvZNSQG4MHkAJp2eX/P3U97YvlF4IYQQQviGzWZj9uzZ2GzuL8zQWWw2G99//z21te7f67Z48WIqKiq8FxSShB8XDt+kJ/qwTXqsNiuFhOGnGogO69OuNjVDx5PwIX2CiI8ysXlvLYWl7ZtWEmryZ1xiXyzKxtysHe0+txBCCCHaZ9WqVezdu/eY2vjkk0/43//+59bO3J2tqamJSZMmkZ+f73adpUuX8thjj3kvKHy8Y6bwjF2ZdfZNeo4YBS+p2Eej5k+aKmj/RdGBXTMddDqN8aeG8/FPRfz8WzmTL2zfVJhzk9JZXpDB2uJsxiX2JTEotN0xCCGEED3RypUriYuLIz093e06CxcuZPjw4fTt27dD51RK8cQTT/DOO+90qP6OHTvYtWuX8/Gll16KXq93KVNVVcWGDRvw9/dn+PDh+LfzXrfD/f777+Tk5ACg1+tJTEzkxBNPdDnnXXfdRVpaGg899BAxMTEdPldbut6vK6LdWlsfPKfMPq86wdisylEdGglv3zKFDo5VUuavKmv3Civ+eiMXpgxAAbOztnfo/EIIIURP9MgjjzB79ux217nssss6fM6lS5dSV1fHmDFjOlR/w4YNzJw5kxdeeIFJkyZRX+86HfXRRx9l0KBBPProo9x6662kp6ezcuXKDsf7/PPP8+c//5mZM2fy9ttvc+WVVzJ48GBnYg4QFRXFmDFj+Oijjzp8nqORJPw4sDPTnoQPOiIJz6suAujQSLJmsK8p3pHpKAApcf6ckB5EbnETm/e0P5E/M64X0X6BbC0vZG9lSYdiEEIIIbqybdu2sXDhQnJzc12OL1q0iLy8POdjq9XK999/T11dXZt1N23aRHFxMVu2bOH777/nl19+AWDdunV8//33zJo1i/Xr12M2m13Od+R0lOXLl5ORkUFZWRmLFy9my5Ytbb6OefPmceaZZ6JpWvs7Abjuuuv4/vvvmTFjRovPx8fHs3fvXpYsWcK2bdu4+OKLmTZtWpttVlZWsmTJEnbs2NHiYOC4ceP4/vvvmT17Nnv27CEgIIAXXnjBpcyYMWOYN29eh16TOyQJPw7syqxDr4P0pACX43kNDQAkh6W2u03NeDAJN1d1OK4JZ0QC8NPKsnbXNeh0XJI2CIBZmdvbPZouhBBCdFVKKS677DLOO+88XnjhBcaNG8e///1v5/N//vOfXUZ66+vrmTRpEkVFRS51//Of/3DWWWc5665atYr8/HzWrl3LzJkz+e677wBYtmwZM2fO5N133+Xaa6/llFNOobCw0Nn+9OnT+f77752PH374YW6//XZGjRrFU089xVlnncVdd93V6uvZtGkTgwYN8lT3NPOnP/2JgIBDOc6pp57qEv+Rli9fTp8+fbj//vu56aabuOqqq9ps32AwkJaWRlWVa84zePBgNm7ceEyxt3ler7UsOkVJhZnSSgt9k/3xM7n+TpVv9QcdJEW7uV39YTSDffRcWdzf+fJIZ48I4/Wvclm6oYK7rkoiOFB/9EqHOSkqiV+C9nKgppxNZfmcGJXY4ViEEEL0TNaDuzDr9XosFgs6nQ6dTofFYnHOAbZYLBgMBmd5g8GAzWbDZrNhMBjcasNmszWbx9yajIwM5syZQ2lpKWFhYZjNZubMmdPuuuHh4SilnAn0tGnT+Prrr7nkkku45557nHXuuece52OlFDfccAPPPvss//nPf1o9T1VVFZs3b8bf35+NGzcyYsQIpk+fTlRUVLOyJSUlhIeHuxzbsmUL+/bta7X9Pn36MGzYMLde8+HMZjPvvvtuq9NnbDYbU6ZM4Z577uHhhx/GYrHw4IMPMnfuXJdyWVlZfP/991itVjZv3syKFSualYmIiKC0tLTdMbpLRsK7ud1Z9q+m+qe5TkVpaKymTAsnwlZOoH9Eu9v1xEh4gJ+ecadE0GhWLPq9/csV6jSNy9KGADA7cztW1fWWPRJCCNG1LVu2jAULFgDw7bffsmHDBgDefPNNcnNzsdlszJgxA7PZTEFBAa+99hpgTyK/+uorwD49ZPHixQB88cUXbNu2DYBXX32VoqIiGhsbWbZsmdsxJSYmkpaWxjPPPMPGjRux2WxMmjTJq3VzcnJYtGgRP/zwA/Hx8fz2229tlv+///s/582PJ554IgaDgaysrBbLBgYGNpvH7RiNb+3/NWvWuPV6D2e1Wrn55ptpbGxs9ReI7Oxsdu/ezR133OE8dueddzYrt3fvXmbOnMmHH37I7NmzGTJkCMHBwS5l6urqCAwMbFbXU2QkvJvblWn/0A84IgnPLd2G0nQk6Dq21vahOeEdHwkH+5SUOctL+WllGRPHRLe7/oDwGAaGx7CzopjVhVmcGd/rmOIRQgjRs5x11lnOv19xxRXO1cKmTZvmHLl+8MEHMRgMxMfHO6ddDB06lCFD7ANB48aNc7Zx9dVXO9u4++67nW0cfp6j8ff3Z8OGDXz99de88sorrFy5ksmTJ/PII4+0WP7wKZmH13355ZdZtWoVkydP5l//+ler57vzzjv57LPPGD58OKGhoRQUFDSbenGkw6d/AOh0Ouc3AkdKT08nOzvb5diUKVOYMmVKm+doD7PZzOTJk8nMzOSXX34hJCSkxXI1NfZ72Q5PqI9MrsH+ns6cOdP5+OGHH+ayyy5zmRufnZ3drlVm2ktGwrs550h4quvFkluRCUCCn6lD7XpiJBxgQFoAfZL82Z1Vz97sjv1CMDHVPp3mx+ydNFotxxSPEEKInkWv1zsTZYPB4EygDQYDmqahaRpGo9H5d8e0FJ1O5/y7O224OxUF7FM9AgICmDJlCu+99x6//PILjz76qHP6RkREBEVFRc7ymzdvbrHu+++/z6+//sojjzzirGsymbBYDv1bWVRUxBtvvMH69etZvHgxs2bN4vLLL/fovVZjxozh999/91h7R2poaGDSpEkUFhby888/ExHR+jf8ffr0wd/fnxUrVjiPLV++/Kjn6N+/P5mZmS43ra5Zs6bDK764Q0bCuzGlFLsy6zAaNHonuq6XmVtbCfiTFBLbobY9MSccQNM0JpwRyetf5fHTylLuvjq53W2kBIdzSnQyv5fksCR/Pxckt2/3TyGEEKIryczMZPLkyUyePJm0tDQWLFhAbGwsCQkJAFx00UU8/fTT+Pn50djYyNtvv91i3V69erFw4UKXuoMHD+abb74hLS2NyMhIRo8eTXR0NDNmzODcc89l69atvP32220msu01adIk7rrrLrKzs0lJSWl3/by8PNauXcuOHfZN+ubMmYO/vz/nnXceQUFBXHLJJWzdupUXX3zRueILwMSJE5vtgxIQEMA//vEPbrzxRh588EGampr473//2+ycjjnhSilyc3N57rnnuPLKKzEa7es6W61W5syZw6xZs9r9etwlI+HdWFGZmcoaK+nJARgNR9yU2WT/DTc5soNfoxgPLmtoPrYkHOxrhhsNGgvXllPf2PJXWUdzcepA9JrGz7l7qDE3HnNMQgghhK8MHTqU7777joqKCmbNmkVcXBxr1qxxzj++7777uP/++1m8eDHZ2dl8/fXXXHbZZQQGBrrU/f7774mPj2ft2rXOug8//DDnnXceX331Fd999x1+fn78+uuvmEwmvv32W/z8/Pj4448ZP368M54zzjiDfv36OR+PHj2aPn1cd9qeOHFiq4l7aGgoU6ZM6fBmPZmZmc554pdddhmff/45M2fOpLranoOEhYUxatQovvjiC5d55a1Nj3n88ceZMWMGa9asITs7m1mzZnHZZZc5p6WMHDmS0NBQ55zwTZs2MX36dD744ANnG3PmzCE9PZ1TTz21Q6/JHZrqAWu/1dfXExgYSF1dXbM5Tt6mlKKwsJC4uLgOr5/Zml/XV/D4/zK57Owo/nzYCLPNZuOfK7/Aohl47vRJ6HXt/8LD1lRB1bxB6MNOIOTshccc69MfZLFwTTl/vS6Zi0c3v7PaHd9kbGFJ/n7GJvTh/3oP9Wrf9nTSt94jfes90rfe09X7trGxkf3799OnTx/8/Px8HU67KKWcq7N0xb51V0lJCffdd1+X2rr+WPp2+vTpTJgwodUkvK3PnLt5Z9foJdEhh+aDu96UWVGdRb0ukDgqOpSAA2gHt61XHhgJB7j8bPtNmd//WtLheWjnJ/fHX29gWUEGJQ0d28lTCCGEEJ4XHR3Ne++912US8GP16KOPenUUHCQJ79YcK6MMPGJllOzSXQAkGDo29QNA0xlAH4iyHNuNmQ4DewUyIDWA/bkNbN3XsQQ6xOjHuYl9sSrFj9k7PRKXEEIIIYQvSBLeTdlsit1ZdfibdKTEu34NkltdAEBiYMvL97hLM4aizDUeu4P6srH20fBZSzu+8P05iemEGP34vTiHnNpKj8QlhBBCCNHZJAnvpnKLm6itt9E3JQC9znWeU97BBfOTwpKO6RyaIQSUGWwNx9SOwzknhxMapGfp+gpKK81Hr9ACP72Bi1IGoIAfMrd7JC4hhBBCiM4mSXg35ZgPPiCt+YT/fIt9eZ3k6EHHdA7t4AopnpoXbjLqmHBGJFYbzF3R8dHw02PTiPUPYmdlMRn1MhouhBBCiO5HkvBuyrHxTb8U1/ngTeZ6SrQIQm1VhATGHdM5nDdnemheOMDEMdFoGsxZVorF2rFpLnqdjkvT7Bv4LCrNxnb8L/AjhBDCDTabzdchiB7CE1N1ZbOebmpvjiMJdx0Jzy/djk3TE68d++ohnh4JB4iPMnH60FBWbq5i6foKxo3s2GYBwyMTSAsOJ7Omgo2leZwc0/5NgIQQQhwfTCYTer2evLw8YmNjnTtgdgeOZfSsVmu3ibm78FbfKqUoKSlBp9M5N/fpCEnCuyGlFHuz6zEaNFLijrgpsyIDMJLod+xvrWbwzNb1R7pyXAwrN1fx5c/FnHNKeIcuDE3TmJg6mFe3r2RO1g5OjEpEf5wsiySEEKJ9NE2jd+/e5Ofnk5OT4+tw2s1qtbZr23vhPm/1rU6nIyUl5ZiWZJQkvBsqqTBTVWtlQGoAer1rAptbUw7EkhTcsQ1xDuccCT/GreuPNKxfEP1TA9idVc/G3bWcNCC4Q+30C4smPSCcffUVrCg8wJiEPkevJIQQ4rhkNBpJSUnBZrNhsVh8HY7bHKOq0dHRMhLuYd7sW6PReMxroksS3g3tzbGvVtI3pflNmXlN9rXBkyM6uF39YZwj4R5OwjVN4w/jY3jyvSy++qWow0k4wLioFPbnVDAvZzenxqbgr+/410JCCCG6N03T0Ov13WpUWSmFwWDAz89PknAP6+p9K9/fd0OOmzLTk5sn4QW2YPTKQnzkgGM+j2b0znQUgLNPCic20siardUcyO/4EoixpkBGxqRQbW5kUd4+D0YohBBCCOE9koR3Q/sO3pR55Eh4RXUuNboQYlU5BoNfS1Xbx+D5GzMd9HqN/zsnBoCvfyk+prYuShmAQdOxKHcvVU2eWdNcCCGEEMKbJAnvhvZm16Np0CfR3+V4bpl9K/cEg2fmwjlGwvHgEoWHm3BGJEH+On5eW05ZBzfvAYj0C2RMQm8abVbm5+z2YIRCCCGEEN4hSXg3U1NnJb+0iaQYPwL8Xee85VTmAZAYGOSRc2mOkXBLjUfaO1JQgJ6LR0dhtii+XVxyTG2dn9SfAL2B5YUHKK73TrxCCCGEEJ4iSXg3sz+35akoAHn19rXBk0ITPHIub84Jd/i/cTEYDRqzlpZQVdvxEfwgo4nzkvpjU4o5WTs9GKEQQgghhOdJEt7N7Dl4U2bfZP9mzxVY7CPjyVHHtl29w6F1wj0/J9whOtzIhDMiqWuw8d0xjoafndCHcJM/60tzyaop91CEQgghhBCed8xJeH5+Pnl5eZ6IRbihtZsyLdYmCokkyFZDeEiSR851aJ1w742EA1xzfiwGvca3i0uorbd2uB2TXs9FKQMBmJW53SNbygohhBBCeEOHk/AFCxbQq1cvEhMTefzxx9m3bx/nnXceNpvNk/GJIzi2qz9yecLCsp1YNQMJOs+NWmvGMACUudJjbbYkLtLE+aMiqKm3MuvXYxsNPzU2hfiAYHZXlrCz8thWXRFCCCGE8JYOJeEFBQVcd911PPvss7z00ksApKenExkZyTfffON2O6+88gq9evUiODiY8847jz179rRZfseOHUycOJHw8HAGDBjAl19+2ZHwuy2zxUZmfiORoQYiQ103pckp3w9AgslzGxRoOiPog1BNFR5rszXXXhCLTgdfLyqmvrHjo+F6TcelaYMB+CFzOzYZDRdCCCFEF9ShJHz58uWMHTuWq666Cj+/Q+tRn3LKKaxcudKtNr788ksefvhh3n77bfbu3UtqaioXXXQRZnPLS9VlZmZy5plnMnz4cLZu3covv/zC7NmzOxJ+t5WZ34jFqlrcpCe3xj6CnBQU4dFzaqYwlLkSpbz7DUditB/njoygssbK7GWlx9TW0Ih4+oREklNbybqSHA9FKIQQQgjhOR1Kwg0GA1Zr89HK8vJyYmNj3WrjzTff5Oabb+b8888nPj6eF198kezsbBYuXNhi+RkzZnDqqafyxBNPkJycTHJyMh999FFHwu+2MvIcU1Ga35SZ12BfWSQpopdHz6kZIwAbeGmZwsNNvjAWnQZfLCimvqHjo+GapnHZwdHwOVk7Mds63pYQQgghhDcYOlJp1KhR3HrrrSxbtsx57MCBA3zwwQd8//33brWxYcMGbr31Vufj0NBQBgwYwMaNG7noooualf/ll1+YOHEiZ599NuvXr6dPnz48+uijXHHFFc3Kms1mLJZDy93V19uTV6VUp9+s5zinJ867P9e+G2TvBP9m7RXYAtFpVhIiB3r0NTrmhduaytEdXC3FW5Jj/Rh/agQL1pTz9aJirp8Q12b5tvq2d0gkQyPi2VJewPKCA4xN6OOtsI9LnvzcClfSt94jfes90rfeI33rPb7qW3fP16EkPD4+nldffZUJEyag1+vRNI2ZM2fy0EMPMXLkSLfaqKqqIiwszOVYeHg4VVUtr8RRUlLC22+/zVdffcUZZ5zBd999x1VXXcXq1as55ZRTXMo++eSTTJ8+vVkbhYWFBAQ0n8rhTUopKioqAPsI7bHYdcB+g2SIXy2FhU3O4/VN5VTqwoixlVBeVgN4btTaaPNHD5QU7EcF+R21/LG66DQ9v/wGXywsYtRAGyGBrX9Zc7S+PT0ohq3lBfyUtZPe+OGv69DHvUfy5OdWuJK+9R7pW++RvvUe6Vvv8VXfOgZ/j6bDWcnkyZM599xzWbVqFXV1dYwcOZL+/fu7XT8kJITKStdVNyoqKggJaXm0NTg4mLPPPpsJEyYAcPPNN/Pf//6X2bNnN0vCH3roIe6//37n4/r6eqKiooiLi/NJEg4QFxd3zB+AvJIydDo4cXAiJuOh5HRX9i4AEg1NxMW1PXrcXnX5sZjLITJEjyHGs223JC4OLjlLMevXUhZvgj9e3vo5j9a3ccBpTZWsLspii7mKS1I9s356T+DJz61wJX3rPdK33iN96z3St97jq771ehIO9mkfSin0en2Lc8TbMnz4cNatW8f1118PQE1NDXv27GH48OEtlj/xxBObdWBrHWo0GjEajc2Oa5rmkw+447zHcu7qOgvFFWZS4/3wO2IFlNyqXCCIxIAAj78+ncl+o6eyVHZa311/YRzzV5Xz3ZISrjgnhujw5u+lw9H69uKUgawryWFx/n7GJPQhzNR8Pr1omSc+t6Jl0rfeI33rPdK33iN96z2+6Ft3z9XhdcKfe+45+vbty1/+8hceeughhg4dyh//+Ee358FMnTqV999/n6VLl1JZWcl9991HXFwc5513HgDPPvssffv2dZafNm0a3333HUuWLKGxsZHPP/+c9evXM3HixI6+hG7lQJ59PnifxBZuyqyzT+FJCon3+Hmda4V3wjKFDpFhRiadE02TWfHxT4XH1Fa4XwBjE9Ix26z8dPAbAyGEEEIIX+tQEr5161Yef/xxFi5cSHZ2Nvv27WPHjh0sXLiQzz//3K02Jk+ezAMPPMAf/vAHoqOj2bx5M3PnznUueWiz2Vxurrzkkkt48cUXuemmmwgJCeHf//43X3zxBSeffHJHXkK3k3EwCe+V2Hw6Tb7Z/jYmRw3w+Hk1Yzjg/Q17jnT1eTEEB+j5cUUp2YWNx9TW+KR+BBqMrCrMpLDec5sZCSGEEEJ0VIeS8E2bNnHxxRczZswY57F+/fpx++23s2HDBrfbuf/++yksLMRsNrN8+XIGDx7s8ty+fftcyk+dOpXMzEyamprYunUrkyZN6kj43ZIjCe99xEi41WalgHD8VR0RIWkeP69mCgdAmSs83nZbQgINTL4wFqsN3vo275jaCjQYOT+pPzYUczJ3eChCIYQQQoiO61AS3rdvX7Kzs5sdz8rKIj09/ZiDAvt8Gr3ec7s/dnetJeHF5Xswa37EU4VO1+HZRa06tHV9hcfbPprLx0aTGGNi1ZYq1u08thHsMQm9iTAFsLEsn4zqMg9FKIQQQgjRMR3K2nr16oXVamXy5MnMnTuXhQsXct999zFnzhwGDBjA6tWrWb16NRkZGZ6Ot0dSSnEgrwE/o0ZCtMnluZyyPQAkmrxzw4FzOkpT505HATAZdUy9PAGA/36dh9XW8XU+jTo9F6cOBGBW5nZZj1UIIYQQPtWh1VHmzJnD1q1b2bp1K7NmzXJ57pJLLnH+/bbbbuOll146pgAFlFRaqK6zMiA1AJ3ONdnOrS4GokgMCmu58jHy1XQUh9EnhjG8XxCb9tTy08oyLhkd1eG2RsaksChvH/uqStlWXsgJkZ6/kVUIIYQQwh0dGgmfMmUKNTU1R/1fEnDPOHBwu/reSc1XRslvtN+0mBye6pVz+3I6CtinJf3pykQ0Dd7/oYCa+o5vQa/TNCYe3M7+h6zt2GQ0XAghhBA+csyTiBsbG6mp8dwOjaK5DMd29S2tjGINQFM2kqIGN3vOEzRjKND5q6Mcrl9KIBeMiqCixsKHcwuOqa3B4bH0DY0iv66a34qb39cghBBCCNEZOpyEr1u3jlGjRhEYGEhISAj9+/dnzpw5noxNHJSR71ie0HUkvKGxkjJdBJGqAn8/L01H0fRoxjBsnbhOeEumXJZAUICO75aUsC/HvZ2oWqJpGpcdHA2fm7UTs63jI+tCCCGEEB3VoSS8oqKCSy65hJNOOokVK1awbt06brnlFq6++mq2bt3q6Rh7PMdI+JEb9eSUbAMgXt/g1fNrxjCwVKOU7xLWyFAjUyYmYLPBS5/lYDuGmzR7hURyYlQi5U31LM2Xm4eFEEII0fk6dGPm8uXL6devH//973+dx0aMGEF+fj6zZs3ihBNO8FiAPZ3VpsgsaCA0SE9EqOvblVuRBQSQ6O/n1RgOzQuvRDNFevVcbbnkrCjmrypje0YdP60s46IzOx7LpamD2Fyaz4Lc3Zwel0qgwXT0SkIIIYQQHtKhkfCamhri45uvLBEfHy/zwz2soKSJJrOiV4I/mnbEyih19nnaSSGxXo1BM0YAnbt1fUv0Oo17rktGp8E73+dTUW05eqVWxAYEc0ZcGnUWMwtz93gwSiGEEEKIo+tQEj5y5EjmzZvHL7/84jy2e/du3nrrLc444wyPBScgs8A+1SQtoYWVUZrsfyZH9vNqDJrp0Ei4r/VPDWTimCiq66y8/V3+MbV1YcoATDo9v+bvp7yx4/PMhRBCCCHaq0NJeHp6Oo899hgTJkwgOTmZ9PR0Bg8ezAUXXMCll17q6Rh7tKwC+xKEqfGuU05sNhsFhGFSjUSH9/VqDM4Ne8zlXj2Pu26ZmEBUmIEFa8rZtLexw+2Emfw5JzEds83Gj9k7PRihEEIIIUTbOrw6yl//+lf27NnDCy+8wPTp09m4cSNvv/22J2MTHBoJT413HQkvqzpAgxZAHBXodXqvxuCYB64au8Z278EBeu65NhmA/82pOqa1w89N7EuwwcSaoizy66o8FaIQQgghRJuOaZ3wtLQ0rrrqKq6//nq5GdNLHCPhaUeMhOeU7gYgwWjzegyOJNzW1DWScIAzhoUxfmQ4ZVU23vq249NSAgxGLkjpjwJmZ+7wXIBCCCGEEG1wa3WUvLw8du/e7VaDiYmJ9O/f/5iCEnZKKbIKGgj01xEdbnR5Lre6AIggKTDU63HoHCPhXSgJB7jjD4n8tr2Kn1aWMXZEOKcMDulQO2fG9WJJ3n62lBewr6qU9NAoD0cqhBBCCOHKrSR84cKF/O1vf3OrwZtvvpnnn3/+mIISdiWVFuoabAxIC2i2MkpeQz0QQVJYstfj0PzsSalqKvX6udojNMjArZeE8OIXlfznk2zeeXgAwQHtn5pj1Om5JHUQH+xZx6zM7dx7wuhm/S2EEEII4UluJeE33XQTN910k7djEUfIamU+OEC+xQ90kBTtne3qD6d10ZFwgFMG+DPuFI1Fv1fw6he5PHBzaofaGRGdxC95e8moLmNzWQHDoxI8HKkQQgghxCHHNCccID8/n7y8PE/EIo6QdXC7+iPngzeZaynRIgizVRAcEO31OHRdcE744e6+OpHYSCM/ry1n4ZqOreCiO2w7+9lZ27Eq78+1F0IIIUTP1eEkfMGCBfTq1YvExEQef/xx9u3bx3nnnYfNJsmLpxxantB1JDy3ZDtK05Gg65y1rTXTwekojV1rOopDSKCBB25ORafBK1/kkFfSsWULB4bHMiAshsL6GtYUZXs4SiGEEEKIQzqUhBcUFHDdddfx7LPP8tJLLwH2tcMjIyP55ptvPBlfj9ba8oS5FZkAJPq7NZvomGmGQND7d8npKA7D+gYzeUIcdQ02ZryXhcWqOtTOxIOj4T9m76TJ2vEdOYUQQggh2tKhJHz58uWMHTuWq666Cj+/Q1MlTjnlFFauXOmx4Hq6rMJGjAaNxGiTy/G8WnsynBgc02mxaKZIVFM5qgtP07hhQhyDewey40AdH8wp6FAbqcHhjIhOorKpgSX5+z0coRBCCCGEXYeScIPBgNXafIOU8vJyYmNjjzkoAdV1FsqrLCTF+KHXH7EySpM9EU6O6NNp8ehMUYANZa7otHO2l16v8dCtaQQF6Ph0fhGrtnRs851LUgeh1zR+zt1DrbnJw1EKIYQQQnQwCR81ahS//vory5Ytcx47cOAAH3zwAePHj/dYcD1ZVn7r29Xn20IxKDNxkQM6LZ6uvELK4eKjTPzzJvsKKU/PzOrQ/PAY/yBGx/Wi3mphfo576+MLIYQQQrRHh5Lw+Ph4Xn31VSZMmMD999/P559/zsCBA5k2bRojR470dIw90oFW5oNX1eZRpwsilnIMelNLVb2iq21d35YzhoVx7QWx1NRbeeztAzQ0tX8KzQXJA/DT6VlWkEFZQ50XohRCCCFET9bh1VEmT57M3r17mTlzJq+//jqbN2/mX//6lydj69Fa367evrV6gqH5dCBvOrRhT9dPwgFuuTSeEQOC2ZfTwMuf56BU+27UDDH5cW5SPyzKxtzsnV6KUgghhBA9VYeS8Pp6+9J48fHxTJo0icmTJ8tW9R7W2kY9OVX5ACQGBHVqPIfWCu+ayxQeSa+zzw+PCTeyYHU53y4uaXcb4xLTCTH68VtxNrm1lV6IUgghhBA9VYeS8A8++IChQ4fy4osvUlxc7OmYBJBd0IimQUqc60h4Xp19akRSWFKnxtNd5oQfLjzEwGNTe2Eyarz5TR5rtrbvRk0/vYELkweggB8yt3snSCGEEEL0SB1Kwq+55hpuv/12PvnkE5KSkrjiiiuYM2dOiyumiPZrMtsoKGsiLtKEn8n1Lcq32NcGT4ka1KkxOTfs6UZJOMDAXoH886ZUbAr+/V4m+3Pbt8HRmXFpxPgHsb2iiN2V8gunEEIIITyjQ0l4eHg4d911F7///jvr1q2jV69eTJkyhZSUFD766CNPx9jj5JU0oRQkx7reeGmxNFKsRRBsqyY0OKFTY3JOR+miu2a25ewR4dx6aTx1DTYe+m8GZVVmt+vqdTouTbX/wjMrc3u755YLIYQQQrSkwzdmOgwdOpSnnnqKF198EYvFwooVKzwRV4+WU2i/KTMp1nUqSkHZTqyagQRdTafH1F1Hwh2uuzCW806NoKjMzL/ePEB9g/vf2pwYlUhqcDhZNRVsLM33YpRCCCGE6CmOKQlft24dd911FwkJCTzwwANMmzaNBx54wFOx9Vg5RfYkPPmIJDyn3L6DY4JJ3+kxHVodpf03OHYFmqbx18nJDOsbxM4DdTz2zgHMFveWLtQ0jcsObmc/O2s7VlvX3TVUCCGEEN1Dh5LwlStXMnToUEaPHk1ZWRlffPEFGRkZPP7446SlpXk6xh6ntSQ8t8Y+FSQpOLLTY9JMkaDpsTV233nRJqOOJ6b1Jj3Zn9931PD0B9lYbe5NL+kfFsOg8FiKG2pZWZTp5UiFEEIIcbzrUBJeU1PDnXfeSUFBAZ9++innnXceOt0xz2wRBzmT8CNXRmm02I9H9O70mDRNh2aKRjUUd+t50cGBep6+sw+JMSaWrKvgtS9z3X49E9MGowE/Ze+i0WrxbqBCCCGEOK51KHM+//zzmTZtGmFhYZ6ORwC5RY0Y9Bpxka43ZhbYgtApK/GRnbsyioPOPwaUGWWu8Mn5PSUyzMgzd/chMtTAD0tLeXdWgVuJeHJQGKfEJFNtbmRx3r5OiFQIIYQQx6sOD18/99xzpKSkoNPp0DTN+f+0adM8GV+PU1tvpazKQmKMCb1Ocx6vriukShdKjCrHZAzwSWyaXywAqrHIJ+f3pMRoP56+qw8hgXo+W1DEez+4l4hfnDIIg6bj59w9VJsbOyFSIYQQQhyPDB2p9Ntvv/HEE0/w1ltvMWTIEJepKJGRnT9f+XiSW9zKTZklju3qmzo9JgfdwSTc1liCPmSAz+LwlPTkAJ77Sx/+8fJ+Pp1v/8Xi1onxaJrWap0o/0DOiu/N4vx9zM/ZzZW9h3ZWuEIIIYQ4jnQoCd+1axcTJ07k2muv9XQ8PZ5jecJmN2VW5gLBJAYE+iAqO80vGgDV0P1Hwh36pQS6JOIKmHKURPz85H6sKspkeUEGYxP6EO0f1HkBCyGEEOK40KHpKIMGDSInJ8fTsQhaXxklr64agKSQ+E6PyUHn7xgJP36ScDiUiIcE6vlsfhGvf5WHrY1VU4KNfpyX1A+rUszJ2tGJkQohhBDieNGhJDwlJQWLxcJ9993H0qVLWb16tfP/jIwMT8fYo7SWhOdb7GuDJ0cN7PSYHA7NCe++yxS2pl9KIM//JZ3wEAPfLSnh6Q+ysFhbT8THJvQh1OjHupJcsmsqOi9QIYQQQhwXOpSEz549m40bN/LGG29w0UUXMX78eOf/L7/8stvtZGZm8thjj3HXXXfxySefYHNzE5Q5c+Zw2223sW7duo6E36W1tDyh1WahkHACbHWEh6T4KjR0fjEA3Xqt8Lb0TQng5b/1JT7KxC+/VfCvNzNoaGr5M2nSG7go1f4L0Q+Z2zszTCGEEEIcBzqUhE+ZMoWampoW/3/ppZfcamPv3r2cdNJJ7N69m+TkZP71r38xZcqUo9bLy8vjnnvu4cMPPzzuRt2VUuQUNRLgpyMy9NB0/aLy3Zg1EwlalU/XY9cOJuHH05zwIyXH+vHy3/rSO9Gftduq+cfL+yivNrdYdlRsKrEBweysLGZnxfHbJ0IIIYTwvGPO6PLz88nLy2t3vX//+9+ceuqpfPrpp/zzn/9k1qxZzJw5k61bt7ZZ77bbbuORRx7BZDK1Wa47qqixUFtvIznWz+XGwJwy+5rUCabWbxbsDJpzTvjxORLuEB1u5MW/pnNCeiDbM+q469m9ZOTVNyun13RMTLWv2T4rczu2bryJkRBCCCE6V4dWRwFYsGABU6dOJTMzk9tvv51//OMfTJs2jfnz57s1Wrto0SIeeOAB5+OhQ4fSp08fFi9ezAknnNBinXfeeQdN07jxxhu54447Wm3bbDZjsRza0bC+3p5AKaU6fbdHxzndOW92gX0qSlKsyaV8bnUREE1iUJhvd6vUh4DOD9VY1CV2zWxP37ZXcICeZ+/uw/Mf57Do9wr+/PxeHrolldNOCHUpNzQinl7BERyoKWd9SQ4nRyd7PBZf8Gbf9nTSt94jfes90rfeI33rPb7qW3fP16EkvKCggOuuu4433niD/Px8duzYQXp6OpGRkXzzzTf84Q9/OGob+fn5JCQkuBxLSEggPz+/xfIHDhzg8ccfZ9WqVUdt+8knn2T69OnNjhcWFhIQ0Lkb3SilqKioAGhz2TuAHfvsvyxEBFooLCx0Hs+pawAdhGgRLsd9wc8QiWospLAgDzS9T2NpT9921K0TTEQGB/H1kloefvMA140PZsKoQJfznRUSz4GacmZlbCPBokev+W7KkKd0Rt/2VNK33iN96z3St94jfes9vupbx+Dv0XQoCV++fDljx47lqquu4s0333QeP+WUU1i5cqVbSbher3cZrQb7CLZe3zyxU0px66238sgjj5CcfPSRxoceeoj777/f+bi+vp6oqCji4uJ8koQDxMXFHfUDUNVg/wVkQJ9I4uIinMeL9gahKRuDeo/Czy/Ee8G6oSYwAWtTPjERRueNmr7Snr49FtP+AIPSK3j2w2w+WVhDTqmev01OJtDf/lmNI44NDWVsLS9kj6rn7Pg+Xouls3RW3/ZE0rfeI33rPdK33iN96z2+6luvJuEGgwGr1drseHl5ObGxsW610atXLw4cOOB8rJQiKyuLXr16NSv7+++/s2LFCvr06cOaNWsAaGxs5M0336SwsJA777zTpbzRaMRoNDZrR9M0n3zAHec92rlzi+y7YabE+TvL1jWUU66LINpWhr9/aFvVO4XmfzDxbix2zhH3JXf79liNPTmCpFg/pr+Tya/rK9mf28Bjf+xFr0R/AC5NHcy28kLm5+zmtNhUAgzNP3/dTWf1bU8kfes90rfeI33rPdK33uOLvnX3XB363nzUqFH8+uuvLFu2zHnswIEDfPDBB4wfP96tNiZOnMjHH39MY6N9HvScOXMoLS3lwgsvBOCnn37in//8J2BP2F9//XVGjRrl/F+v19OvXz8GDOj+26c7OLasT4w5dNNpbol9+bsEfYNPYjqSc+v6hgIfR9L5+qUE8uY/+3PGsFCyCxu589k9LFhdhlKKxKBQTotNpcbSxKK8vb4OVQghhBBdXIdGwuPj43n11VeZMGECer0eTdOYOXMmDz30ECNHjnSrjQcffJD58+dz0kknMWDAAH7++Weee+45kpKSANi0aROff/45Tz/9NDExMdx2220u9e+55x7OPfdct5P+rk4pRV5JE8EBekKDDr0tOZVZQCAJ/v6+C+4wugD7PP6e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", + "text/plain": [ + "
" + ] + }, + "metadata": {}, + "output_type": "display_data" + } + ], + "source": [ + "g = gate_square(0.6, 0.8)\n", + "t = np.arange(g.size) / sr\n", + "\n", + "fig, ax = plt.subplots(figsize=(9, 3.6))\n", + "for mode, color in [(\"analog\", C[0]), (\"hybrid\", C[1]), (\"linear\", C[3])]:\n", + " env = tap.Adsr(sr, attack=100, decay=300, sustain=-12, release=400, mode=mode)\n", + " ax.plot(t, env.process(g), color=color, lw=1.4, label=mode)\n", + "ax.axhline(10 ** (-12 / 20), color=\"gray\", lw=0.8, ls=\":\", label=\"sustain (−12 dB)\")\n", + "ax.set_xlabel(\"time (s)\")\n", + "ax.set_ylabel(\"envelope\")\n", + "ax.set_title(\"attack 100 · decay 300 · sustain −12 dB · release 400\")\n", + "ax.legend(loc=\"upper right\")\n", + "plt.show()" + ] + }, + { + "cell_type": "markdown", + "id": "69a932bc", + "metadata": {}, + "source": [ + "## 2 · The contract numbers\n", + "\n", + "The header's promises, measured: the analog attack reaches full scale at exactly the knob\n", + "time with its midpoint at 1.4·(1 − e^(−ln 3.5 / 2)) ≈ 0.652; decay and release close 95 %\n", + "of their gap at their knob times (τ = t/3); and the release genuinely ends at zero (the\n", + "asymptote is truncated below 1e-6). The same numbers are pinned CI-side in\n", + "`tests/adsr_test.cpp`." + ] + }, + { + "cell_type": "code", + "execution_count": 3, + "id": "eebcb92f", + "metadata": { + "execution": { + "iopub.execute_input": "2026-08-05T11:29:01.835746Z", + "iopub.status.busy": "2026-08-05T11:29:01.835447Z", + "iopub.status.idle": "2026-08-05T11:29:01.849271Z", + "shell.execute_reply": "2026-08-05T11:29:01.847185Z" + } + }, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "attack: reaches full scale at 99.8 ms (knob: 100.0); midpoint 0.652 (law: 0.652)\n", + "decay: 95.0 % of the gap closed at the 200 ms knob (contract: ≥95 %)\n", + "release: level 0.0126 at the 100 ms knob; final sample 0.0 (exactly zero — the stage ends)\n" + ] + } + ], + "source": [ + "env = tap.Adsr(sr, attack=100, decay=200, sustain=-12, release=100)\n", + "y = env.process(gate_square(1.0, 1.0))\n", + "\n", + "a = int(0.100 * sr)\n", + "first_peak = int(np.argmax(y >= 0.999))\n", + "print(f\"attack: reaches full scale at {first_peak / sr * 1000:.1f} ms (knob: 100.0);\"\n", + " f\" midpoint {y[a // 2]:.3f} (law: 0.652)\")\n", + "\n", + "sus = 10 ** (-12 / 20)\n", + "closed = 1 - (y[a + int(0.200 * sr)] - sus) / (1 - sus)\n", + "print(f\"decay: {closed * 100:.1f} % of the gap closed at the 200 ms knob (contract: ≥95 %)\")\n", + "\n", + "rel_start = int(1.0 * sr)\n", + "rel = y[rel_start:]\n", + "print(f\"release: level {rel[int(0.100 * sr)]:.4f} at the 100 ms knob;\"\n", + " f\" final sample {rel[-1]} (exactly zero — the stage ends)\")" + ] + }, + { + "cell_type": "markdown", + "id": "00a6e580", + "metadata": {}, + "source": [ + "## 3 · Gate amplitude is velocity\n", + "\n", + "The family contract lands: with `velocity` sensitivity at 1, a plain 1.0 gate is unity, an\n", + "accented 2.0 gate (the 303 convention) hits twice as hard, and a half-level gate lands\n", + "soft. At sensitivity 0 the envelope is amplitude-blind — the legacy behavior, still the\n", + "default. The default `threshold` (0.005) also hears the 808 sequencer's plain level\n", + "(0.01), retiring the old hard-coded 0.5 gate that a default accented row could never\n", + "open." + ] + }, + { + "cell_type": "code", + "execution_count": 4, + "id": "fb5de450", + "metadata": { + "execution": { + "iopub.execute_input": "2026-08-05T11:29:01.853892Z", + "iopub.status.busy": "2026-08-05T11:29:01.853547Z", + "iopub.status.idle": "2026-08-05T11:29:02.099319Z", + "shell.execute_reply": "2026-08-05T11:29:02.097890Z" + } + }, + "outputs": [ + { + "data": { + "image/png": "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unfvrg8dOvSI9TX12moThzPPPDPwD395ebneo0cP/fLLLw+Ua257NebXX3/VFUXRX3zxxcC277//Xu/WrVuDBO5wq1at0g0Gg/71118f9bW0NMYrrrhCHzlyZOAYXfd/fup+0WmOxmKtfX/PPvtsPS8vT9d1Xd+3b59uNpv1P/zhD/of/vAH3efz6bqu6y+99JKuaZqemZnZ4Pjx48frBw4c0HVd151Opz558mS9T58+usfj0XX9yEn4kd6z5ibhGzdu1FVV1f/5z38Gtn399dcN2vB4PieHx9ySdgnm57y552hu2wjREcmYcCGC7OqrryY/P59vv/02sG3BggXk5+cHLuJ66aWXMJvNPP3004Gf5aOjo7nnnnuYO3cuRUVFjdb96quvEhMTw1//+tfAtpEjR3L55Zfz6quv4vV6AXjxxRex2Ww899xz9YZtnHfeeY3+/HwkN954I+Xl5fVmgZg7dy7l5eXcdNNNx1RXc1VUVDQ63KB2W92ZPaZNm8bZZ599XOe78MILSUlJAcBut3PppZfy/fffB/a3tL0AXn75ZTp37sztt98e2HbGGWfQs2fPRsvv27ePRYsW8eGHH5KRkUF8fDw//vjjUV9DS2PMzs4mMjIycAxAv379mjUEobmxXnjhhcTHxwOQmprK+PHj+de//sXDDz+MoigAXHHFFXi9XpYsWdLo8Z06dQLAZDLxxBNPsG3bNhYsWHDUGFvDSy+9REpKCr///e8D28455xzS09MblGvp5+Rwx9MuTWnLz3lzzyHEiUzGhAsRZCNHjqRXr1688847gfGY77zzDt27d2fMmDEArF69msTERObPn1/v2L179+Lz+di2bVugbF0bN25kwIABgXHStYYOHcpbb71FZmYm3bt3Z+3atZxyyimEhYUd9+vp2rUrZ599NrNnz+aaa64BYPbs2UyaNKnJsejHy2QyNToLSu22uq//+eefP+7zDR48uN56586dyc/Px+VyYTKZWtxeANu2bWPAgAH1kimAgQMHBsY4AzidTq688kq++eYbhg8fTnx8PJqmUV1d3ayZTFoa45VXXsmNN97IiBEjmDFjBmeddRZDhgwJJMeNOdZYBw4cWG89OTmZTp06ERMTE9gWExODyWTi4MGDDY4/PPEcNGgQqqqydevWBmOe28K2bds45ZRTGozHHjJkCMuXLw+sH8/n5HAtaZejacvPeXPPIcSJTJJwIULA1Vdfzd///nfKysoA+OKLL7j33nsD+x0OB5WVlQ3+sYNDs4I0xu12Y7VaG2yv7SF2uVyBZWxs7PG+jICbb76ZCy64IDCt2LJly5gzZ06r1X+4Tp06UVJS0uAf7tzcXIBAT1trOfz9rr1Ir/b8LW0vgOrq6kZnvDi8Hf/xj3/w/fffs3Hjxno9rGlpaei6ftTX0NIYb7jhBnr16sW7777LG2+8wX333Uf//v35+OOP6dOnT6PHHGush19kZzQaG73wzmg04nQ6G2y3WCz11g0GAwaDgaqqqkbja67aL0aHx1z7d1Srqqqq0b+nw9vweD4nh2tJuxxNW37Om3sOIU5kkoQLEQKuuuoqHnroIT755BN0Xae6upqrrroqsD89PR2v13vMiWzXrl3Zvn17g+27du1C07TADCbdu3dnw4YNx1T3kXrYpk2bRkpKCrNnz0bXdeLj47nwwguPqf5jMWzYMHRd59dff2X48OGB7evWrcNgMDBo0KBjqu94eg+h5e1Ve2xjcz9nZmbWW1+5ciUjR46sl9SWlpaSlZVVr1xTr+V4Yhw3bhzjxo0D4LfffmPKlCncc889fP75542Wb26srSUjI6PebCRZWVm4XK4Gw0Ga0tR7lpCQAPhvIFN3VpLDbyqVnp7Ojh07Go3r8HItbYPGHGu7BPNz3lLHG7MQoUTGhAsRAtLS0hg3bhzvvPMO77zzDqeddlq9oRuzZs1i8+bNfPXVVw2O3bt3b5P1XnTRRezYsYPFixcHtlVUVPD2229z9tlnB8Z7X3311ezZs6fBP6ZFRUUNevlq1fb0NXbHO03TuOGGG/jf//7H22+/zaxZs1qtV0vXdebMmcOqVasC28455xzi4uKYPXt2YJvT6eSdd95h+vTpREVFBbZ/9dVXfPfdd0c8x5FeW3O0tL0AZsyYwfr161m3bl1gW2FhYb1rBsA/9nb//v31emWff/75elPnQdOvpaUxHr5v4MCBDBgwgMrKyiaPaW6sreXdd9+td67XXnuN8PBwpkyZ0qzjm3rP+vfvj6Zp9cah5+TkNPg8XXzxxWzYsIE1a9YEtuXm5jZow+P5nBytfHPaJZif85Y63piFCCXSEy5EiLj66qv53e9+B8Arr7xSb98FF1zAPffcw0UXXcT111/P0KFDKSkpYcWKFRw4cKBeQlrXNddcw/z587ngggu46667iI2N5T//+Q+6rvPSSy8Fyl144YX8/ve/56qrruLHH3/k1FNPJSMjg08//ZTVq1c3mkD37NmTzp0788QTT5CVlYXJZKo3X++NN97IE088gc/na/YFmT/88AN5eXkcOHAA8I+ZtdvtaJoWmB/b6/Vy+eWXM2vWLEaOHAlAWFgYr732GpdddhmapjFs2DDefvttqquree655+qd449//CNRUVFMnjy5yTiaem3N1dL2Arjkkkt4/fXXmTJlCnfddRdWq5XPPvuMyy+/nNdeey1Q7o477mDcuHFceumlnH322axatQqv10uvXr2a9VpaGuNNN90UmLs7MTGRVatWsXjxYubNm9fka2purK1lzJgxTJ8+nWnTpvHbb7/xyiuv8MILLzT7xjZNvWepqalcddVV/PnPf6a4uBhVVfnmm2+4+uqr67XNxRdfzBlnnME555wTaMNPP/2UK6+8kldffTVQ7ng+J4drSbsE83PeUkf7/44QHYn0hAsRIi655BJmzpzJzJkzufTSSxvsf+qpp/jpp5+Ijo5m2bJlgdlTVqxYEShz+N3lVFXl008/Zfbs2eTk5LBmzRquuuoqNm3a1OCn+RdffJEffvgBq9UaOM9PP/0U+Mft8LrNZjMLFy5k+PDhfPvtt8yfP5/y8vJAfV26dGHAgAFMmDCh2cnW8uXLmT9/PmvWrGHmzJmUlpYyf/78wI1eal/TzJkzAwl4rYsuuog1a9Zgs9lYsmQJkydP5rfffqNr1671yjVndpSmXltycjIzZ86s17MO/uE8M2fOrNez25z2aoyiKHz99dc8+uijbNu2jdzcXN5++200TSMyMjJQbtSoUaxZs4auXbuycuVKTjvtNP7zn/8wZcqUeu/NkdqpJTF+99133HHHHRQWFrJ06VISEhLYvHkz06ZNa/KY5sba1Ps7YsQIzjnnnAb1XnzxxQwYMKDB9unTp/OXv/yFDRs24PV6+e677+rNVHL4Z/lYPtuvv/46TzzxBJs2baK0tJT333+fsWPHcvHFFwfqVxSFb775hscff5zt27eTm5vLu+++y6RJkxr8bbf0c3J4zC1pl2B+zpt7jmP9/44QHYmiN+cKHiGEOEY7duygb9++fPDBB41+qRBNy8/PD0zRB/6L1AYOHEi/fv349NNPgxhZaFuwYAHnnHNOYFYgIYQIZTIcRQjRqrZu3crq1at54YUXGDRoUL0eQtE8t9xyC7GxsQwfPpyysjLeeecd8vLy+Pjjj4MdmhBCiFYiw1GEEK1q586dLFiwgClTprBgwYIG812Lo3v//fcZPXo0GzZsYNOmTVx55ZVs2bJFenePoqkhDkIIEYpkOIoQQgghhBDtTLqohBBCCCGEaGeShAshhBBCCNHOJAkXQgghhBCinZ0Us6P4fD5KSkqwWCxyy1shhBBCCNFmdF3H4XAQFRV1xMkJTookvKSkJHCrWyGEEEIIIdpaYWEhMTExTe4/KZJwi8UC+N8Mq9XarufWdZ3c3FwSExOlFz5ESJuEJmmX0CNtEpqkXUKPtEloCla7VFdXExsbG8g/m3JSJOG1b7zVag1KEl57XvnDDA3SJqFJ2iX0SJuEJmmX0CNtEpqC3S5HO6dcmCmEEEIIIUQ7kyRcCCGEEEKIdnZSDEcRQgghhDgR+Hw+3G53sMPoEHRdx+Px4HQ6W304islkOu46g5qEr127lsWLF6NpGhMnTmTw4MFHLF9QUMCcOXMoKChg9OjRnH322e0TqBBCCCFEEOm6Tl5eHkVFRcEOpUPxer2Ul5e3er2aptGtWzeMRmOL6whaEj5r1iy2bdvGhAkTKC8v54EHHuDRRx/lL3/5S6PlDxw4wIgRIxg4cCADBgxg1qxZXHHFFTz33HPtHLkQQgghRPuqTcATExOx2WxyAWgz1PaEGwyGVn2/fD4fBw8eJDs7m9TU1BbXHbQk/I477mD48OGB9cGDB3P33Xdz1113NTqx+eOPP07Pnj355ptvUBSFSy65hNGjR3PrrbfSs2fP9gxdCCGEEKLd+Hy+QAJ+pHmnRX26rqNpWqsn4QAJCQkcOHAAn8+HpmktqiNoSXjdBBzAbrcfsfzChQu56667Am/iyJEjSU1NZeHChQ2ScLfbjcfjCaxXV1cD/sbQdb01wm+22nO21nmzC1zsz3Uyon94q9R3MmrtNhGtQ9ol9EibhCZpl9DT1m3icrkA/1TL0u7Hpvb9au33zWDwp9But7tB53FzzxUSF2aWl5fz97//nZtuuqnJ23seOHCATp061dvWqVMnsrKyGpR94oknePTRRxtsz83NDco84SUlJcDR54tsjrtezCe/xMdTt8TSOSEkmq/Dae02Ea1D2iX0SJuEJmmX0NPWbeLxePB6vXi93nqdjOLIdF3H6/UCrd8ute1RUFAQSMhr1Xb+Hk3Qs7iKigrOO+88unXrxpNPPtlkOUVRGnyz0HW90Tf1/vvv59577w2s1965KDExMShJONBqd2vKL8kFYN1ulaGnJB53fSej1m4T0TqkXUKPtEloknYJPW3dJk6nk/LycgwGQ4OETxzd8Vw82RSv14umacTFxWE2m+vt6xBJeElJCVOnTiU5OZkPPvgAk8nUZNnU1FT27dtXb9v+/ftJTU1tUNZoNDb6hiuKErQ7JrXGuUvKD337XbiqmBumJ6Np8j/glmitNhGtS9ol9EibhCZpl9DTlm1SW6e0+bGp21nb2u/bkdqkuecK2s168vPzmTRpEunp6Xz44YcNEvClS5fy1FNPBdanTp3KnDlzAj8rLFmyhJycHCZPntyucQfTrgOHvlkVlXlYvaX1p9wRQgghhAi2JUuWsGPHjuOup7CwkG+//ZalS5dSWVl51PJut5slS5bw2WefkZube9znP5KgJeHnnnsuGRkZpKSk8MADD3Dfffdx3333UVZWBsCKFSt45ZVXAuXvv/9+8vLyGDduHDfddBMXXXQRDzzwAN26dQvWS2h3u2uS8GunJQGwYKXMFSqEEEKIE8/f/vY3vv766+Oq47777mP48OE8//zz/OlPf6Jbt24sWbKkyfL5+fmceuqp3Hzzzbzwwgv06NGDjz/++LhiOJKgDUe55pprqKioaLC9tgv/9NNPJzIyMrA9MTGRX3/9lfnz51NYWMgNN9zAqFGj2i3eULDnoAOAM0ZEsfzXUlb8VkZphYdIu4wPE0IIIURoKSgoYM2aNSQmJjJgwAA++eQTpk2bht1uZ+XKlWRmZqIoCqmpqQwdOjQwtnrNmjXk5uayfv165syZQ0REBFOnTgX8M8Vs2LCBwsJCBg8eTHJycpPn7927N1u3biUsLAxFUbj99tu544472LRpU6PlH3zwQcLDw1m6dClGo5FXX32Vm266iXPOOYewsLBWf3+COk/4kYwaNapBkh0eHs7VV1/dlmGFtMyDDiwmlaQYE1NGRfPy3IN8/0sxMybFBzs0IYQQQoiARYsWMWPGDAYPHozb7cZms/H999+zc+dOevTowdq1a1m2bBk+n49t27bhdrv54YcfSE5O5tdffyU/P5+NGzfidDrp1KkTU6dOZdOmTcyYMYOwsDCSk5NZsWIFzzzzDNdff32jMVx33XX1ZpMZNGgQn3zySZMxz5s3j7///e+B6wqvvfZa/vSnP7F48WKmTZvWum8QITA7imgen09nX46DtGQLqqowaXg0r83L5tuVRZKECyGEECehPz23i/xid7ucKz7ayD/v6tGssj6fj5tuuomHHnqIu+66C4CHH36Y77//PlDm9ttv5/bbbw+sX3fddTz11FM8//zz3HDDDXzwwQdMmzaNO++8M1Dmqquu4vLLL+eRRx4BYP369UyYMIFzzz2XxMQjzxjncrl44403uOiiixrdX1lZSV5eHunp6YFtFouF5ORkMjIymvW6j1XQxoSLY5NT6MLp1umaYgEg0m5g9CkR7D7gYOf+qiBHJ4QQQgjht3fvXvbs2VOvh/qGG25oUC4jI4Ovv/6aDz/8kIiICNauXdtknVlZWfz666/Ex8czZ84c5syZw/bt2wkLC2PNmjVHjMfj8XDFFVegaRpPP/10k2WABhOFmM3mNpubXXrCO4jMbP948LRkS2DblNEx/Li+lAU/F9Fzpi1YoQkhhBAiCJrbM93eaufJrntvFputfp5yww038PnnnzNs2DAiIiLIysqisLCwyTprJ+5YsmRJvdvET5gwgfDwpu8i7nQ6ufLKKykqKuK7775rcmx3eHg4VquVnJycettzc3OP2sveUpKEdxCZBxsm4cP6hZMQbWThL8XceEEyVrPW1OFCCCGEEO2iW7duWK1Wli9fzhlnnAHAsmXLAvtzc3P573//y759+wL3e3n88cd57733AmUO74Hu0aMHERER/O53v+Oss84KbC8uLm6Q4NeqqqriggsuQFEUvv322wblNmzYQF5eHpMnT0ZVVcaNG8dXX33FjBkzAPjpp58oKSlh3Lhxx/mONE6S8A4i0BOecigJ11SFqafF8taXOSxZW8I5Y2KDFZ4QQgghBODvAb/33nu5+uqrueeee/B4PLzxxhuAfxa86OhoEhISuP/++znjjDPYtGkTb7/9NtHR0YE6BgwYwIcffkhiYiKxsbFMnTqVl156iauuuorf/e53pKens23bNubPn8+qVasa3LUS4JxzzmHHjh38v//3//j8888D2y+99FJUVeXdd99lyZIlgXvOPProo0ycOJHIyEjS09N55plnuO222+jSpUubvE8yJryD2JvtwGZRSYiufyfQc8bEoKrwxbKmf8IRQgghhGhPDz/8MM899xxbt26lrKyMt99+GwC73Y7JZGL58uUkJCTwww8/kJiYyIcffsi5554bOP6BBx7gwgsvZOHChSxatAjwT2+9cOFCAJYvX058fDwrVqwgKiqq0RhSU1MZP348CxYsYP78+YFH7Y0fhwwZwtlnnx0oP2rUKFasWIHP52PdunU89thjvPjii23x9gCg6Lqut1ntIaK6uhqbzUZVVVW98UntQdf1wHiilt4y1evTOffOjfTobOXle3o22P/I65ks21DKK/f1pFcXGRt+NK3RJqL1SbuEHmmT0CTtEnrauk2cTicZGRmkp6c32uMbioqLi+v1bL/zzjvcfffdDcZctyVd1/F4PBgMhlZvlyO1SXPzTukJ7wAO5rtwe3S61hkPXte0cf5hKF9Kb7gQQgghQsCKFSs477zzeO2113jooYe4/fbbuf/++4MdVkiRMeEdwN5GxoPXdWpvOynxJhatKeF3F6Vgt8oFmkIIIYQInqlTp6KqKl9++SUmk4l58+YFLtIUfpKEdwC1SXjXpMZ/glJVhWljY3l9XjaLfinm/Alx7RmeEEIIIUQDU6ZMYcqUKcEOI2TJcJQOYH+eE4AuSY33hAOcPSoGo0Hhi2WFnATD/IUQQgghOjRJwjuAA3lOjAalwcwodUWFGxg/JJI9Bx1s3FXZjtEJIYQQQohjJUl4B3Agz0nnBDOqeuQrey843T8M5dPFBe0RlhBCCCGEaCFJwkNcaYWH8kovnROOPiVRv25h9E2z8dOvpeQUutohOiGEEEII0RKShIe4A7n+8eDNScIBLpoYh0+H+UukN1wIIYQQIlRJEh7iai/K7JzYvCR8/KlRxEYa+PrnQqod3rYMTQghhBBCtJAk4SHuQE0SntrMnnCDpnD+hDgqq318u6q4LUMTQgghhBAtJPOEh7gDx9gTDjBtbCzvfpPLvMUFTB8Xe9QLOoUQQgghQsl7771Hz549GTFiRIvrWLp0KUuXLkVVVRRF4d5778VobHqmOYDCwkLmzZtHaWkpp59+OkOHDm3x+Y9GesJD3IFcJ+E2jYiw5t8FM9Ju4MwR0RzIc7J6S3kbRieEEEII0frefPNNfv755+Oqw+1243A42LVrFw8++CBOp/OI5Xfv3k2/fv346KOP2L59OxMnTuT5558/rhiORHrCQ5jPp5OV76R7JyuKcmy92RdNjOPrn4r4eFE+IwdEtFGEQgghhBCN++233/jxxx9JTExk8uTJvPTSS9x+++1ER0fz2WefsXHjRhRFITU1lSlTppCQkADAN998Q2ZmJgsXLqSiooK4uDhuueUWAPLy8vj+++8pLCxkxIgRjBw5ssnzn3nmmZx++umsXLmSt99++6jx3n///QwbNoyvvvoK8N/x88orr+Tqq68mNja2Fd6R+qQnPITlF7txufVmz4xSV7cUK8P7hbNuewU79lW1QXRCCCGEEI177733GDNmDBs2bODLL79k/PjxPPjggxQWFgKHeqkrKyuZN28eAwYMYPv27YF9Xq83UKa2B3vJkiUMGDCA+fPns2vXLi6++GIeeeSRVot5wYIFXHHFFYH16dOnYzAYWLx4caudoy7pCQ9htTOjpB7DePC6LpucwOot5cz5Lo+HbkxrxciEEEIIEWzlP12IXn2wXc6lWFMIP21es8q63W7+9Kc/8cYbb3D55ZcD8Oqrr3LrrbcGylx88cVcfPHFgfW7776bf/zjH8yePZvp06fz4osvMnXqVO68804AdF3nuuuu44knnuCmm24C4M9//jN9+/bluuuuo2vXrsf1+srKyigtLSU1NTWwzWAwkJSUxIEDB46r7qZIEh7CsmqS8E4t6AkHGNTTf/OeH9eXBu66KYQQQgjRlvbs2UN+fj7nnXdeYNv5559fLwn3+Xx8//33bNu2jfLycg4cOMCePXuarHPv3r1kZmaye/du/va3vwW222w21q9ff9xJeK3Dh/8qioKu661S9+EkCQ9h2QX+u16mxJtadLyiKFw2OYGHX8/ko4V53HVl6tEPEkIIIUSH0Nye6WCpm9Cqav0R0GeeeSZ5eXlMnDiRiIgI3G43JSUlTdbldrsB8Hq9OByOwPabb765VRLwiIgIIiIi6vV6e71ecnJy6Ny583HX3xhJwkNYbRKeHNeyJBxgzMAIUhPNfLeqmFnTkoiNPPLUPEIIIYQQx6Nbt27ExMTw9ddfc8kllwDw5ZdfBvZnZ2ezePFicnNzAxdj3nXXXWzatClQxmaz1ZvNpHv37iQnJ3PqqacGhrgAbN++vd4QkmOxaNEi9u7dy/XXXw/A5MmTmTNnTqD+r7/+GqfTyemnn96i+o9GkvAQll3oxG7VCLe1vJlUVWHmWfE88+4BPvkhn99dmNKKEQohhBBC1Gc0Gnnqqae4/vrrWbp0KR6Ph+XLlwP+HvGEhAR69erFJZdcwvjx49m0aRPr16/HYrEE6hg5ciSvv/46VVVVJCcnc8stt/DWW29x1VVX8fnnn5Oens62bdvYtWtXoO7Dbdu2jY8++ijQu/2Pf/wDk8kUmKHlm2++YcmSJYEk/G9/+xtjxozhvPPOIz09nf/973889thjxMfHt8n7JLOjhChd18kucB1XL3itM4ZHExdl5ItlhVRUya3shRBCCNG2brzxRhYtWkTXrl0ZM2YMH374IQCRkZFomsbKlSu5/PLLMZlMzJo1i6+++qremPF7772XJ598Ek3TAj3ikydPZtOmTUyZMgW73c7VV1/N2rVrCQ8PbzSG2qErCQkJ3H///fh8PhwOR2CM95lnnskNN9wQKN+7d282b97M5MmTSUhI4KuvvuLee+9tq7cIRW+r0eYhpLq6GpvNRlVVFVartV3Pres6ubm5JCYmHtNc36UVHi66ZzPjh0Ty8E1pxx3H3EX5vPrJQWZNS+SaqUnHXV9H1tI2EW1L2iX0SJuEJmmX0NPWbeJ0OsnIyCA9PR2zuWNMsrBv3z5SUlIwGPy/5v/zn//k5ZdfZvfu3e0Wg67reDweDAZDq7fLkdqkuXmnDEcJUa0xHryuaWNjmPNdHp8sKuCi0+Ox25p/B04hhBBCiGOxd+9eLrjgAs444wyysrL47LPPmnXDnJOJDEcJUQcL/D+9JMe2ThJuNWvMPCueimovny7Jb5U6hRBCCCEaM27cON577z06derE2LFjWb9+PTNmzAh2WCFFesJD1KGe8Nb72Wn6+Dg+XJgvveFCCCGEaHN9+/alb9++wQ4jZElPeIhq7eEoABaTymWTE/y94YulN1wIIYQQIlgkCQ9ROYUuVAUSYlp3Xu/zxsUSHWHg4x/yZaYUIYQQQoggkSQ8RGUXuIiPNmI0tG4TWUwql52VQGW1j09+kN5wIYQQQohgkCQ8BHm8OnlFrlYdD17XtJre8E9+yKe0wtMm5xBCCCGEEE2TJDwE5RW58OmtOx68LotJ5epzEql0+HhvQW6bnEMIIYQQQjRNkvAQdLANLso83LljY+kUb+LzHwvJKXS12XmEEEIIIURDkoSHoNyapDipleYIb4xBU7juvCTcHp23vshps/MIIYQQQoiGZJ7wEJRX7E/CE2PaLgkHmHBqFB99n8/3q4u55Mx4undu+taqQgghhBDt5bnnnmPgwIGceeaZx1XP9u3b+eCDDygrK2PixIlcdNFFTZb99NNP+frrr+ttmz59OtOnTz+uGJoiPeEhKLfIDUBCdOtOT3g4VVW46YJkdB1mf5bdpucSQgghhGiur7/+mk2bNh1XHevXr2fkyJHk5uaSnJzM7bffzt13391k+V9++YXNmzczatSowKNz587HFcORSE94CMorcqGqEBvZtkk4wKl9whnax86qzeVs2FHB4F72Nj+nEEIIIU58X3/9NT/88AOJiYlcdtllPProozz55JPEx8cze/ZsVqxYgaIopKamcvHFF9OvXz8A3n33XbZu3UplZSWbNm0iOTmZxx9/HIAtW7Ywf/58CgsLGTlyJJdeemmT53/ooYc4//zzeeONN1AUhdGjR3PWWWdx55130qlTp0aP6d69OzfeeGPrvxmNkJ7wEJRX5CYuyoimKe1yvpsuTEZR4JWPs/D69HY5pxBCCCFOXM8++yzXXHMNUVFRVFRUcOaZZzJ79mxKS0sBf7I7atQohg8fTnFxMWPGjGH16tUAdOvWjcjISLp27cqoUaMYNGgQAHPnzmX8+PGUlJTQuXNnnnzyySYTZl3XWbJkCeedd15g2+mnn47dbufHH39sMu7Nmzfz+9//nkceeYSVK1e21tvRKOkJDzFen05+iZs+abZ2O2fPVBtTRsfwzc9FLPi5iHPHxrbbuYUQQgjRMi9sWk6xs7pdzhVttvLHAWObVdbhcPDII48wd+5cpkyZAkD//v2ZOXNmoMzpp5/O6aefHliPjY3ln//8J++//z6nnXYaKSkpjBo1KpBke71ebrvtNl599VUuvvhiAGbNmkWXLl24++676d27d70YysrKqKysJDk5ObBNURSSkpLIzm58CO6MGTPo0aMHXq+XLVu2cOaZZ/Lggw9y7733Nut1H6ugJeEff/wxL7/8cmB9zpw5JCUlNVn+ww8/5JVXXqm37cILL+SPf/xjm8UYDMVlHjxencRWvl390Vw/PYml60r47+c5TBgahd2qtev5hRBCCHFiyMjIoKKiol6SPXHixHplysrKmDNnDtu2baO8vJw9e/YEesmbqrOgoID58+ezYMGCwHaj0cjGjRsbJOGa5s9jPJ76NyV0u92BfYcbPnw4w4cPD6yPGTOGq666ijvuuIOwsLAjv+gWCFoSPmrUKOLi4ti3bx+zZs3C4XAcsfz+/fupqqriH//4R2BbU+N5OrLamVESott2ZpTDxUQYufqcRF6bl827X+dyy4yUdj2/EEIIIY5Nc3um25vZ7L/jt9PpxGKxBJ7X0nWdsWPHkpyczOTJk4mIiEBVVZYuXdpknUajv3Ny+PDh9RLiusNV6rLb7cTFxbF3797ANpfLRXZ2Nmlpac16HSNGjMDj8XDgwIEGSX5rCFoS3rlzZzp37sy2bduafUxMTEy9b1UnorzamVHauScc4MKJcXz5UyGfLs7n3LExpCZa2j0GIYQQQnRsaWlpdO7cmffff59bb70VgHfeeSewPzs7m40bN/Ldd98FRkH89NNP9eoIDw+nsrIysN61a1d69eoFUG8c+A8//NDkSIpp06bx9ttvM2vWLAwGA++99x4GgyHQKz937ly2b9/OAw88AMBXX33FueeeGzh+zpw5REZGkp6e3uL34kg61JjwzZs3M3XqVCIjI5k0aRLXX399oz8puN3uej8/VFf7x0vpuo6ut++Fh7XnbO55c4v8PeHx0cZ2j9WgKdx6UQoPvJrJvz8+yN9v69au528vx9omon1Iu4QeaZPQJO0Setq6TWrr7SjtrqoqL7/8MldeeSVfffUVHo+H8vLywL6kpCTGjBnD+PHjGTlyJJs3b0ZR/JNR1L6+M888k0cffZQdO3aQmprK448/znvvvcell17KnDlzSE9PZ9u2bcTExDB//vxG35cnnniCcePGMXz4cLp06cKiRYv417/+RXh4OLqus3LlSpYuXcr9998P+IdK//Wvf6V///5kZGSwY8cO/ve//2EwGBrUf6Q2aW4bKXqQW3Pbtm307duXPXv2HPHngf3797N79258Ph87d+7kySefZOTIkXz44YcNyj7yyCM8+uijDbZnZGRgtbbvDWl0XaekpISoqKjAB+xI/regjO9+qebJm2Poktj+veG6rvOP90v4bbeLP82MZFjvE683/FjbRLQPaZfQI20SmqRdQk9bt4nH46GkpIS0tLTAUI+OYP/+/axatYrExEQSEhI45ZRTyM/PJzIyEo/Hw6JFi8jPz2fAgAFER0ezZs0aZsyYETh+9erVbNu2DZvNFtjucDj45ZdfOHjwIH369GHw4MFNnl/XdSoqKliyZAnl5eWMGTOmXq65evVqsrOz692MZ/v27WzYsIGYmBhG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", + "text/plain": [ + "
" + ] + }, + "metadata": {}, + "output_type": "display_data" + }, + { + "name": "stdout", + "output_type": "stream", + "text": [ + "a plain 0.01 sequencer hit opens the envelope: level 0.819 after 20 ms\n" + ] + } + ], + "source": [ + "fig, ax = plt.subplots()\n", + "for amp, color in [(2.0, C[0]), (1.0, C[1]), (0.5, C[3])]:\n", + " env = tap.Adsr(sr, attack=20, decay=150, sustain=-9, release=200, velocity=1.0)\n", + " y = env.process(gate_square(0.3, 0.3, level=amp))\n", + " ax.plot(np.arange(y.size) / sr, y, color=color, lw=1.3, label=f\"gate {amp}\")\n", + "ax.set_xlabel(\"time (s)\")\n", + "ax.set_ylabel(\"envelope\")\n", + "ax.set_title(\"velocity 1.0: the gate's amplitude is the hit\")\n", + "ax.legend(loc=\"upper right\")\n", + "plt.show()\n", + "\n", + "env = tap.Adsr(sr, attack=5)\n", + "y = env.process(np.full(int(0.02 * sr), 0.01)) # the seq's plain level\n", + "print(f\"a plain 0.01 sequencer hit opens the envelope: level {y[-1]:.3f} after 20 ms\")" + ] + }, + { + "cell_type": "markdown", + "id": "8e1ae9a8", + "metadata": {}, + "source": [ + "---\n", + "\n", + "Every number above is the shipping kernel through its C ABI; the same contract points are\n", + "pinned in `tests/adsr_test.cpp`, alongside the scenario that keeps the legacy hybrid curve\n", + "honest (linear attack midpoint 0.5, dB-linear decay). The wrapper's default mode is now\n", + "`analog`; the Jamoma curves remain one attribute away." + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "Python 3", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.11.15" + } + }, + "nbformat": 4, + "nbformat_minor": 5 +} diff --git a/notebooks/taptools_py.py b/notebooks/taptools_py.py index 6bde0bc..5d5409b 100644 --- a/notebooks/taptools_py.py +++ b/notebooks/taptools_py.py @@ -216,6 +216,18 @@ def load() -> ctypes.CDLL: "taptools_tune_target_midi": ([vp], ctypes.c_double), "taptools_tune_applied_semitones": ([vp], ctypes.c_double), "taptools_tune_process": ([vp, f64p, f64p, ctypes.c_int], ctypes.c_int), + "taptools_adsr_create": ([], vp), + "taptools_adsr_destroy": ([vp], None), + "taptools_adsr_prepare": ([vp, ctypes.c_double], ctypes.c_int), + "taptools_adsr_clear": ([vp], ctypes.c_int), + "taptools_adsr_set_attack": ([vp, ctypes.c_double], ctypes.c_int), + "taptools_adsr_set_decay": ([vp, ctypes.c_double], ctypes.c_int), + "taptools_adsr_set_sustain_db": ([vp, ctypes.c_double], ctypes.c_int), + "taptools_adsr_set_release": ([vp, ctypes.c_double], ctypes.c_int), + "taptools_adsr_set_mode": ([vp, ctypes.c_int], ctypes.c_int), + "taptools_adsr_set_threshold": ([vp, ctypes.c_double], ctypes.c_int), + "taptools_adsr_set_velocity": ([vp, ctypes.c_double], ctypes.c_int), + "taptools_adsr_process": ([vp, f64p, f64p, ctypes.c_int], ctypes.c_int), "taptools_harmonizer_create": ([], vp), "taptools_harmonizer_destroy": ([vp], None), "taptools_harmonizer_prepare": ([vp, ctypes.c_double, ctypes.c_int], ctypes.c_int), @@ -825,6 +837,54 @@ def __del__(self): self._h = None +ADSR_MODES = {"analog": 0, "hybrid": 1, "linear": 2, "exponential": 3} + + +class Adsr: + """tap.adsr~'s kernel (tap::tools::adsr::generator): the virtual-analog + envelope (truncated RC attack, asymptotic decay/release) with the Jamoma + curves as compatibility modes. Gate amplitude is velocity under the + `velocity` sensitivity; the gate opens above `threshold`.""" + + def __init__(self, sr: float = 48000.0, **params): + self._h = _LIB.taptools_adsr_create() + _check(_LIB.taptools_adsr_prepare(self._h, float(sr)), "prepare") + self.set(**params) + + def set(self, *, attack=None, decay=None, sustain=None, release=None, mode=None, + threshold=None, velocity=None) -> "Adsr": + if attack is not None: + _check(_LIB.taptools_adsr_set_attack(self._h, float(attack)), "attack") + if decay is not None: + _check(_LIB.taptools_adsr_set_decay(self._h, float(decay)), "decay") + if sustain is not None: + _check(_LIB.taptools_adsr_set_sustain_db(self._h, float(sustain)), "sustain") + if release is not None: + _check(_LIB.taptools_adsr_set_release(self._h, float(release)), "release") + if mode is not None: + _check(_LIB.taptools_adsr_set_mode(self._h, ADSR_MODES[mode]), "mode") + if threshold is not None: + _check(_LIB.taptools_adsr_set_threshold(self._h, float(threshold)), "threshold") + if velocity is not None: + _check(_LIB.taptools_adsr_set_velocity(self._h, float(velocity)), "velocity") + return self + + def process(self, gate) -> np.ndarray: + gate = _f64(gate) + out = np.zeros_like(gate) + _check(_LIB.taptools_adsr_process(self._h, _p64(gate), _p64(out), gate.size), "process") + return out + + def clear(self) -> None: + _check(_LIB.taptools_adsr_clear(self._h), "clear") + + def __del__(self): + h = getattr(self, "_h", None) + if h: + _LIB.taptools_adsr_destroy(h) + self._h = None + + class Harmonizer: """tap.harmony~'s kernel (tap::tools::harmony::harmonizer): up to four formant-preserving pvoc voices at fixed intervals plus a latency-aligned diff --git a/tests/CMakeLists.txt b/tests/CMakeLists.txt index 6e54341..e1a148c 100644 --- a/tests/CMakeLists.txt +++ b/tests/CMakeLists.txt @@ -12,6 +12,7 @@ FetchContent_Declare( FetchContent_MakeAvailable(Catch2) add_executable(taptools_kernel_tests + adsr_test.cpp autowah_test.cpp diode_ladder_test.cpp grm_comb_test.cpp diff --git a/tests/adsr_test.cpp b/tests/adsr_test.cpp new file mode 100644 index 0000000..596cee0 --- /dev/null +++ b/tests/adsr_test.cpp @@ -0,0 +1,189 @@ +/// @file +/// @brief Unit tests for the virtual-analog ADSR kernel (tap::tools::adsr::generator). +/// @details Pins the analog model's contract numbers (attack reaches full scale at the knob +/// time with the truncated-charge midpoint near 0.65; decay and release close 95 % +/// of their gap at the knob time and taper asymptotically), the family trigger +/// contract (default threshold hears the sequencer's plain level; gate amplitude is +/// velocity under the sensitivity control), retrigger-from-current-level, and the +/// faithful preservation of the legacy Jamoma curves. +// SPDX-License-Identifier: MIT +// Copyright 2026 Timothy Place. + +#include +#include + +#include +#include + +namespace { + + constexpr double k_sr = 48000.0; + + /// Run `n` samples at a constant gate level, returning every output sample. + std::vector run(tap::tools::adsr::generator& g, double gate, int n) { + std::vector out(static_cast(n)); + for (int t = 0; t < n; ++t) { + out[static_cast(t)] = g.process(gate); + } + return out; + } + +} // namespace + +SCENARIO("the analog attack reaches full scale at the knob time, convex like a charging capacitor") { + tap::tools::adsr::generator g; + g.prepare(k_sr); + g.set_attack_ms(100.0); + + const int attack_samples = static_cast(0.100 * k_sr); + const auto out = run(g, 1.0, attack_samples + 100); + + // Reaches the peak at the knob time (within a handful of samples). + int first_at_peak = -1; + for (int t = 0; t < static_cast(out.size()); ++t) { + if (out[static_cast(t)] >= 0.999) { + first_at_peak = t; + break; + } + } + REQUIRE(first_at_peak > 0); + REQUIRE(std::abs(first_at_peak - attack_samples) < attack_samples / 50); + + // The truncated-charge law puts the midpoint near 0.65 — visibly not a straight line. + const double mid = out[static_cast(attack_samples / 2)]; + REQUIRE(mid > 0.60); + REQUIRE(mid < 0.70); +} + +SCENARIO("the analog decay tapers into sustain, closing 95 percent at the knob time") { + tap::tools::adsr::generator g; + g.prepare(k_sr); + g.set_attack_ms(1.0); + g.set_decay_ms(200.0); + g.set_sustain_db(-12.0); + const double sus = std::pow(10.0, -12.0 / 20.0); + + const int attack_samples = static_cast(0.001 * k_sr); + const int decay_samples = static_cast(0.200 * k_sr); + const auto out = run(g, 1.0, attack_samples + 2 * decay_samples); + + // At the decay knob time past the peak: 95 % of the way down, and still above sustain. + const double at_knob = out[static_cast(attack_samples + decay_samples)]; + REQUIRE(at_knob > sus); // asymptotic — never crosses + REQUIRE(at_knob - sus < 0.07 * (1.0 - sus)); // ~95 % closed (tolerance for the attack tail) + // And still tapering, not parked: strictly decreasing toward sustain. + const double later = out[static_cast(attack_samples + 2 * decay_samples - 1)]; + REQUIRE(later < at_knob); + REQUIRE(later > sus); +} + +SCENARIO("the analog release closes 95 percent at the knob time and ends at exactly zero") { + tap::tools::adsr::generator g; + g.prepare(k_sr); + g.set_attack_ms(1.0); + g.set_decay_ms(1.0); + g.set_sustain_db(0.0); // sustain at unity so the release starts from a known level + g.set_release_ms(100.0); + + run(g, 1.0, static_cast(0.05 * k_sr)); // open and settle at sustain + const int release_samples = static_cast(0.100 * k_sr); + const auto tail = run(g, 0.0, 6 * release_samples); + + REQUIRE(tail[static_cast(release_samples)] < 0.07); + REQUIRE(tail.back() == 0.0); // the stage genuinely ends + REQUIRE_FALSE(g.active()); +} + +SCENARIO("retrigger rises from the current level without a jump") { + tap::tools::adsr::generator g; + g.prepare(k_sr); + g.set_attack_ms(50.0); + g.set_release_ms(500.0); + + run(g, 1.0, static_cast(0.2 * k_sr)); // up to sustain + run(g, 0.0, static_cast(0.05 * k_sr)); // partway into the release + // Re-gate and confirm the largest sample-to-sample move stays at attack-slope scale. + double prev = g.process(1.0); + double max_step = 0.0; + for (int t = 0; t < static_cast(0.1 * k_sr); ++t) { + const double y = g.process(1.0); + max_step = std::max(max_step, std::abs(y - prev)); + prev = y; + } + REQUIRE(max_step < 0.005); // no discontinuity — the capacitor charges from where it sat +} + +SCENARIO("gate amplitude is velocity under the sensitivity control") { + auto peak_for = [](double gate, double sensitivity) { + tap::tools::adsr::generator g; + g.prepare(k_sr); + g.set_attack_ms(10.0); + g.set_velocity(sensitivity); + const auto out = run(g, gate, static_cast(0.05 * k_sr)); + double pk = 0.0; + for (const double y : out) { + pk = std::max(pk, y); + } + return pk; + }; + + // Full sensitivity: the 303 convention lands — accented 2.0 hits twice as hard. + REQUIRE(std::abs(peak_for(2.0, 1.0) / peak_for(1.0, 1.0) - 2.0) < 0.05); + // Half-level gates land softer. + REQUIRE(peak_for(0.5, 1.0) < 0.6); + // Zero sensitivity is the legacy amplitude-blind behavior. + REQUIRE(std::abs(peak_for(2.0, 0.0) - peak_for(1.0, 0.0)) < 1e-9); +} + +SCENARIO("the default threshold hears the sequencer's plain level, and 0.5 is no longer an edge case") { + tap::tools::adsr::generator g; + g.prepare(k_sr); + g.set_attack_ms(5.0); + + // The 808 rows' plain level (0.01) opens the envelope now. + auto out = run(g, 0.01, static_cast(0.02 * k_sr)); + REQUIRE(out.back() > 0.5); + + // The old wrapper's exact-0.5 trap: an accented seq level (0.5) opens too. + g.clear(); + out = run(g, 0.5, static_cast(0.02 * k_sr)); + REQUIRE(out.back() > 0.5); + + // Below the threshold stays silent. + g.clear(); + out = run(g, 0.004, static_cast(0.02 * k_sr)); + REQUIRE(out.back() == 0.0); +} + +SCENARIO("the legacy hybrid curve is preserved: linear attack, dB-linear decay") { + tap::tools::adsr::generator g; + g.prepare(k_sr); + g.set_mode(tap::tools::adsr::mode::hybrid); + g.set_attack_ms(100.0); + g.set_decay_ms(500.0); + g.set_sustain_db(-60.0); + + const int attack_samples = static_cast(0.100 * k_sr); + const auto out = run(g, 1.0, attack_samples + static_cast(0.4 * k_sr)); + + // Linear attack: the midpoint is 0.5, not the analog 0.65. + REQUIRE(std::abs(out[static_cast(attack_samples / 2)] - 0.5) < 0.02); + + // dB-linear decay: equal time steps lose equal decibels. + const int hop = static_cast(0.05 * k_sr); + const double d1 = 20.0 * std::log10(out[static_cast(attack_samples + hop)]) + - 20.0 * std::log10(out[static_cast(attack_samples + 2 * hop)]); + const double d2 = 20.0 * std::log10(out[static_cast(attack_samples + 2 * hop)]) + - 20.0 * std::log10(out[static_cast(attack_samples + 3 * hop)]); + REQUIRE(std::abs(d1 - d2) < 0.1); +} + +SCENARIO("the envelope is silent before prepare and after clear") { + tap::tools::adsr::generator g; + REQUIRE(g.process(1.0) == 0.0); + g.prepare(k_sr); + run(g, 1.0, 1000); + g.clear(); + REQUIRE_FALSE(g.active()); + REQUIRE(g.process(0.0) == 0.0); +} diff --git a/tools/capi/taptools_capi.cpp b/tools/capi/taptools_capi.cpp index 3dece29..a5bacc6 100644 --- a/tools/capi/taptools_capi.cpp +++ b/tools/capi/taptools_capi.cpp @@ -6,6 +6,7 @@ #include "taptools_capi.h" // The DSP cores are the same headers the Max externals compile — no Max/Min dependency. +#include #include #include #include @@ -817,6 +818,65 @@ int taptools_harmonizer_process(taptools_harmonizer h, const double* in, double* }); } +// ---- tap.adsr~ --------------------------------------------------------------------------------- + +using adsr_generator = tap::tools::adsr::generator; + +taptools_adsr taptools_adsr_create(void) { + return static_cast(new adsr_generator()); +} + +void taptools_adsr_destroy(taptools_adsr h) { + delete static_cast(h); +} + +int taptools_adsr_prepare(taptools_adsr h, double sr) { + return with(h, [&](adsr_generator& g) { g.prepare(sr); }); +} + +int taptools_adsr_clear(taptools_adsr h) { + return with(h, [&](adsr_generator& g) { g.clear(); }); +} + +int taptools_adsr_set_attack(taptools_adsr h, double ms) { + return with(h, [&](adsr_generator& g) { g.set_attack_ms(ms); }); +} + +int taptools_adsr_set_decay(taptools_adsr h, double ms) { + return with(h, [&](adsr_generator& g) { g.set_decay_ms(ms); }); +} + +int taptools_adsr_set_sustain_db(taptools_adsr h, double db) { + return with(h, [&](adsr_generator& g) { g.set_sustain_db(db); }); +} + +int taptools_adsr_set_release(taptools_adsr h, double ms) { + return with(h, [&](adsr_generator& g) { g.set_release_ms(ms); }); +} + +int taptools_adsr_set_mode(taptools_adsr h, int mode) { + return with(h, [&](adsr_generator& g) { g.set_mode(mode); }); +} + +int taptools_adsr_set_threshold(taptools_adsr h, double t) { + return with(h, [&](adsr_generator& g) { g.set_threshold(t); }); +} + +int taptools_adsr_set_velocity(taptools_adsr h, double s) { + return with(h, [&](adsr_generator& g) { g.set_velocity(s); }); +} + +int taptools_adsr_process(taptools_adsr h, const double* gate, double* out, int n) { + if (!gate || !out || n < 0) { + return -1; + } + return with(h, [&](adsr_generator& g) { + for (int i = 0; i < n; ++i) { + out[i] = g.process(gate[i]); + } + }); +} + // ---- pitch detector passthrough ---------------------------------------------------------------- taptools_yin taptools_yin_create(int window, int tau_min, int tau_max) { diff --git a/tools/capi/taptools_capi.h b/tools/capi/taptools_capi.h index ef012f6..6429155 100644 --- a/tools/capi/taptools_capi.h +++ b/tools/capi/taptools_capi.h @@ -268,6 +268,23 @@ TAPTOOLS_API int taptools_harmonizer_set_glide(taptools_harmoniz TAPTOOLS_API int taptools_harmonizer_latency(taptools_harmonizer h); TAPTOOLS_API int taptools_harmonizer_process(taptools_harmonizer h, const double* in, double* out, int n); +// ---- tap.adsr~ (tap::tools::adsr::generator) ----------------------------------------------------- + +typedef void* taptools_adsr; + +TAPTOOLS_API taptools_adsr taptools_adsr_create(void); +TAPTOOLS_API void taptools_adsr_destroy(taptools_adsr h); +TAPTOOLS_API int taptools_adsr_prepare(taptools_adsr h, double sr); +TAPTOOLS_API int taptools_adsr_clear(taptools_adsr h); +TAPTOOLS_API int taptools_adsr_set_attack(taptools_adsr h, double ms); +TAPTOOLS_API int taptools_adsr_set_decay(taptools_adsr h, double ms); +TAPTOOLS_API int taptools_adsr_set_sustain_db(taptools_adsr h, double db); +TAPTOOLS_API int taptools_adsr_set_release(taptools_adsr h, double ms); +TAPTOOLS_API int taptools_adsr_set_mode(taptools_adsr h, int mode); // adsr::mode +TAPTOOLS_API int taptools_adsr_set_threshold(taptools_adsr h, double t); +TAPTOOLS_API int taptools_adsr_set_velocity(taptools_adsr h, double s); +TAPTOOLS_API int taptools_adsr_process(taptools_adsr h, const double* gate, double* out, int n); + // ---- pitch detector passthrough (tap::dsp::yin, for the notebooks' pitch tracking) --------------- typedef void* taptools_yin; From 37c6d3314187bca7e492a06e4eaca83c72b9b827 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 5 Aug 2026 11:32:16 +0000 Subject: [PATCH 12/12] Update the Moog recipes for the rebuilt tap.adsr~ The gate contract sentence now speaks threshold rather than the retired 0.5 level, the Moog voice notes the analog default gives its contours real RC curves, and the sequenced-modular chapter's accent caveat becomes an accent feature via the new velocity sensitivity. Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01V6CC6kpK5Lx2YkJWuNNQpw --- book/src/recipes/minimoog.md | 13 ++++++++----- book/src/recipes/sequenced-modular.md | 7 ++++--- 2 files changed, 12 insertions(+), 8 deletions(-) diff --git a/book/src/recipes/minimoog.md b/book/src/recipes/minimoog.md index 4ce7c41..d3673fa 100644 --- a/book/src/recipes/minimoog.md +++ b/book/src/recipes/minimoog.md @@ -31,11 +31,14 @@ gate (0/1 signal) ──┬───────────▶ tap.adsr~ (filte - **Pitch** arrives as note frequencies (floats into each `tap.vco~` left inlet; halve for voice 3's octave-down). The oscillators' own `smooth` ramp is the glide knob — no portamento object exists or is needed. -- **Gate** is any signal that goes above 0.5 and back — `tap.adsr~` reads - the gate by level, per sample. A `tap.303.seq~` gate output (1.0 plain, - 2.0 accented) drives it directly, which also gets you slides for free; - so does a MIDI-driven 0/1 signal, or the `trigger 1` / `trigger 0` - attribute messages for mouse-driven patching. +- **Gate** is any signal that rises above `tap.adsr~`'s `threshold` and + back — the envelope reads the gate by level, per sample. A + `tap.303.seq~` gate output (1.0 plain, 2.0 accented) drives it + directly, which also gets you slides for free; so does a MIDI-driven + 0/1 signal, or the `trigger 1` / `trigger 0` attribute messages for + mouse-driven patching. The default `mode analog` gives the envelopes + below the RC curves a Model D actually had; `velocity` (off by + default) lets the gate's amplitude scale the hit. - **The filter contour** scales into the cutoff's signal inlet: envelope × `amount` (Hz) + `base` (Hz) into `tap.ladder~`'s right inlet. The classic panel's "amount" knob is your `*~`. diff --git a/book/src/recipes/sequenced-modular.md b/book/src/recipes/sequenced-modular.md index 88424d2..3b6fc73 100644 --- a/book/src/recipes/sequenced-modular.md +++ b/book/src/recipes/sequenced-modular.md @@ -88,9 +88,10 @@ single slap and patch feedback around it, or reach for Max's delay objects for modulated regeneration. Glue: an 808 closed-hat row in 16ths from the drum scaffold, mixed low. -Accents in this scaffold are honest but blunt: `tap.adsr~` ignores the -gate's 2.0 amplitude today, so accent color comes from the voice you route -the accent lane to — or from leaning the pattern itself. +Accents land in this scaffold too: turn up `tap.adsr~`'s `velocity` +sensitivity and the sequencer's 2.0-amplitude accented gates hit the +envelopes harder — the loudness contour for punch, the filter contour for +the quack, or both. ## When to leave the recipe