diff --git a/README.md b/README.md index d54c2f2..a569985 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 @@ -28,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** @@ -62,12 +67,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/book/PLAN-recipes.md b/book/PLAN-recipes.md new file mode 100644 index 0000000..eb7bd6c --- /dev/null +++ b/book/PLAN-recipes.md @@ -0,0 +1,140 @@ +# Plan — the Recipes part + +> **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. 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 +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 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. + +## 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. +- **`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). + +## 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. 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. +- **`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. + +**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. 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). + +## 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..39d9fc7 100644 --- a/book/src/SUMMARY.md +++ b/book/src/SUMMARY.md @@ -55,3 +55,18 @@ - [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) +- [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) +- [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) +- [Chords with no keyboard](recipes/comb-drones.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/pitchaccum.md b/book/src/pitchaccum.md index bf5841a..ad44695 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 @@ -101,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/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/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/choir-of-one.md b/book/src/recipes/choir-of-one.md new file mode 100644 index 0000000..57a97b2 --- /dev/null +++ b/book/src/recipes/choir-of-one.md @@ -0,0 +1,121 @@ +# 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 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 + +```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/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/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/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/minimoog.md b/book/src/recipes/minimoog.md new file mode 100644 index 0000000..d3673fa --- /dev/null +++ b/book/src/recipes/minimoog.md @@ -0,0 +1,147 @@ +# 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. 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 +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 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 `*~`. +- **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. 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. diff --git a/book/src/recipes/robot-voice.md b/book/src/recipes/robot-voice.md new file mode 100644 index 0000000..0dec2b2 --- /dev/null +++ b/book/src/recipes/robot-voice.md @@ -0,0 +1,162 @@ +# 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. + +## 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. 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. + +### 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 + (`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..3b6fc73 --- /dev/null +++ b/book/src/recipes/sequenced-modular.md @@ -0,0 +1,106 @@ +# 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 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 + +- **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). 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 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/include/taptools/harmonizer.h b/include/taptools/harmonizer.h new file mode 100644 index 0000000..43c0af6 --- /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/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/fv349NNPgxhZaFuwYAHnnHNOYFYgIYQI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DNdff32jMVx33XX1ZpMZNGgQn3zySZMxz5s3j7///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+jSpUubvE8yJryD2JvtwGZRSYiufyfQc8bEoKrwxbKmf8IRQggh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undu+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/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//7127Nhha0tNTVVCQoLi4uJsj5e73tChQ7Vr1y7bY9zyJSUl2a7EPf7449q8eXOBX9pS2Lct3qz8q7vXFxslFUtR+axSpYrD/t59912nbn+4nrP7cua1cKZP/u0Q3377rW390aNHbY+1dHfMkhQQEKChQ4fqk08+UUJCgp588kmH2zwWLFhgF3Nhxo4dq3nz5mn69Om2Rym62q9fv36qWLGipk2bZmtLT0/XnDlzFB8f79LrXZi3335bCQkJmjhxonr06OHUNte/Bm3btlXjxo1t70nFOU47deqk3bt3a/HixbbbWiIjIxUaGqq//OUvqlevnho0aODK1IBSgSvpQCn20ksv6fz58+rUqZPCwsK0a9cuLViwQJ9//rmkq8/pHjp0qIYMGaLf/e53CgsL04wZM5Samqqvvvqq0P26ut31hg4dqldeeUW5ubl65ZVX7NY9++yzWrx4sbp3764XXnhBFStW1JQpU1SlShW9++67he5z+PDh+vbbb9W3b1+NGTNGzZs316FDh7R48WLt27dPPj4+Gj58uLZs2aLu3bvrqaeeUsuWLXX27Flt2LBBV65c0YoVK5yeg7OioqIUEhKi1157TYMGDZKfn5/i4uJKNJYb5XPs2LHq0aOHhg0bpvvuu0/r1q1TtWrVCr3P+Eac3Zezr0VRfZo1a2Zbf+LECWVnZ2v16tUaPHiwFi9e7PaY8z399NP68MMPVbZsWY0YMcJhzFGjRqlVq1bq2LFjoXF98MEHmjRpkrp166Zy5crZ/UWlWrVqtivOzvYLCQnRhx9+qKeeekrZ2dmKjIzUJ598ooCAAL311ltO5coZycnJttvn6tSpYxfPjZ6THh8fr7CwMN1zzz0KCQnR+vXrtXv3bv3tb3+TVLzjtHPnzsrLy9OpU6fsrph37NhRc+bM0fDhw0tsvoAVUaQDpdi8efO0du1arVy5Ut9++61q166tnTt3qnnz5rY+M2bM0MMPP6zly5frxIkTiouL04gRI+yuwgYFBSk+Pt7uCrkz2xVlyJAh2rZtm3x9fW0fwMvn5+enFStWKCEhQevWrVN2drbGjBmjJ554wu4Dq9d/A6iPj48+//xzPfbYY1q6dKk2bdqk5s2ba8uWLXZXOqdMmaKhQ4fqP//5j9avX69atWppzJgxRV4RvH68evXqKT4+3navfL6mTZsqPj7etlypUiWtXr1aM2bM0DfffKPc3Fz16NFD/v7+TsVS2DjO5rN79+7atGmTEhIS9N1336lnz54aPHiwcnJy7O5rduYbVZ3dlzOvhbOv1+zZszV58mTt2rVLjRs3VkJCgr7++mu7PjfKUUnGnC8yMlJ169ZV69atHf56lJ6ervPnz6t9+/aF5lG6epznHyfXfy4hPDzcVnw720+6+otG8+bNNWvWLK1fv179+/fXqFGjFBwcfMNYqlWrpvj4+EJvc4uLi7PdLuPr66tHHnmkwHiCgoIKLdI3bdqkJUuWaP369fq///s/NWzYUAcPHrSN6ezrJF19vfN/Gbn2i9SGDRsm6er5ANzOfExxP1EEAIAX2LZtm+666y4tX75c3bt3t1u3fPlyPfLIIzp27JiqVq3qoQgB3M64kg4AwDV++OEH7dixQ3/72990//33OxToknT58mX97W9/o0AHcMtwJR0AgGvMnj1bS5YsUXh4uH7729+qSpUqng4JgBeiSAcAAAAshkcwAgAAABZDkQ4AAABYDEU6AAAAYDE83UVXv4o5LS1N/v7+hX4lNwAAAHCzjDHKzMxUcHCww/czXIsiXVJaWprtK70BAACAWy0lJeWGj3GlSJfk7+8v6WqyAgICPBzNrWWMUVJSkkJDQ/mrwX+RE0fkxBE5cUROHJGTgpEXR+TEkbfkJCMjQyEhIbb6szAU6ZLtQAgICPCKIj1/nrfzCVAc5MQROXFEThyRE0fkpGDkxRE5ceRtOSlqjnxwFAAAALAYinQAAADAYijSAQAAAIuhSAcAAAAshiIdAAAAsBiKdAAAAMBiKNIBAAAAi/Hoc9KNMdq+fbvOnj2r1q1bKzQ0tET6Hz9+XDt37lTbtm0VFhZ2K0IHAAC47XV5ZrfbxvKRUf3qGTqWfEZG7nlO+uqPotwyjis8diX90qVL6tixo/r27au//OUvaty4sWbMmHHT/bOzs9W/f38NGDBAmzZtupVTAAAAAG4JjxXp77zzjpKSknTgwAFt2LBBH3/8sUaPHq3k5OSb6j9hwgR16NDhtv/mUAAAANy+PFakf/XVV3r88cdVqVIlSdKgQYNUoUIFLVu2zOX+W7du1bx58/TWW2/d+gkAAAAAt4jH7kn/8ccf1bhxY9tymTJl1KBBAx05csSl/pmZmRo+fLimTJmiwMDAG46dnZ2tnJwc23JGRoakq/e8G2NcnlNpkD/H232exUFOHJETR+TEETlxRE4KRl4clZac+Mh98V0dy7h1TE/k39kxPVak5+TkqHz58nZt5cuXV3Z2tkv9x48fr/vuu0+dOnUqcuw333xTEyZMcGhPSkq67W+TMcYoLS1NkuTj454PZVgdOXFEThyRE0fkxBE5KRh5cVRaclK/eoYbRzMKrZz133+7JydJSUluGeda+ReHi+KxIr1GjRoOiUlKSlKNGjWK3f/w4cOaPHmyPv74Yy1cuFCSlJubq61bt6pOnTqKjY212278+PEaN26cbTkjI0MhISEKDQ31iiJdkkJDQy39puBO5MQROXFEThyRE0fkpGDkxVFpycmx5DNuGyv/Cvrx5AC3Pd2lqCcL3gqWL9I7dOigZcuWadSoUZKkI0eO6PDhw+rQoYMk6fDhw/rpp5/UvXv3IvsbY9S9e3fNnz/ftv/s7GytXbtWwcHBDkW6n5+f/Pz8HGLy8fGx9IlSUvLn6Q1zdRY5cUROHJETR+TEETkpGHlxVBpy4q5i+X98/nvDi3vG9UTunR3TY0X6+PHjdffdd2vs2LGKiorSP//5T/Xr10/R0dGSpPnz52vKlCk6duyYU/3zr6Dnq1ixol5++WU9/PDD7pwWAAAAcNM89nSXFi1aaMuWLcrNzdXKlSs1cuRIzZ4927Y+IiLCdhXdmf7X69Onj2rVqnVL5wAAAADcCh79xtEWLVpo0qRJBa7r37+/+vfv73T/692ogAcAAACszGNX0gEAAAAUjCIdAAAAsBiKdAAAAMBiKNIBAAAAi6FIBwAAACyGIh0AAACwGIp0AAAAwGIo0gEAAACLoUgHAAAALIYiHQAAALAYinQAAADAYijSAQAAAIuhSAcAAAAshiIdAAAAsBiKdAAAAMBiKNIBAAAAi6FIBwAAACyGIh0AAACwGIp0AAAAwGIo0gEAAACLoUgHAAAALIYiHQAAALAYinQAAADAYijSAQAAAIuhSAcAAAAshiIdAAAAsBiKdAAAAMBiKNIBAAAAi6FIBwAAACyGIh0AAACwGIp0AAAAwGIo0gEAAACLoUgHAAAALIYiHQAAALAYinQAAADAYijSAQAAAIuhSAcAAAAshiIdAAAAsBiKdAAAAMBiKNIBAAAAi6FIBwAAACzG40X6sWPHtG3bNl2+fLlE+v/000/at2+fMjMzSzJMAAAAwG08VqRnZWWpf//+atmypR577DGFhYVp0aJFLvfftGmTWrVqpQceeED9+/dX7dq1NW/ePHdMBQAAAChRHivS//GPf2jnzp06evSoDhw4oIkTJ2rYsGE6d+6cS/1PnTqlefPm6dChQzp48KAmTJigYcOGcUUdAAAApY7HivSEhAQ98cQTqlatmiTpySeflK+vr5YtW+ZS/0ceeUTh4eG2/vfee68yMzOVlpZ2aycCAAAAlLCynhr40KFDatKkyf8CKVtWDRs21KFDh1zuf+HCBf3www9KTU3Vu+++q1GjRumOO+5w2Fd2drZycnJsyxkZGZIkY4yMMTc9NyvLn+PtPs/iICeOyIkjcuKoNOWk27O73TKOj4zqVc/Q8eRfZOTjljFXTopyyzg3ozQdK+5SWnLiI/fFd3Us49YxPZF/Z8f0WJF+5coVBQQE2LUFBgbqypUrLvc/fvy4XnnlFaWmpury5ct6/vnnC9zXm2++qQkTJji0JyUlOYxxuzHG2P664OPjnh8gVkdOHJETR+TEUWnKSf3qGW4aySi0ctZ//+2enCQlJbllnJtRmo4VdyktOXHfuSN5y/mTf3G4KB4r0qtVq6azZ8/atSUnJ9tuZ3Glf4sWLbRhwwZJ0vr169WpUyft2LFDUVH2VxnGjx+vcePG2ZYzMjIUEhKi0NBQryjSJSk0NNTSbwruRE4ckRNH5MRRacrJseQzbhkn/wrg8eQAt11JDw0Ndcs4N6M0HSvuUlpy4q5zR/Ke88fyRXr79u21atUqjRgxQpJ08uRJHTx4UO3atbMtnzlzRjExMU71v3z5sgIDA237b9euncqVK6eff/7ZoUj38/OTn5+fQ0w+Pj6WPlFKSv48vWGuziInjsiJI3LiqLTkxF0/8K/y+e8f7N0zptVzn6+0HCvuVBpy4t5zR/KG88fZMT1WpI8bN07333+/3njjDUVFRWnixInq3Lmz2rdvL0n64osvNGXKFB07dsyp/n369NGDDz6oqKgoXbx4UZ988onCwsJ03333eWqKAAAAgEs89nSX2NhYrVq1Svv27dOHH36oLl26aMGCBbb1derU0V133eV0//nz5+vy5cv6xz/+oX//+9/q0KGDtmzZosqVK7t1XgAAAMDN8tiVdOnqYxLvvffeAtcNGTJEQ4YMcbp/cHCwXn/99RKPEQAAAHA3j11JBwAAAFAwinQAAADAYijSAQAAAIuhSAcAAAAshiIdAAAAsBiKdAAAAMBiiv0Ixg0bNmjVqlXas2ePzp07p0qVKikiIkKdOnVS9+7dVbasR5/qCAAAAJR6Tl1Jz8vL08yZM9WkSRP169dP27dvV8OGDdW5c2c1bdpUJ06c0JgxY1SnTh399a9/VWZm5q2OGwAAALhtOXXZ+7PPPtPChQs1adIkderUSb6+vgX227Ztmz7++GP98Y9/1HvvvVeigQIAAADewqkifdiwYRo5cmSR/WJiYhQTE6Ps7OybDgwAAADwVk7d7uLn51esnRa3PwAAAID/cfnpLnPmzNF3330n6ertMLVq1dKjjz7KVXQAAADgJrlUpB8/flx/+tOf1Lp1a2VlZekvf/mLPvzwQ+3Zs0dffvllSccIAAAAeBWXivRNmzbprrvuUrly5bR9+3Y98MAD6t+/v4YNG6adO3eWdIwAAACAV3GpSPf399fJkyclSStWrNA999wjSbpw4YKCgoJKLjoAAADAC7n0zUOdO3fWqFGj1L59ex07dkx79+5Vbm6uli5dqpkzZ5Z0jAAAAIBXcalIr1y5srZv365Vq1apQ4cOqlq1qo4dO6aXXnpJkZGRJR0jAAAA4FVcut0lMTFRGzdu1MiRIxURESFJql+/vurUqaNZs2aVaIAAAACAt3GpSN+3b5/Wr1/v0L5nzx5t3LjxpoMCAAAAvFmxbndJSUnRiRMndPLkSaWkpGjXrl22ddnZ2Vq+fLliY2NLOkYAAADAqxSrSJ8/f76eeeYZGWNkjNGCBQts6/z9/dW6dWsNHz68pGMEAAAAvEqxbnd56qmnlJOTo1mzZum1115TTk6O7b/09HQlJiYqLCzsVsUKAAAAeAWXnu4SHx9f0nEAAAAA+C+XPjgqSZMnT9add96poKAgVaxY0fbf888/X4LhAQAAAN7HpSvpO3fu1EsvvaR//vOfioyMVJky/6v1Q0NDSyw4AAAAwBu5VKTv3btXffv21ahRo0o6HgAAAMDruXS7S0REhH799deSjgUAAACAXLySHh4erszMTL3xxhvq3bu3ypUrZ1tXtWpVnvACAAAA3ASXivS5c+dq48aN2rhxo15//XW7dU8//bSmTJlSIsEBAAAA3silIn306NEaPXp0SccCAAAAQDfxCMZ8Fy5cUEpKSknEAgAAAEA3UaQnJiaqefPmqly5ssaPH68jR44oLi5OxpiSjA8AAADwOi4V6cnJyerfv79+97vfaeLEiZKkRo0aydfXV4sWLSrRAAEAAABv41KRnpiYqHvvvVcjRoxQ5cqVbe2xsbFav359iQUHAAAAeCOXb3fx9fV1aLtw4YJCQkJuKiAAAADA27lUpMfGxmrNmjXavn27re306dOaMWOGOnfuXGLBAQAAAN7IpUcw1qpVS3/961/VoUMHVaxYUcYYffHFF3r22WfVrl27ko4RAAAA8CouFemSNGrUKHXr1k2JiYm6fPmy2rZtq9atW5dkbAAAAIBXcrlIT01NVYUKFTR06FBJ0sWLF3X69GmFhYWVWHAAAACAN3LpnvRLly6pa9euOnfunK3NGKPevXvrp59+KrHgAAAAAG/kUpG+atUq1a9fXxEREba2oKAg9e3bV//+979LLDgAAADAG7lUpBtjlJWV5dCenZ2t7OzsYu3r/PnzOnbsmPLy8kqkf3Jyst0VfgAAAKC0calIb9u2rdavX68VK1bY2g4cOKCpU6fq/vvvd2ofubm5euqppxQaGqq77rpLdevW1bfffuty/4ULF6pFixaKjIxU/fr11bp1a+3evduV6QEAAAAe5VKRHhYWpr///e966KGHFBERoRYtWqhly5YaMmSI089JnzRpkpYsWaJDhw4pOTlZzz33nB555BGlp6e71P/777/XnDlz9Ouvvyo5OVktWrTQoEGDXJkeAAAA4FE39QjGLl26aP369bpy5UqxH8H4xRdfaMSIEapbt64k6YUXXtDbb7+tZcuW6ZFHHil2/7feesvWt1y5cho4cKBmzZqlnJwclS3r8jQBoNTp8ox7/oroI6P61TN0LPmMjHzcMubqj6LcMg4AeNpNVa8NGzZUw4YNXdp2//79euGFF2zL5cuXV6NGjbR///4S6f/ll1+qffv2BRbo2dnZysnJsS1nZGRIunqvvTHGpfmUFvlzvN3nWRzkxBE5cVSacuIj98R4dRzjtvEkuZx/cuJZpen8cZfSkhN3Hsvecv44O6ZTRfrixYt15swZDRs2TOXLl7/hoIsXL9apU6c0ZsyYG+4zIyNDFStWtGurVKmSLl++fNP9P/jgAy1ZskSbNm0qcF9vvvmmJkyY4NCelJSkgICAG8Zd2hljlJaWJkny8XHPlS+rIyeOyImj0pST+tUz3DSSUWjl/IcIuCcnSUlJLm1HTjyrNJ0/7lJacuK+c0fylvMn/+JwUZwq0lu1aqUXX3xR48aNU1xcnO655x6Fh4crKChIly5d0vHjx/Xdd9/pq6++Uv369fX+++8Xuc8qVaooJSXFri0lJUVVq1a9qf7vvfee/vrXv2rNmjV2j4i81vjx4zVu3DjbckZGhkJCQhQaGuoVRbokhYaGWvpNwZ3IiSNy4qg05eRY8hm3jJN/tet4coDbbncJDQ11aTty4lml6fxxl9KSE3edO5L3nD8lWqTXqVNHc+fO1cGDB/XZZ5/po48+0t69e5WVlSVfX1+Fh4erY8eOmjt3rtq1a+fUwPlPiBk+fLgk6ddff9WBAwfUtm1bSVe/0fTcuXNq1KiRU/0l6Y033tDUqVO1bt06NW3atNCx/fz85Ofn59Du4+Nj6ROlpOTP0xvm6ixy4oicOCotOXHXD7erfP77x2n3jOlq7smJ55WW88edSkNO3HvuSN5w/jg7ZrHuSW/SpIkmTpyoiRMnSpIuX76sgIAAlyb40ksvqUePHoqJiVFUVJTeeOMNRUdH67777pMkTZ06VVOmTNGxY8ec6v/KK69oypQpmj17tqSrj4SUpMaNG/PBUQAAAJQqLj2CMV9gYKDLv4F06tRJ8+bN0/z58/Xss8+qQYMGWrp0qcqUuRpSSEiI7Sq6M/03btyoO+64Qy+88ILi4uJs/11/iwwAAABgdR69xNynTx/16dOnwHWjRo3SqFGjnO6fmJhY4vEBAAAAnsB9IAAAeCF3PU9fcv8z9XmePm4HLt3ukpaWVioe+QQAAACURi4V6QsXLtTrr79e0rEAAAAAkItF+p133qlDhw6VdCwAAAAA5OI96eHh4crMzNS4cePUr18/u28CrVq1qsLCwkosQAAAAMDbuFSkz507V5s3b9bmzZv1zjvv2K17+umnNWXKlBIJDgAAAPBGLhXpo0eP1ujRo0s6FgAAAAC6yS8zkiRjjHJyckoiFgAAAAC6iSJ979696tq1qwIDAxUQEKA2bdpo9erVJRkbAAAA4JVcKtIvXryoHj16qGbNmlq8eLFWr16tHj16qG/fvjp48GBJxwgAAAB4FZfuSU9MTFSdOnU0c+ZMW9t9992n1NRUffXVV/rDH/5QYgECAAAA3salK+nnz59X3bp1Hdrr1q2rtLS0m40JAAAA8GouFenR0dFatmyZtmzZYms7ceKEpk+frrZt25ZYcAAAAIA3cul2l4iICP3+97/Xvffeq8aNG6t8+fI6cOCABgwYoAEDBpR0jAAAAIBXcalI3717t+6++27t2bNHmzdvVlZWllq3bq3Y2NiSjg8AAADwOi4V6QcOHNCKFSs0bdo03XnnnSUdEwAAAODVXLon/a677tL333+v7Ozsko4HAAAA8HouXUm/cOGC/P391bZtW/Xq1UsVK1a0rWvdurUeeOCBEgsQAAAA8DYuFem//PKLQkNDJUm7du2yWxcUFHTTQQEAAADezKUivUyZMurdu7dGjx5d0vEAAAAAXs+le9KvXLmijRs3lnQsAAAAAORikd6+fXvt2LFDJ0+eLOl4AAAAAK/n0u0uW7duVVZWlpo2baqYmBi7D4727NlTzzzzTIkFCAAAAHgbl4r0mjVrauTIkQWua9So0U0FBAAAAHg7l4r0Vq1aqVWrViUcCgAAAADJxSJdkvLy8jRr1ixt3rxZbdq00QMPPKCDBw+qS5cuJRkfAAAA4HVcLtLj4uJ09OhR1ahRQ7m5uXrsscf04IMPaunSpapXr15JxggAAAB4FZee7rJx40YdOnRIO3bs0MCBAyVJ5cuXV8+ePfXFF1+UaIAAAACAt3GpSD969KhiY2NVrlw5u/bQ0FClpaWVRFwAAACA13KpSG/UqJG2bdumvLw8u/YNGzaoadOmJRIYAAAA4K1cuie9Xbt2qlKlinr16qXq1avrzJkzGjNmjHbs2KF///vfJR0jAAAA4FVcupLu4+OjJUuWKCIiQtu3b9fhw4d17tw5JSYmKjAwsKRjBAAAALyKy093CQ4O1vvvv1+SsQAAAACQi1fSAQAAANw6FOkAAACAxbh8uwtKTpdndrttLB8Z1a+eoWPJZ2Tkc8vHW/1R1C0fAwAA4HbDlXQAAADAYriSDkvirwsAAMCbcSUdAAAAsBiKdAAAAMBiKNIBAAAAi/H4Pem5ubnKyMhQxYoVb6p/Zmam0tPTbctVq1ZVmTL8DgIAAIDSx6NV7B//+EdVrlxZISEhatGihbZv3+5y/88//1xNmzZVeHi4qlevrp9//vlWhw8AAADcEh4r0qdNm6apU6dq06ZNSk9PV8+ePfXQQw8pIyPDpf5PP/20zp49q82bN7tzGgAAAECJ81iRPn36dI0YMUItW7aUn5+fXn/9dZ0/f17Lly8vkf4AAABAaeWxe9L37NmjZ5991rYcGBio8PBw7d27V3FxcTfd/0ays7OVk5NjW86/Gm+MkTGmeBMpAT5y35hXxzJuG9PVfJITz8o/F0pDrO5SmnLirmPZ3eeOZP33FHJyo7F4n71WaXlPuZ2PE8kzx4qzY3qsSL98+bIqVapk1xYUFGT34c+b6X8jb775piZMmODQnpSUpICAgGLv72bVr17wLT63hlFo5az//vvWf3FPUlKSS9uRE88yxigtLU2S5ONz63NSGpSmnLjv/HHvuSOVhvcUclIw3mevV1reU27n40TyzLFS2K3d1/NYkV65cmWdO3fOri01NVXBwcEl0v9Gxo8fr3HjxtmWMzIyFBISotDQUI8U6ceSz7htrPzfTo8nB7jl2zVDQ0Nd2o6ceFb+b/mhoaGW/uHhTqUpJ+46f9x97kjWf08hJwXjfdZRaXlPuZ2PE8kzx4rli/To6Ght3rxZw4YNkySdO3dOBw8eVHR0tKSrE8jMzFSVKlWc6l8cfn5+8vPzc2j38fHxyInirgPxf3z++8ekWz+uq/kkJ56Xfz6UlnjdobTkxL3nj/vOHam0vKeQk4LxPnu90vCecjsfJ5JnjhVnx/TYB0d/85vf6PPPP9fcuXN18OBBjR49WhEREerUqZMk6f3331fr1q2d7p+dna2zZ8/a/nR07tw5nT171u7ecwAAAKA08FiR3qdPH02ePFlvvvmmunTpotzcXC1btkxly169uB8YGKiqVas63f/7779X06ZN1bt3b4WEhKhbt25q2rSpdu/e7ZH5AQAAAK7y6DeOPv7443r88ccLXDd27FiNHTvW6f733HOPzp49W+IxAgAAAO7m0W8cBQAAAOCIIh0AAACwGIp0AAAAwGIo0gEAAACLoUgHAAAALIYiHQAAALAYjz6CEQBuRpdn3Pc9CD4yql89Q8eSz7jtm/BWfxTllnEAANbDlXQAAADAYijSAQAAAIuhSAcAAAAshiIdAAAAsBiKdAAAAMBiKNIBAAAAi6FIBwAAACyGIh0AAACwGIp0AAAAwGL4xlEAAADd3t9izDcYlz5cSQcAAAAshiIdAAAAsBiKdAAAAMBiKNIBAAAAi6FIBwAAACyGIh0AAACwGIp0AAAAwGIo0gEAAACLoUgHAAAALIYiHQAAALAYinQAAADAYijSAQAAAIuhSAcAAAAshiIdAAAAsBiKdAAAAMBiKNIBAAAAi6FIBwAAACyGIh0AAACwGIp0AAAAwGIo0gEAAACLoUgHAAAALIYiHQAAALAYinQAAADAYijSAQAAAIuhSAcAAAAsxqNF+nvvvafatWvL399fnTp10sGDB2+qf3H3BwAAAFiRx4r0hIQETZgwQTNmzNDJkycVHh6unj17Kisry6X+xd0fAAAAYFUeK9KnTJmi4cOHq3PnzqpWrZreffddnT59WitXrnSpf3H3BwAAAFhVWU8NvHv3bj355JO25aCgIEVERGj37t3q1atXsfsXZ3/Z2dnKycmxLWdkZEiSjDEyxpTYHJ3lI/eNeXUs47YxXc0nOfGs/HPB6rHezseJZP3zh5wUNg45KXgs67/PkhNHt3NOJM/8THZ2TI8V6RcuXFDlypXt2oKDg3XhwgWX+hdnf2+++aYmTJjg0J6UlKSAgIBizaMkfPHaHW4byxijtLQ0BQcHy8fH55aPl5SU5NJ25MTRq5N/KuFIbsQotHKWks7/JOnW50SS/jKmQbG3uZ2PE8n65w85cUROClZa3mfJiaPbOSeS63m5GfkXh4visSI9KChI58+ft2tLS0tTUFCQS/2Ls7/x48dr3LhxtuWMjAyFhIQoNDTUI0W6O+X/9hYaGuq2E8DqSktOjiWfcdtY+VcxjicHyLipSA8NDXXLOK4qLceJO5ETR+SkYOTFETlx5C05sXyRHhUVpa1bt+qxxx6TJF28eFGHDh1SVFSUS/2Lsz8/Pz/5+fk5tPv4+NzWB0W+/Hl6w1ydVRpysuqjVm4byxijpKSk2/6NsrhKw3HibuTEETkpGHlxRE4ceUNOnJ2bxz44Onr0aP3rX//SmjVrlJKSohdffFFhYWHq1q2bJGnixImqX7++0/2LWg8AAACUFh67kj5o0CCdOnVKQ4cOVUpKiu6++24tXbpU5cqVc6l/cfcHAAAAWJWPsfrjG9wgIyNDgYGBunz5slfck85tDPbIiSNy4oicOCInjshJwciLI3LiyFty4mzd6dFvHAUAAADgiCIdAAAAsBiKdAAAAMBiKNIBAAAAi6FIBwAAACyGIh0AAACwGI89J91K8p9C6ezXtJZmxhhlZGQoIyPjtn68UXGQE0fkxBE5cUROHJGTgpEXR+TEkbfkJL/eLOop6BTpkjIzMyVJISEhHo4EAAAA3iAzM1OBgYGFrufLjCTl5eUpLS1N/v7+t/VvbtLV395CQkKUkpJy239xk7PIiSNy4oicOCInjshJwciLI3LiyFtyYoxRZmamgoODVaZM4XeecyVdUpkyZVS1alVPh+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//HFPh2Mpx48fN2XKlDEbN270dCge8frrr5vY2Fi7try8PNO4cWMzbtw4W9vDDz9sHnzwQXeH5xHz5s0zFSpUsGvLzc0106ZN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9Mj41+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//nPf7Bnzx6cdNJJAICrr74aEydOBODzKH/wwQd4/fXX8fe//z3ieXNzc2G325Gbm4uSkpKwx0mSFHKsDJfu3/72N93luuCCCwAAt956K15++WU8++yz6NChAwDgwgsvxPfff6+kYbSszZo1Q7NmzQAALVu2xN133423334b1157ra6y5+fnY8CAAXjkkUdw6qmnwm634/777wcAVFdXw+v14ujRo3jyySexcOFC9O7dGwsXLsSwYcOwZcsWFBQUQBTFkKHS5TCwoVi8eDE+/vhjzbba2lqlvW02m5LnlStX4sEHH8SqVavQqlUr5XibzUbNgRUL3MDncDgJRzbw3W43JEmis5otN/BjQq62qkYHRCLpjoPP4USiqKgIN910E9X04qFt27bKZznanlqP3b17d83x3bt3x969e+NKU02rVq1CTgyNN902bdoon2XPeOC2ysrKmNNcu3YtHnjgAWzbtg11dXVwuVzo2LGj7vwBwOuvv47JkyejpKQENpsNt956K3Jzc9G8eXPYbDZkZGTgqquuwkUXXQTA92Zg0aJFWLZsGSZPngxBEEKGSpcfPEJxySWXYO7cuZpt48aNCzrul19+wZVXXol33nkHPXr00OyrqKgI+dYlVeAGPofDSTjJWGWR68djxF9vvP44icRms8XlUU81ZF27zP79+xWDLzMzUyOVCVxkU09YxH79+mHt2rW60pUN8GjpxkqksqppbGzEiBEjcP/992Pu3LnIz8/H22+/rTGc9ZS9S5cuWLVqFTweDwgh2LRpEx555BEMGjQIANCrVy9kZWlDIGdmZsLtdiMzMxNdu3bFxo0bcf755wMAjhw5gkOHDqFnz55h08zMzAx6qxAYQn3fvn0YM2YM5s6di7PPPjvoHBs3bkT//v2jli9ZcFcNh8NJOLJhn5WVRcd7Dz7JNlbkamuZ3Yx77zmcMCxatAgbNmwAIQTvvfcevvnmG4wdOxYAcPLJJ+Odd96B2+2Gw+EICrXYsmVLZcJoOC666CKsW7dOY7DHm64ZZVVTV1eHhoYG9O3bF2VlZXA4HHjxxRc1x+gp+6JFi7B+/XrY7Xbs2bMHU6dOxZQpU9C+fXsAvkWlXn/9dezYsQMA8Oabb2Lv3r0YPnw4AF8UnmeeeQa7du2Cy+XCzJkzccIJJygPCLFQXV2NkSNH4vbbbw/p2QeAFStW4MILL4w5DbPhozmHw0k4soHvdDp5HPwUR55ke8hRB5Gkrp6Uw0kml19+Oa677jrk5ubi5ptvxqJFi9CtWzcAwL///W/s3bsX+fn5KCsrC/J233zzzXj33XdRUFAQNopOjx49cMopp2Dp0qW607333nsjpmtGWdW0aNEC999/P84//3zk5eXhnHPOwYABAwyX/ayzzsL06dORnZ2N/v374y9/+QueeeYZZf+NN96Iv/71rzjjjDOQk5ODmTNnYvHixcqbjDvvvBMXXHABevbsiby8PGzcuBEffPBBXM6lpUuXYsuWLXjggQdCRtHZuXMndu3ahcsvvzzmNMxGIMd52ASn04mcnBw0NDTwuPlpCCEE5eXlcS+3zkksVVVVeOaZZ5Cfn4/bbrst7ECbiPb7y82bAAD/vbETBp3CVgxpGry1axPWlu9Ft4IWuLnHQFh0tgO/9tKbRLWfy+XC7t270aVLF2RmZiYwh+ZRW1sLu92uxMKvqalBZmamRgZSVVWFgoIC2Gw2nHvuubjssstwyy23wOVyhS2n0+lUzllZWYmioiLN2FdbWwtJksJG+1u7di1uu+02JfqLOl/qdAkh8Hq9sNlsEAQhbLqB5RJFEceOHdNIUxwOByRJUvTqesuqRpIkNDQ0IC8vT3mbEFjGaGWX85KdnR22P0qShMbGxrC2msfjgdvtRm5ubsT81tXVQRCEII1+bW0trFYrcnNz4XK5QsbKz8/PR0ZGBqZMmYJevXrhtttuC5lGpOvC4XAgNzdXKa9ZcA0+h8NJOLLfICMjg0t00oTmmdm6jXsOJ53Jz8/XfA+1uFRxcXHI30YyeNXGWqioMYHpBnLWWWdh+fLlIIRAEARNvmJJN7BcVqs1KF+RHJt6H9gsFgvy8vIA+Mb8jIyMoGOilT1aXuR0Ih0jT46OhpzXQNR5zMzMjFj+Rx99NOUXJeMSHQ6Hk3BkA7++vl6ziIq5aVJJhjnkattTdxTeFA75xuEcDxQVFfE3YmlA8+bNqTmvYoV78DkcTsKRDfzs7GyKHnxu4ceGr95a5+RxDz6HE4KlS5emjfwoXo6nsrION/A5HE7CkY1tWotcAXyhq1iRqy3Hagc37zmcYFJdipFIjqeysk5qv1/gcDhpiWzgyxOr6KRJJRnmkNtqa3UFRF6JHA6HwwTcwOdwOAlHNhrz8/O5RCfFkWvtpMIWsHKJDofD4TABN/A5HE7CScZKtty+jw3BL8xxS3QmQ3M4HA7HfLiBz+FwEo5s2Dc0NFCT6HANfmxY/E77P+uruUSHw+FwGIEb+BwOJ+GoJTq0Jtpy2zQ25Goryy+GLcXDvnE4xyterxcOhyPZ2eCkEXw053CSzPY/HNi2l62BWzbwPR4PxUm23MKPBbnaql1OSLwOOZyUQpIkTJw4EQUFBTjttNOSnR1OGsHDZHI4Sebmh38HAKyc1zvJOUkcsrHtdrupGd5cohMfNe5GX1vxibac44z6+no0a9Ys5D6HwxHSSZGTk2M4gEBjYyOsVquu1VZlvvjiC6xbtw7l5eVh85iqNDQ0UF0LhaOF1zqHw0k4slHfrFkzqrHwObHgX+gqNx9WfiPmHGc0NjYiLy8P9fX1Iff37dsXrVq1Uv61aNECeXl52L59u+G0xowZg2effdbQb3799VeceuqpaWfcA0BxcTF++umnZGfjuIWP5hwOJ+HIBr7T6aQ3yZa78GNCrrVKZwNEQqetOJx0YcuWLaivr1f+/e1vf8Ppp5+O7t27R/ydKGqjUrlcLoiiCLfbjfr6el16epfLhcrKSlgsFtTX18Ptdmv2E0JCjq9OpxMej0fJh9fr1QQ8CMxbuPM4HA7U19ejsbExZP4indPpdCp/6+vr4XK5IpY18Pd60uBEhhv4HA4n4SRDD8/l4/HBq4/DiYzb7cbChQtx4403hj3m6aefRuvWrZGTk4OePXti+fLlAIAZM2ZgzZo1mD17Nlq1aoXBgwdHTW/atGl44oknsHTpUrRq1Qp33303AODIkSO48sorUVhYiIKCAowePRr79u1Tfjdy5EjccccdGDRoEIqKirBo0SIUFBRg5syZ6Nq1K7KystC7d29s2bIFkydPRl5eHvLy8jB79mxN+vLbi8LCQrRr1w7z58/X7C8oKMDDDz+Mbt26ITs7Gz169FA89ueccw5cLheGDx+OVq1aYfr06SHLuGnTJpx55pnIy8tDcXExbrnlFs3DT6Q0OJHhGnwOh5NwZAM/Fp1qzGlSSYVdirNyYBW4z4eTGB5Y+Af+PBzZa5soOrTKxL+u66j7eLfbrXjDZc9yQ0ODsj8jIwMZGRlBv3v33Xfhcrlw1VVXhTzvoUOHcPvtt2Pt2rUYNGgQduzYgZdeegnDhg3Dk08+ic2bN2PMmDG4/fbbdeVzwYIFaNWqFXbu3InFixcr26+99lqIoohdu3YhMzMTU6ZMwdixY/Hdd98p4+1bb72FZcuWoV+/fgCAqVOn4vvvv8e6devQrFkzXHTRRejbty8ef/xxPP/889i8eTMGDBiAyy+/HKeccgoA39sLwDeer1+/HqNHj8YZZ5yBvn37Knn5/PPP8dVXX6GkpAS33HILbrvtNqxZswbr169HVlYWvv76a/Tp0ydk+err6zFy5EhMnDgRK1euxKFDh3DhhRfiX//6F5588smoaXAiw0dzDoeTcGQDv76+ntprVcIlOjEht9VhRy1ESnIqDieZyF70Vq1aoWNH34NBWVmZsk32lAcyf/58TJgwAbm5uSH3Z2ZmIjs7W5GnnHjiiXjooYcSmvfKykp89tlnePjhh1FSUoL8/Hw8/fTT+OGHH7B161bluMmTJyvGvcysWbPQsmVL5OTk4OKLL0a7du1w0003wWaz4dRTT0X37t3xyy+/BKXp9Xpx8skn48ILL8Snn36q2Td79my0bt0adrsdEydOxK+//qq7LCtWrIDb7cacOXOQlZWFzp0745577sGiRYsSlsbxDPfgczichCMbjRkZGRAoRWXh9n1syNWWY6PXVhz2MeJRp83DDz+Mhx9+GIBvkm12djYOHz4ccSLr1q1b8fXXX2Pu3LlhjykqKsLy5csxd+5c3HXXXejYsSNuu+02nHvuuQnL+8GDBwEAnTp1Ura1atUKmZmZOHDgAE4++WQAQLt27ULmTyYzM1PzXd6m1tv/5z//wfPPP4/y8nJkZWXB7Xbjuuuu0/ymuLhY+ZyVlRVWrx+uLO3atYPN1mSKdu7cGdXV1XA4HMjJyYk7jeMZbuBzOJyEIxv4mZmZ9CQ63MCPizx7JizcwOdwQjJ//nwMHDhQka+EY9CgQRg0aBAAYNWqVRg+fDj27duHli1bwmKxBM1P8nq9cLlcYd8KBNKhQwcAwO+//65IZfbu3QuXy6W8jUgEK1aswNy5c/Hll1+iV69eAIDrrrvO0BvZUOVV06FDB/zxxx9wuVzIzMwEAGzbtg0lJSWKcc+JHS7R4XA4CUce1Kurq+lJdLiFHxd/1lfDyyU6HE4QTqcTr7zySsTJtQDw7bffYsqUKdiwYQOqqqpw4MABiKKojE1t27bFhg0bcOzYMWUi6YIFCwwZ5oWFhbjssstw++2347fffsPOnTtxww034Nxzz0W3bt1iL2QAHo8HoiiisbERFRUVeOONNzTzAPTQtm1bfPvtt6itrQ0ZRWfo0KFo3rw5br31Vuzbtw/ffvst7rnnnqj1zNFHWhj4P/30Ex577DHlX21tbdAxDQ0NWLx4MZ555hn8+OOPScglh8ORUcfBp+XB5xKd2CB+kU7L7FxYuQefc5whCAJyc3MjytPef/995Obm4oorroh4rgEDBuDMM8/EjTfeiJNOOgnPPPMM3nnnHZSWlgIA7rzzTuzevRtlZWVKFJ1du3Zh2LBhYc+ZmZmJrKwszbYFCxbg1FNPxUUXXYShQ4eiXbt2WLJkibI/Ozs7aJJw4Jokdrs9yEuek5OjLMI1YsQITJkyBZdeeil69uyJpUuXYuLEiZq8BJ7TarVqZE6PPvoo5s+fj/bt24eMopOVlYXly5ejsrISAwYMwOTJkzFp0iTcc889utPghEcgaeD2WrNmDZYuXYqjR49i4cKF2LNnj0Z/VlFRgUGDBqF58+bo0aMHli5diunTp2PWrFlRz+10OpGTk4OGhgb+SigNIYSgvLwcpaWlaasf/svNmwCwtZLttm3b8NZbb6F169a4/vrrw7ZNItpPrr+bxrbBZX9pEXOej1de+X0DfqjYj5Obl2LqSf11twML197xTKLaz+VyYffu3ejSpYsis+Do5+yzz8aLL76Irl276v4NIQRerxc2m41feylKpOvC4XAgNzcXDocD2dnZpuUhLTT4gwcPxuDBg7Ft2zYsXLgwaP+cOXPQvHlzfPPNN7DZbFi5ciWGDx+OiRMnJlSTxuFw9CH7DY4ePQpJkqisZpvynooU58/6aoiEwMYNBg6HGl9//XWys8BhlLQw8KOxbNkyTJs2TZmJ/Ze//AWtWrXC559/jhtuuEFzrMfjgdfrVb7L4awIIVzDm4bI7ZaubafOd7qWIRTyyoNFRUUQBCFs2RLZfpKUvv0gmch11iG3EBbo74fpfu0d7ySq/eTf875AF3W9c1KPSNcFrTZLmoH/3XffYe3atWH3n3TSSRgzZoyuc/3555/KzHKZ9u3b488//ww6ds6cObjvvvuCtpeXl3OJThpCCEF1dTUApOWrSkklHC8vL09iThKL3CaNjY0oLy+PKNFJVPvV1tahvJxPEjWKHHKuvtERsa0CSfdr73gnUe3n9XohiiK8Xi+VN3UcX9vJwQv4tZeayNdFZWWlJgwoAM1KvWaSNAO/oaEBhw8fDru/devWus9FCAnq5OHCM82cORMzZsxQvjudThQXF6O0tJQb+GmI3MbpqgN2eyQARwAALVu2TMsyhKKiogKAT4fYokWLsDf+xLSf78GoWbNmKC1tGeM5jl8ya/cD9UCt5EVJy5aw6ZwUne7X3vFOotrP5XKhrq4ONpstyJDhmIs8IZaTeoiiCKvVipKSkpAafBok7Wr8y1/+gr/85S8JOVfbtm1x4MABzbYDBw6gTZs2Qcfa7faQF4UgCPwmlabIbZeO7aeO/EIgMBeHvKCgIOpNP1HtRwj3ZsVD29x82A16YNP52uMkpv3k3/J+QA+1U5PXeWoS6bqg1WZpESYzGsOGDcO7776reCR++OEH/Pnnnxg6dGiSc8bhREYdIl4U2dFSytdiY2Ojosc3P00qyTCHXG11HhckXokcDofDBGnxPm3fvn146623lNf+L7zwApo3b46rr74arVu3xqxZs9CvXz+MGTMGp5xyChYtWoRbbrkloYs+cDhmIKpc+CzFcZcNfI/HQ21CEUPVlxScXq+vrbhHkMPhcNKetPDgu91uHD58GKIoYvr06XC5XDh8+DA8Hg8A33LHv/zyC4YOHQqr1Yr//e9/ePrpp5Ocaw4nOmqvPYse/NzcXGoT77j3OUb81VaSlQsrpUXJOBwOh2MuaeHBLysrw2OPPRbxmJYtW+KOO+6glCMOJzFoPfjsGKiyge9wOCBJEpXVbAkPoBMT8kq2x1wOiESCVeBGPoeTauzbtw8Oh+O4VCaIoog9e/YgKysL7dq1A+CLOldRUYGTTz6Zz0MIAx/JOZwkIqqMUrUenxVoDrwsSZySAb9Jcjiph8fjwdlnn42BAwdi2rRpyc4Odfbu3YuysjKMHDkSTz31FABg0qRJ6NmzJ8aPH68oOTjBpIUHn8NhFbU+XWLIQpXLlZmZScV770+VUjpsUpCRxb33nOMOQgi2bNmCHj16hByrduzYAbfbHbS9rKwM2dnZhtLau3cv8vLyUFxcrPs3H3/8MaqqqvDHH3+k3ToDv/32G7p06YKsrKyYzzFv3jwMHToUCxYsUM65dOlSHDhwALm5uYnKKpNwA5/DSSJqk1Rk0MCvr69X4gGbDaVgPcwh97ojznqIksR1+JzjCpfLhV69eqGurg7NmjUL2n/rrbdqwnDX1NRg//792LVrF7p06WIorSlTpmDMmDG4/fbbdf9m+/bt6N69e9oZ9wBw+umnY+3atejTp0/M59i2bRvOO+88zfdOnTpx414H3MDncJKJyqYXGTRQMzIyqHnwGZrCQBd5QrQ9g8t0OJwAPv/8c833m2++GVu3bo1o3NfX16OiogIdOnRQDPODBw8qC3xu3rwZmZmZ6Nq1a8S09+/fjz179qChoQGbN29GcXGxZhHQqqoqiKKI0tJSze/27NmDgoICFBUVYf/+/cjNzcXBgwdRVlYGm82GP//8E23btlUWYDp06BAsFkvQeeS3F3a7HZ06dQpasGnLli3KOffv3482bdogIyMDALBz504QQrBr1y5kZWWhqKgo5NpE6rLm5+cjPz9fk/7hw4dRUVGBzZs3AwC2bt0Kr9eLzZs3Iy8vDx07doxYh8cz3FXD4aQItMJJ0kAui81mo2Y0EgoSnW3btuGFF14wPZ1kkGOzM7fQGoeTSBoaGvD6669j6tSpYY+ZPn06SktLMWzYMLRq1QqLFi0CALz44ov49ddfsWjRIowfPx7Tp0+Pmt6zzz6L999/H99++y3Gjx+PhQsXAvAZz4MGDULXrl3Rs2dP9OzZE7/88ovyu+uuuw633HILOnfujKFDh2L58uXo3bs3pk6divbt2+Oss85C+/btsWLFCgwdOhQDBgxAly5dcM0112jSv/XWWzF+/HhccMEFaN68Oe6++27N/t69e+Ouu+5C+/btcc4556C0tBTLly8HANx1113weDyYOXMmxo8fj+effz5kGb/44gu0a9cO/fr1Q9u2bTFmzBhUVVUp6W/ZsgULFy7E+PHjMX78eDz33HPYtWsXxo8fjwcffDBqHR7PcA8+h5NE1DY9O+Z9E3V1dUxJdFauXInKykrzE6KI3O8ONtTCK0mwcYkOJwEs2rEB5c46KmmVZudh0oln6D7+8OHDynUs6+u3bt2qaOoDPeUyr7/+OjIzM3HppZeGPO+ff/6JJ598Ert27UKnTp1QX1+Pl156CQAwe/ZsrF692pBE58EHH4TVasXOnTuxePFiZfvEiRPRtWtXfPPNN7DZbLjttttw+eWXY/PmzbDb7QCAb775BmvXrlWizlx11VVwOp34448/YLfbMW7cOIwYMQIffvghRo0ahQMHDqBbt264+eabMWDAAADatxf79u3DoEGDMHToUPzlL39Rth86dAh79+5FZmYm7rnnHvzzn//EsGHD8P777yMrKwuLFy8OK9GprKzEFVdcgfvvvx+33HIL6uvrMXLkSNxxxx145ZVX8Pnnn+Pcc8/FZZddhltuuQUA8PLLL+OZZ57Bjz/+qKsOj2f4SM7hcBKO7MHPzs5mSqJDb8IwPeQ3H8WZObByD35M1NR7mZokzzqyF338+PGYOHEiAF9kFnmb7CkP5Pnnn8df//pXRYYSSPPmzVFQUICVK1cqmv6//e1vCc37oUOH8P3332P27NnKG9L//Oc/2LFjB7Zs2aIcN2nSJMW4l7n11luRkeGT4g0ZMgTdunXDqFGjAABt27ZFt27dsGPHDs1vHA4Hdu3ahZqaGgwaNAirV6/W7L/tttsU6c7IkSPx+++/6y7LqlWrkJ2drUQHatasGWbMmIH3339ff4VwwsI9+BxOEiFhv6Q3soFPU9NNo/pYNPAPV3kAAThy1JvsrKQlBytcmHjvNlw1vCUmXxTs9T1eMeJRp82MGTMwY8YMAEBjYyOys7Oxfv36kJNsZdavX4+ff/4ZS5YsCXtMXl4efvjhByxYsABjxoxBY2Mj/va3v+Hqq69OWN7lNw9qvXxhYSEyMzNRUVGhbGvRokXI/MnY7XbNd3mb/EbD6/XihhtuwOLFi9GqVSvk5OTg8OHDKCgoiHjOUBGHIpWlZcuWmvtEaWkp6uvr4XQ6DUcp4mhh727F4aQpDEnwFerr6yFRCm9DYw6DbOCzNF+i0eVbgMFhcUBkqFy0KD/qi8P93iq2pFscLfPnz8ewYcMiTq51u90oKyvDgw8+iNWrV2PRokWYOHEi9u3bB8A3JylwPDx27Bi2bdumOx+dO3eGxWLBpk2blG1btmyBy+WKOmnXCJ999hk+//xz7N+/H7t378bmzZsxdOhQQ+N5qPKqOeGEE7B7927U1TVJuX766Se0bduWG/cJgBv4HE4S0WjwGTKu5LLk5uaaqr/XriNgWjIKsoEvMrQqmVyDNlc219/HQH6uFfmd6uEm/A0Iq1RXV+Ott97CjTfeGPG4TZs2YdiwYXj33XexYcMGvPvuu8jOzla83J07d8bKlSvx888/K1KWt956C2effbbuvDRr1gzXX389brrpJnzyySdYsWIFJkyYgMsuuwydOnWKuYyB5Ofno6amBitXrsQPP/yABx54wLB0pnPnzvjggw/wyy+/4ODBg0H7zzvvPJSVleGqq67CmjVr8Oabb2LWrFm46667ElWM4xou0eFwkgoJ8YkdRFEEIcQ0qY7PvicAJSWQ2sC32dgaPolFhEQIj6RjkIOuarQ7qxINh2NfzIeTPCwWC04++eSIjoiVK1fitNNOwwUXXBDxXH379sW//vUvzJs3T1mB9csvv0RhYSEA4F//+hdmzJiByZMno127dvjwww+xefNmjB07Nuw5S0tL4XK5NNvmzp2L//u//8MTTzwBr9eLSy65RJEcAT7DOnAxrZ49e2q84kVFRSgrK9McU1ZWhqKiIgDA2WefjUceeQRPP/003G43zj33XMyaNQterzfsObOzs3HyyScr3+fPn485c+Zg2bJluPjii3Hfffdp0rNarVi1ahX++9//4p///CcKCgrw2GOPYdKkSWHL0rx5c5xwwglh64vThEBYchvGgNPpRE5ODhoaGpCTk5Ps7HAMQghBeXk5SktL0zKG977yRlx733YAwMJ7TkSHVmy8lvzuu+/w+eefIyMjA//4xz/C3jzjbT9RJJjywRdo1roRXfedgb+Naxf9R3GwaNEi7N27F3feeSczC63868vVqMuqhsVjx+ODR+j24qf7tZcovt55CEuOrAeRgGfOuijZ2dFNotrP5XJh9+7d6NKlS1CcdE50LrvsMsydOzdk1J5wEELg9XqphiHmGCPSdeFwOJCbmwuHw2GqFIktFxSHk2awLtHJzMw0V6IDoFnrRgCASMyXzTAt0fFkcolODNgFX50JvOo4MfDOO+8kOwscRuFDEiduvCI7hmkyYcnAl/F4PKZOslWHJnTZXBGOTAwsGviyiS9ZPZAY7INmw6NjcjicVIQb+Jy4OFzlxvBbf8GHX/MIErGg9eAnLx+JRn5YoRVBBwAkgXvw44EIhMpqwKzB0nXL4XDYgRv4nLg4UOHzmj61+ECSc5KeqG0DFj34drvd1Njxau8pDeNULot6olm6I3c7qzcDVq4zMQyL1y2Hw0l/+GjOiQu7jU/wSRQsGQpyWdxut6lefNphMuUJbSx68EWbGyKh98aFFST+1oPD4aQg3MDnxAW3B+JEZRuwqH82O8KDpsoEeh58tgx8/6rDhD+sxwKL120s0JTjcTipTio47HgUHU5cJL8Ls0MqDAiJQi6L1Wo1VaJDkvSAxFRb+f9aJBuX6MQAQ10hJjIyMmC1WnHw4EG0bNkSdrudh240GTlMpiiKvK5TEEIIKisrYbFYYLfbk5YPbuBz4oIlQycZqHXjhKFwHGqJjiiKpoXKpD1JWS4Xi/1etLnglSQeKtMgx7sHXxAEdO7cGYcOHcL+/fuTnZ3jBvW4KkkEhABWKzf2UwWLxYL27dub6uCKBjfwOXFxnN/b4iZZHmhaWCwWcz34jK8ETAO53gTRxlexjQHe73yT6du3bw9JkpiagJ6qyB7ikpISCIKA6U/uRPlRD1697yTu0U8RzA4woQdu4HPigiGnMyeByB5ui8Vi6g1HLfulEUWHZQ++FVZu4MeAxAdBAD5PvtVqNXVhO44PQghsNhsyMzMhCAK2/uEFIACWDGRm8DdwRpEkgrdXVGDkoCIUNGPHLOY9gRMf/N4WF6yuZCsjS3RoQFOiwxa+MnnsjfDyiZKGYbFHcNKTegdLk//p8dWGarzwwSE8tOjPZGcloXADnxMXLMpKkgVLxiOtSbbq/kej/lj04MslsXkyYeUefMMQHkqMkyJwAz82Gpy+equuY0texg18TlywY+YkH5acp7QMYM0bEIoSHQ5HhncJTqpQ7+QGfiyI/muYNf8GN/A5ccGdV4mDReNRFEWTF7pSfTYtlVDpMtRW/qJ47S6ILJWLElyCz0k2Nn/0HO7Bjw05gp3FwpaFnxYG/i+//ILLL78cxcXFKC0txZVXXokDBw5ojvm///s/tGvXDllZWRgyZAi2b9+epNweX/B7W3ywqsFXT7I1c9JdssJksojdm8lDZMYAy32Ckx7InmcumY0N+SGdMfs+PQz8Bx54AFdeeSV+//13rF+/HkeOHMEVV1yh7F+8eDHuu+8+vPLKK9i/fz+6du2KUaNGwe12JzHXxwf85hYfmjCPDNalJEmmlkt9bh5FJ0Zk4wAiNxBiQOJuDk6KwJLMkyYiox78tIgHtHjxYuVzUVER/v73v+PCCy+E1+uFzWbD/Pnzce211+K8884DADz22GMoLS3F8uXLMXr06GRl+7iA2wOcUKgNYUmS6Cx0xTX4cSFaRV/5WBOimgzDXYLDOS4gjHrw08LAD2T16tU4+eSTYbP5sr9p0yZMmTJF2Z+fn48TTzwRmzZtCjLwPR6PZiEOp9MJwHfjZvnmbRbqGNDJqD+53dK17dSr14ome7tpIpdDEARYLJaw5Yq3/QL7n9n1J5/f7DcTdPFHPPJmwCIIusuV7tdeoqAdySlR8PZLX8K1ncTbMybk+4iR8S8eaLVR0gz8+++/H7Nnzw67f9y4cRrPvcxHH32EZ599Fp9//rmyrba2FgUFBZrjCgsLUVtbG/T7OXPm4L777gvaXl5ejpycHCNF4ACorm5UPpeXl1NPnxCC6upqAEjLFfyqjnqUz8eOHkMSqtAU6uvrAfja59ChQ2FDZcbbfhXVTZPK3B6P6X3Q5XIBAKqrq5PS381A9L/XFwUPDh0+rHuxq3S/9hJFXX094H9BlU59grdf+hLYdrKBeuxYNcrLGyP8khOK2toGAIDH66ZyDTscDtPTAJJo4M+aNQuzZs0y9JulS5di0qRJeOedd3DWWWcp2/Pz81FTU6M5trq6Gvn5+UHnmDlzJmbMmKF8dzqdyuRdbuAbJ/9ANQBf3ZeWllJPX34SLi0tTcubVI3LAeAoAKCgsCApdWgGubm5yufS0tKIBr58TCztJ1pdcvXBZrObXn92ux0AUFDATltZtmzxfRCAlqUtYRX0Tc1K92svUeQcaAB8z31p1Sd4+6UvgW0nCEcAEP+4VJjUvKUjObnlAOqRlZlB5Rpm3sA3yptvvombb74Z7733nqK1l+nduzd++OEHTJgwAQBQV1eHHTt2oHfv3kHnsdvtyk1aje8i4YOcYVR1lqz6k9suPduvKc8++XM6liEyFoslYrniaT8B6t8QavWXvv0tPBbRBpvF2FyJ9L72EkXyx8BY4e2XvqjbrmnOU/r1wVRAFsxYLHSuBVptlBZRdBYsWIBbbrkFy5YtCzLuAeDGG2/Eyy+/jC+//BJVVVWYPn062rRpg2HDhiUht8cXEg8CnTgY0k6qNYZmxsFXdz8eRSc+JJsHIl/YwjA0+h3rfPnjMbz7ZUWys5G2kIC/HGPItyi98sR0IS08+LNmzcLRo0dx5plnarbv27cP7dq1w/jx43HgwAFMnDgRVVVVGDBgAJYtW4aMjIwk5fj4gQ8o8aG2E1l9VjI3TKbqs2mpqNNjsZH8ZZIsAW9EOHrgoUXjZ85LfwIAxp7XIsk5SW94V4yNpnVbkpyRBJMWBv7hw4ejHjN9+nRMnz6dQm44aviAkjhYMh7VZTHzdaQmDj7Fha5YaisZQbIw58GiAXs9gZN2+Dshg8MSFVj14DP2vMKhDR9QOKFQG8CiaN7y6bTj4LOIXGuS3QMvXynHMHwM5KQKvC/GhvwWTmd8gbSBseJwaMOiJ5MmWq06m3VprgfftFOHSY9hD77XypwHiwYs9gVOeqFo8HlfjIkmD35y85FouIHPiQs+niQOljzQtG406jqTGKq/ZCAQLtGJBd7vOKkC74kcNdzA58QFo05naqirjzBameqVoxONRlFCsfpY9JSJGW4u0YkF9roCJ80gXIMfF/LkWtZuwdzA53BSBJaMRnVZwi1ylfA0uaUVF4LHDiv34BuGR9HhpAos3UOSAWtRgrmBz4kLVnXjtGB1PNZGtzGvkGrjikZVyvMJWLqR8gej+GCoK3DSHH47jg35GmbtYZ0b+Jy4YOtySAKaOPhs1ia9KDrmw5JhHwixeyAyXD6z4Bp8TsrAu2JMsCpx4gY+Jy5YuyCSCUt1qTaErVarielovpmWTnC6DDWWH4vHDhtrK71QgL2ewElXeF+MD9acbHw058QFY9cDdTSTbBmtTO7BTw+IIDF3g6MBy32CNrwu44PVQA1mwz34HE4I+ICcOFiqS218f/NmLtHS+kdKlxWIVWKyXGbD5zAkDm6fxgevvthoWkcgqdlIODEZ+FVVVWH3/f777zFnhpN+sHZB0CZZBipNzIyiQyJ8MyU9RtsIACxeG6xcomMYbpQmDh60IT549cWGPK6z1v9iGs2XLFmCK6+8EnV1dcq2+vp6XH311XjiiScSljlO6sOwvUMdlgYXah581alp1h5Lhr7sgSYWESJrceJowE5XSDp8GYY44X0xLhi6BQOI0cC//PLLUVNTgz59+uDXX3/Fr7/+ij59+qCqqgr33XdfovPISWFYMnSSAau1RwihElKSdv0x3d95CPyY4FF04kPt2GDJyZEM+Bya+GCt/8Vk4BcXF2PZsmW49tprMXDgQAwaNAgTJ07Ep59+ihYtWiQ6j5wUhrHrgT7qSaKMDc5y9BzBxMWTtHHwuQY/LrwWWAUu0TEMi32BIl6xqf5EXpVxwbtibPBJtgE4nU5s27YN+fn5sFqtqKurMzVaBscYdXV1qKysTHY2OAZgaXBRG8Cmjgs8ik7C8FrcEBnSSIiiiNWrV5sqEQO4kyNeRJF78BMFw8OTqcj1dqSCLZspJgN/165d6NevHw4ePIiNGzdiw4YN+OKLL3DeeefhwIEDic4jJwaefPJJPPvss6anQ3s8rqiogNfrpZuoiRAC2HO9sOd6mTMezfTcyyTLHmCtrQAAIp02o8WWLVvw1VdfYefOnaamQyhXmdPpRE1NDd1ETUTttWfo+TIp0HJyfPDBB6iurqaQGl0cDkeys5BQYjLwv/zyS4wdOxaff/45WrZsibKyMnzzzTfo3r077r///kTnkRMDZnutZGgbOvPmzcMXX3xBNU2z6XrJfnS9ZD9zRqMcPcdMo1EbB59H0YkFJUScKMDCkIEvvzky+6FFHXucRv947rnn8OSTT5qeDjWI/B/hHvw4odH/3G43Nm3ahNWrV5ueFi2a6o2t/meL5UfXXnst7Ha7ZltWVhaef/55/PnnnwnJGCdNoHg9yA8tx44do5eoybC60JV6kq2Zb1ySVWcstZXcCy2ZBF5JYmY1W7mNzH8roTbwAbOTU0evYwECgi6jDyKruQciOTnZ2Ukoe/fuhSiKKCsro5IejWFJvp5oORFpwNJoriamkTzQuFfToUOHmDPDST9oOlw8Hg8AwGaL6bk0JVEPyCw5r9QGPq04+NyDHx+SG7Ay5MGnZeCrzRx2e4d5EAJkNfeN7Tt37kpybhLLokWL8Nprr1FLj8bwJF9XLM25lAhBQed6CDa2ruCY77zff/89zj//fJSWlsJut8Nms8Fms2HatGmJzB8nxaF5OcgGfqQHTE7qIBv2pobJTJITiWVDnxWoefA1GnLeL+Lhl182JzsLaUmztg6UnnGUyrjEooHfkFWDtmdWonlfF1Nje0wGfkVFBUaPHo1Ro0ZhypQpuOSSS/DCCy+gXbt2uPXWWxOdR04KQyje0NxuNwC2PPja1/vsDCxqD76ZNwK115578OPDkgWIDJWPngdfFQWGofqjhbrKmjXLS15G0pgOQ46guHstlf4nS3NYkuiIVr86oJnE1INLTAb+2rVr0a9fP9x+++3o0KEDCgsLcd111+Hiiy9mbgIkJzLJ8OCzZeA3wZrxSEOiw6PoJA6pkUt0Ykuo6SM38OMjOyc32VlIa7ww3zhl0YOvOIcIWw8uMd15jxw5omjtCwoKlEmPnTp1wq5dbGnoOJGheT9j0YOviQLDkHFAayVb2nHwWUQJ88iObQ+A3vWk9uAnSzKWzmgjYTHWCf3QMho9MD+EtHxdsWQIKzF0uIGvHTh79+6Nr776CmvWrMG7776Ljh07JixznNRHJBJannYUtmzzBxYWNfgsR9GRPfdmenq0Hnx6Eh2W2kquNksGmxIds9tKfXaRW/iGUUvrGLKtNNAaL7wC9+DHAhEoLcxImZhcoX369EG7du0AAN27d8e1116LkSNH4vTTT8fkyZMTmkFOalNnrUXJybUo6NRgelryhWem5COZMGRbAWhqJ1Oj6LBWacnAf3OT3AIzITIBiga+6vy8O8YHr7/48MJjehqyh5slQ1jpeJLAlAc/ZgNfzaOPPopHH300IRnipBn+9/v2XFEjyzAlKQa9pyxLdGTMHDC1r/fNh8U+KCNYCCRCmFnsKhlSAnZMA3poQwWzd10B5o8XkleAxUYgUuiBLEt0ALbKlTZi5h07dmDZsmVwOBzo378/hg4dqtl/5MgRvPHGG6isrMTAgQMxevToJOX0+EIi2s9WNmyDpMDarU323NMy8NmrQcpY/Tdvxgx88yU66odZ3gcNo6kyNvpeIKY7BOS3cDxMZkzI1zDX4PtZvXo1rrrqKpx99tk466yzlH+PPfZYIvMHAJg/fz7Gjx+PQ4cOoba2FhMnTtRIgf7880+ccsopWL58ObxeL66//nrcdtttCc8HJxT0XKgsek011cdQ+dQafFoSHe7Bjw/iFWBlUKJj9g1b+xbO1KSYRDsPKWnZ4OiExTGQqD6w9OASkwd/+/btGDlyJG644QYMHjxYI8s4+eTELzU9ZMgQTJ06VUln5MiRGDJkCB555BEUFxfj/vvvx0knnYSPP/4YgiBg7Nix6N+/P6ZNm4YTTzwx4fnhNKH14BNYTfTAsDiwqGGpWLQkOqy+0k8GgpVAJBKsAhtGfjI8+HySrXG0Mjs2r2dqEZ0oxsE3PfwsVdj04Mdk4H///fcYPXo0nnzyyQRnJzTdunXTfHe73cjKykJGRgYAYPny5Zg+fbrS4fr27YsOHTpg+fLlQQa+x+OB19sU8cXpdALwXYAsGo40J5hJkrl1qL5hB35O17bzqgaTdC5HIGoPviRJYcsVb/upJREE5tdfqD7ICgL85dJpZKX6tadekIfGuORLi159xJtOqrSfdpJy8vNjBonug4FtJ5vaNMZAtYHPSls1xcEXIIoiVbvJTGIy8Nu1a4f6+vq4El65ciU+/fTTsPtPO+00XH311cr3vXv34plnnsHRo0exfv16vPbaa8jL8616d+DAAbRt21bz+7Zt2+LgwYNB550zZw7uu+++oO3l5eXIycmJtTgpS3l5uanndzY6lc+Hy48g027eU7283kJDQ4NSLkIIqqurAaSnR+FotVMRytXV15neXrRwuVzKq85jx47BarWGPC7e9jtW4wSylbOZXn9ymWpra5lpK8nvdSaigMojFbp/l+rXXl1dHQBf/zOzrVxuN+C/dRypqAQaM0xLS028ZUqV9jta2ySJcDidzFxXasrLy5GZmZmw84Vru8ZGl+n1d/ToUQCA1+tlpq08Xn/0IQJUVFSYfj04HA5Tzy8Tk4E/ZMgQzJ07Fw899BBGjRqleNIBoHnz5igtLY16jtzcXLRq1Srs/oKCAs13u92OVq1aISMjA16vFx999BEuueQSWCyWkE+SkiSFbKSZM2dixowZynen04ni4mKUlpYyaeDraYt4yMw6pnxu0aIlsjPNe70vDyy5ublKueR2Ly0tTUkjIxoFFccAnx2CnJwc09uLFhkZGcrCZAUFBWHLFW/75f95FMraLoL5/V1+K5GXl8dMWwm/CSAABDtBSYsWunX4qX7tyeN5fn6+qW1lt+9XPhcVF6O0OZ37SLxlSpX2E+wuoNL3OTMrm5nrSk3Lli2RlZWVsPMFtd1O3/aMzExq9We325lpK5ttr+8DAQoLC00vV0ob+F6vFy6XC3fffTfuvvtuzb6pU6di/vz5Uc8xYMAADBgwQHeabdu2xZ133gkAuOuuu9CqVSuMGzcOI0eORIcOHfDnn39qjt+3b5+y2q4au90ecqEkQRBS8iYVL2aXKfBNE40wmYHpyG2Xju2nWQUTqekJjRW5LNHaJp72C3zRSbP+WGorACASFIeJXtLh2jM9fK/6Gib0+kUi0kmF9tNMshXYu65kEl2u0G1nbl8PlT4LyKt5E5g/XgD0+nhM7tbPPvsMW7Zswa+//gq32w2Px6P8mzdvXqLziG+++UbzvaamBl6vF7m5uQCAUaNG4Y033lC09StXrsThw4cxfPjwhOeFo0UTIo6SHI8V3R+gnRTF0oRRQogiyzFzMKNdZ0xP9JYEZmLgA8mJ183qJFEz8WoiYbFZf/TmZZifBkuTUJsgyh+WyheTB9/hcOCcc85Bz549E52fkCxYsAB33XUXevfujbq6OnzyySe46qqrcNZZZwEAZs2ahUGDBuHMM89Ejx498MEHH+Dee+9Fx44dqeTveEYzcFEKk8mScSWqJ9kydHNTe0HUk9oTjSixbxzQQrATeCWJqdVsAdpRdExNiklYdXKooWbg00hDntjLkjNA/kvYKRMQo4Hfv39//Oc//4Hb7dbo783ipZdewqZNm/Ddd98hOzsb//znPzXhOFu0aIGNGzfiww8/RFVVFaZNmxa02i7HHNQDitmDM4sGPqs3N1px8GmvK8RiH1QWefECVoZu2jI04+AzFeuWErTXsmAZGk4OFg18NSyN7TEZ+AcPHgQhBL1798aQIUM0Rv6ZZ56Jyy+/PGEZlOnduzd69+4ddn9ubi6uvPLKhKfLiUwyFnlh6QJULy3OmoEv3wBMDVFIYWl2TnrCV7JND2g6iZKF6WFaZQ05hepj0sD31xtLRQJiNPA9Hg8GDRoEwBeTXo6WAfjC43FSB9oTzMyESe8poxITtQbfzJUBRQlNM4kEet4rlvqgjMUOiITAxthdjqamltv3xtG8xWRoDFRjroGv+kyh/ljSqLNOTAb+Oeecg3POOSfReeGkIVyiEx9a/S5D5VIZ+OFi4CcCSXNz48SD5BGY0t/TGi+0kbB4LzSK1knE688ovuhr/s8U6o9JD76MwFYfZGc054TEfP0pPQ9+qDTTHY33hYIHmhbqN0dm9kFCVOemMDiz+JCpIBAmJRI0PY4sPaTTQuMkYvQBydTxQnMPMS8ZJQ0G+7hSIsaeWbiBzzjm60+bMPv1NIvGlVpDzlK51AvNmSnRkbT2PZ/jGAeCjU0NtPkPfeovpibFJpp5XGxWoLnzkMJ9MSk9Jj34bPY7buAzDksRJJg08Bk1DgghsNl8CkAzo+hoPKYCf4sUG3IUHTYlOtyDn9qoq4xVdbfpk2zlz6alEpweSwa+XG+CQJga29kZzTkhoRpBgnvwDaMuC0veU3oSHe0TEq15IEwh36ctbEp0aI6BNKuPlb7Io4zGh+YBiUIFMj3Jlp1nFgAxTrKV+fbbb/Hdd9+hrKwMgwYNQlVVFbp165aovHESAIs3N1YHGJYm6NEKk6le6ErgHvzYUIWI8/VBNu5y9MJkNiERiqvmmhwhjRbq0KIszUNSQyuKDg0fPpMefM1cQnb6YMwe/Ntuuw0XXnghXnrpJXzyySew2+246KKLUFVVlcj8ceKEpkSHT3A0jkSS4/0zG3UUHXPDtKqgYOCz1PcU5OaRAKvAX+oaJRmBBgLTZQUWywTQ0+DzOPhxwliRYhrNN27ciPfeew/btm3DtGnTAAAFBQUYPnw4Xn755UTmjxMn5g+Y9G5uLA7+mjj4DBVP7V00NQ5+QKXRkpiw2BdhAUSKHmizSYZDgGYcfHb6oEqmmMRcpCvJ0uAzhRDwlxFiMvA3b96MIUOGoLi4WLO9Y8eOOHDgQEIyxkkP1Dc0Wjc3lgYYEuFbOkMIUSbXmtlempVDBWJ6FbLU94JguGhmkqw47qz0Rc1aFoyUKRBaYTJpXMSyKoApD74sUwRbfTAmA79NmzbYvn170PZNmzahrKws7kxxEgeLHnyWLkB1pbFULEmSlCg6ZqIJoiPwh8xYIKoPLEp0qHrwKT4lsdIHaco8kwU1iY5pqajSYFCio9QbO0UCEKOBf9ZZZ6Gurg7Tpk3D77//jqqqKjz++OP47LPPMG7cuETnkZPCaPV/XINvFPUraXZKRU+iEyjJ4TKxWPDfsK2AyNAEdlptpTFQKVYfK8EGNG9AkpgPMzH1LSblBySWx0DWDPyYXGwZGRn4+OOPceutt+LLL7+Ex+PBnj178NFHH6GkpCTReeTEAS2jG+De05ggRBlUWIuiI0+yNffmpnbh06tDpvqgH0LY8srRQh35hWaYUVb6IO1JosxBQn40LzkGHW3qt5gslSsmA//tt9/Gb7/9hmXLlkGSJHg8HmRmZiY6b5w0IBkefFY8VwC7Nzf1QldmpyMjQLuyrdnpMQcBLAwZ+NTCZGrmIdFzqDDTF1kdBFWYK9EhIT+blh6jbcQiMUl0CgoKsHXrVt8JLBZu3KcwdCd9mX1+Bj0HLN6w4SuLXB6v12taOhqDXiA8Dn4cCFbAy9DDMz2SIzFhpQ9qDVR2HjDV0IuDbz4s3odlWCtRTAb+mWeeiR07duDbb79NdH44aQbNGNAsDiwSwwa+1Wo1XfIROKmRr2QbA7JETASs3INvPB3VZ5r9j5U3mZo5DMyZWD5oGfj8ATM+fIslslOumN6hf/TRR9i3bx8GDRqE0tJSNGvWTNl31VVX4T//+U/CMshJbWje3JQ0GboAGSqKBnmSrSAIphoi2jCZoHaHY6kPKrBj21MmSRYWI2juGyxeVyZDOwoRi2MfeyXyEZOBP3DgQCxYsCDkvs6dO8eVIU5iMd97xT348cFmBAl1W5lp4NMOk8lW39MiWHwLh9kY8uLTIFkefBb7IhvvJIKhpcGnCVv9T75fsVWumAz8Tp06oVOnTgnOCifd4Qa+cViNAS1JEqxWK+x2u7npBC4Vxt8ixQyRAJuFnTj4SVnJ1mRji8V+p4bV8tGT6HAPPqcJdkZzjgJNL49WQ25qUkySrFUwzYaWVpj2JFuW2igUNMM8sgLNt5iadBlpK00xGCkTVbgGP27YKYkWbuBzEgZf6Mo4hCRpdDYBUSTwito2kiTJXImOqtJ8E6RMS0qbLkN9UEawsGXgJ8WDzyd5G0bSyBTZlIfRWsmWxj2ExT7YVHECU+XjBj7j0I0gYWpSbBr4ms/pXa4rZ/2GUbf9AqApio7ZIXSlgE7HkoFKD6L8YUmiQwsS5rPp6TLS1zVvnNN8DAwHtZVsKdYfK/1PA2PPl3w0Z5Bkxb5n8Xo3G+3NLb2pqvFC9Dvr5XKJoghRFE1LU/NuQDC/Dll8yFTf1ETC6jRHM1HL0bgHPx5YLZ6p7Ua50ljsg+yVyEdMk2wbGxshSRJycnIgSRLeeecdlJeX4+KLL0b79u0TnUdOHJh+MVJcpp1F44oky/1nMnKYTMBcDT4JqEBun8YBY96rZMTBp/WAGfiZc/ySrHUEWOx/AghT5TJs4M+cOROPPPIICCGYPXs26uvrMW/ePGRkZGDOnDnYunUrmjdvbkZeOTqh68GnpyFn6cJTYPT1tFqiY+ZiV+pnB5phMpnqi/JDOgGsAn+paxjNW0z+hGkUjcSEpetKBS0NPo3aY7KN5DIx5uQwNJpv3boVTz31FF555RUsW7YMb7zxBj777DMcOHAAR44cQffu3fHmm2+alVcAgMvlwuHDh+FyuYL2eTweVFdXm5o+JzxmG1cyLA0wanOAoWJBkiQQQuByueD1ek1LR/NQJPi2cGJEYEuiQ8+DTy+KDosefJqroScLcyU6YT6bDCv9D4DKsD+OJ9n+/PPPGDVqFK688koMHz4ckyZNwumnn47CwkLY7XZccMEF2Llzp1l5BQCMHz8erVu3xkcffaRsI4TgH//4BwoKCtC6dWt0794d69evNzUfqQzNmwDNMI8sXXhNsOfBlyTfa06LxQKbLSYVoP60AvqEiWogAKx68NUfGXNhUYadx6PkwMoYGIi5k2zp3kOYHANJ0AcmMGTg19bWoqioSPleVFSE7Oxs5XtOTg4cDkfichfAK6+8ArfbjdzcXM32BQsWYOHChfjxxx9RV1eHSy65BBdffLGpeeH40DgPuDzCMGqHKSvlcnubDPzMzExqNzdQDJPJKha+im0MqAwsipNsWRkvGJ2GRA1NnfHLNyaIXG+M1Z9hwaXb7UZ1dTWqq6vhdDqDvpvFgQMHcM899+D5558P2rdw4UL89a9/RY8ePWCz2TB79mzU1tbi888/Ny0/qQzVm4Dq9Fz/bJxkLZJjJi63T55DCIHD4Ygpio7TJeqKSKK17wmf6B0LsgZfALxmvwJJAqa/WVQZBXySo3FYfGgJhJZEh0b9MTkGqmCpXIbfny9cuBALFy4M2iYzdepUXedpaGhAXV1d2P3Z2dkoKChQvk+ePBmzZs1Cu3btgo7dvHkzbrnlFs1vu3btis2bN+OSSy7RHOvxeDSaYPmhRDZIWCBwwDR3go82RJy5S3I3DSyBn9O27YI80GlaDhWNblHx4GdlZUVsn1Dtd7jKjQn3bMO1Y0oxYWRpxLQCNfi0+kJa97kwCILPgaW3XKl+7YUaL8xJp+mzZHJa6ohU8ZYrVdov8KE82fkxA3lOUqJQt53aEUJAVyrLSlvRtJkC0zMTQwb+pZdeilNPPTXiMaWlkW/IMi+88AIeeuihsPsvvvhizJ8/HwDw/PPPQxRFTJkyJeSxDocDeXl5mm35+floaGgIOnbOnDm47777graXl5cjJydHV95THY/Ho3yurKw0NQ65VxSVt1pHjx5Debl5sii5Pd1uN8rLywH4LhR5YrWZ0VrMosHpAJr5Prs9XqVc6cyBg0cAAHV1dbBYLGhoaAhbrlDtt/63RgDAsrUVGHZ65LQaG1WT7QWgorIKuTZ7fAXQQaQypR2qy+ZIebnu6yjVrz3ZeeNwOExtK0mls6urqzc1LfVb8njH9lRpv5rqWuWz1ysyc12pjbhjx44ltFzqtqs82tQHRNH8+pMdsx6Ph5m2kiRJGQZrampMLxct+bghA79ly5Zo2bJlQhK+/fbbcfvtt0c97tChQ5g5cyY+/vhjHD58GEBT566urkZhYSEKCgpw7Ngxze+OHj0aMlznzJkzMWPGDOW70+lEcXExSktLmTHw3W638rm4uBgtWrQwLS2rdbcysaywsBClpfmmpSW3j91uVx4k5UG0tLQ0JY2MaGRnVSif7Tab7gfk1MQ3KDZv7punk5+fj/r6emRmZoYtV6j2s/xeBaAG+c0yotaHLaNS872oeRFKS825jtU37JycnDRvKxW7mj4WtWiBDKtV189S/drLysoCYH5bWSxblDEwJzfX1LTUTqt4x/ZUab/8GgBVvs9Wq5WZ60o9XvjujYkrl7rtPIILqPFtt1gtptff3r17AQC2tL9fNWGxbvO9CxaAgoIC08uVUgb+2rVrsXjxYl0nHDx4MMaNGxdXptQcOnQINpsNF198sbLN6XTirrvuwrp167Bw4UL06dMH69atwzXXXAPAZ9xv374dZ5xxRtD57HY77PZgD58gCCl5k0oEZpZLO0GKXh2q05HbLh3bTztJmaRlGQKR72tWq1WZlB+pXIHt1+D0mUvNsq1R60N9ExUE33806pCdtiJQF8NqsP7S5dqjlT9CMS0kIK3UaD9NGKeU70t6CZRhJLpcTe0mBG2nAStjIICg2d1ml4tWveky8AkhQbGs161bh3379mHYsGHIyMjA119/DVEUMWjQoIRm8PTTT1c89zLNmjXDCy+8gMsuuwwAcNttt+Gyyy7DOeecg969e+Oee+5B9+7dMWTIkITmhROM+rowc8VSgB29nxqifUJiAlH09YNYV7Ktd/peOeflRB+eRM0cBmJqmEwmtacB3yVWOiHoTQZkcaI8TWhGYksWtOaAMFp95sPIc0ogugz8wYMHY/Dgwcr3AwcOYMiQIdixY4ci2XG5XBgyZAhat25tTk5VlJaWKq9fAWDUqFH43//+h8cffxxVVVUYMGAAPvnkE1h1vmrmxAO9mxuTs/fVRiMjg4x60lxNTQ3atGlj6PeNLp+VnpUZPchX4LpMZkfRUdJlpA8GRn3xShIy+LAZM2ZH0WHyIZNyHHda0GofEuGbKekxeB+WS2IkyEA6ENMqNN988w369eun0eNnZmbikksuwYoVK0z3nO/atSto24QJEzBhwgRT000XknUT4MaVcWguFEYL2WNvt9vRokULU19Hqj34ghBs8CcSNo0r7XerxXDk5JSHpTGQlX6nhsGXmADojRckIIqO2bDYB+WaY61kMY3meXl52LBhA1wul2b7unXrNKEtOewTGCLO3LRYu/wCBhRGiieKvoIIggC322040of8PKCnvQMPEc1ejIExQnnwWSEZHlSavY+V8VDTB9koUhDUFvujCCv9T43ASKhqmZg8+Oeddx7y8/PRt29fjB07FhkZGVi+fDm2b98eciEqDl2oehqFpvPzha6Mo9VPslEu2YMvCAKcTie9m5sAiNyDb4jAYkhmvgJhFvoyRaZgcAwE6LWVRLn+WLwPs0pMHvyMjAx8+eWXuPrqq/Hjjz9i9erV6NevH37++WdmwiZx9KExULkHPwbovl6lgeg38K1WK0pKSgz/3oiiR+u9ItQ8+Kz0xUCDwCKwI9FJhiHCalpmwkgxgqDnEGD/DYjZKNXGyDw4mZg8+ACQm5uLGTNmaGLKc1IDuh78po8ipZGalRsbYPz1KiEEDyz8E0P6FGLQKakph1OvrFhXV4fs7Gzz0iJE8VIIgrkSHSY9+AEWgUcyb1E8ViEgyjBIc5ItK/AoOvGhGfIoGKhMevApOippwo67hpMUaIaIY+nCC4We8tU7RXz5YzVmz99rfoZiRJboWPwTNs0NEaeV6NCQkDMT+xnB1yxLEgkZul51akkxMx6yGuaRlkNAAnuOB+oIbNYbN/AZhNUoOix6Doze3OJYmZ4achx8m82G5s2b0/NeoWmCr5kIgsBMHwyW6LD08EKpjVRVZnaKx8NbJI4xAp0ctNJjpf+xDDfwOXHB4g2HJpo601F/6RAlRpboEEJw9OjRmBdA09Od1A+VgkBMfciU24opAz+gGB6GougkA8nk65OVfqclWXGIzIVamExG34AkBcai6HADn0GS1UHN1uCz6Dkwqj/1UvBQx4uokuhkZ2cbNvBlCYyeksoGvQDBF0WHQv1YLBZm+mCQ95SNYgGgN15oZIoUK5CZPsiogUpNoqMZXnkUHU4T3MBnHPNvbuq0TE2KzYHFYFE83tQvu+zFtNlsyMvLMzctxcCXv5uXFssefCU6JjsKnaRg9vsPVvqdGvZKFIypHnwGI7HRhsUFJwFu4DMJ1Q6qjoPPhxfDGB2cvWlk4BNCcPDgQeMLXfn/6unG8jEWih58pgx8eQVHf3G86TDJQyfUHAJqDT6fZGsYgyrFtIHaQmuUK41JR5sMYw4ObuAzjvmx6Zs+80m2xjH6St9j5kpOCUKW5NhsNrRo0YLKQleCIEAAHQ++HB2IBZT+5+9WLEUIogc9DTlLY58MeyXyQU2iozk1q7VJB9ZGP3buVJzkoL4iKEl0mELjvYpevlSV6KjzrtbgZ2VlxaDBV06qI13fX58Hn3APvkFk44BIgv87G+VKFrScHIGf0xp1mZKYDTNhaZIti442NSyVixv4DELzJqD2QPOFroxj1PeXqhIdtRdJLdHZs2cPNQ++Om0zYFGDLyMXRySp/4ZIL/Qm2Yb+zNEHq2EyqUl0GK0/TvxwA5+TMMyXAzE4kGm8Vzo8+CkaRUcj1VJJdMrKygy3mxEbXZHNQPCvZGsoqZhgKoqOYgT7HpAE5l5S04CiQ4VBDz4jxYgIDSeHPyXT0lFSYNCDr9x7GRv+uIHPIMlb6IpOOkwOLL4vUfF4ZC+ySRmKEbXnXP5ssVjg9XoNS3SUG4iedOVxWfBPsuUefENIARp8libKJ2MFW3Zqjx4a85ShCqQWB9+0M0dJl6XGUiBMlYsb+Jw4oe+9YukC1Oono5dLjoNvtaSWhR9KogMAhw4dMtxeRg6X68zqf+KhsRCYXgO/UfTgru+X4YeKfabnKVbkUsgefJHBha6oRNGR6KTFogdfDUtyE2oGvmrMo6nB56Q+3MBnEKqeK9VnmhPMWMFomTxenyVhTbErl2g8+L482u12nHDCCTEb+MbDZBKYaZ+qo+joKdOBhlo0il68sXOjeZmKE+Wh2T/J1pJiD47pAVEekBgcokyHxXGdJtohj+ZbKwbbjbHhL8XMBE6iSZaxb2o6DA0s2gU2oh+fqlEy1Y5ztRe9trY2ZomOrmP99WcRLH4NvvkSHb1hMuWcpJqcKiT+JvIy5MGnNk4IUBrbbA80ix582lFgaEHNg0+50ljpd+FgqXzcwGcQuh00ORPMWMFokVJV6xtqki0A1NXVGTfwA/5GQn5rZFGi6BhKyhBGPfhNlZK6Fr5cf3JWWdLgy5g/bhCAkgefSQM/2RkwCXoafNWgR3GoYaX/AQAR2CmLGm7gMw7NEHFmh8lkU4NvVD+pNchSBbXnXCI+nbrNZkPHjh0Nn0tv2Qhp8pdaKU6y1Wvgp7553+RxJpLvVsBSFB26Hny+jkCssKS7TwZG53HFnx7b7cVS+biBzyDJkuXQ9F6xiBGncKpVRaAHXxAESJKEI0eOQBTF2M4VpYy+B4kmD74g0ImDz1aYTO0HPsk2hvOrPvOFruKDpRIlZyVberDY/9JCTmkAbuAzDt1QcXTSYmlg0ZZFv1c41TyF6vwQiSg69VhCSuo9XBSJ4h63+tMzU0Nu3IPvOyaV7xmKB1+WmCQzMwmG1jghCE0SHfYejziJgGvwOcmAG/icuNBMEqU0wYylASZWDX6qWWLqcoiSBIvFAovFgjZt2sRg4OuTIak9V9YU1OCLotZ4TkWU7iTJBn6Kdax0QAAERYPPPfhG0UhM2CgSgCRp8HkUnbhhqVzcwGcQqjcBtTSDS3QMo57UaKR8yXotG47AOPgWiwWiKGLPnj0xT7KN9pZCFInyStUimB/H3WgUnb2HGwEATlfq+nWVPqdE0TEmp0oHqIwblDT4LI6BLJYJoPlGm0oyqvTYbC8Aqf26NQa4gc+JD4G+R4nVAUZPqVK27AEPlRaLBYIgoLi42LCBLymLBkU5jhCl/1kFi+a3ZmB0Jdt08IYHSPDB0h2O3iRbQs2DryZlxwKDaErBTvfTQEuDT/NlISv9z4f6/pXEbCQYbuAzSNIWujI7LZauPD/EcIx4kzISJ1qJDlEkOkVFRbGcLeicoZAkqDT4vg/ySr9mYFiDL995U7TNAJUcyh9Fh8lrzOwyqSQ6IsU4+CzCUvlovUmnPTGeRamsmlSb3xYPtmRnQA+ffPIJ3njjDc22888/H9dcc43yfefOnViwYAEqKysxcOBAXHvttbBarbSzmnJQiQFNKS3WBxZdHnzTcxEbmqnCEoEgCBBFEVu2bDEcRUexiw1IdGQNvpkGlvwmQrcGPw36adMkW99fL0ldOZFR4hknHF4Pat2NaJWTp+t4AQJInGnqgU0NPhvliARLk2xZRPMCk6H6TAsP/m+//YZff/0VI0aMUP51795d2b9t2zacccYZOHLkCHr27ImHH35YY/wfbyTNg8/QhUELTZXpipNpVk7iRDMXo2mS7QknnBBzFJ1o/UkkCJLoiCnkwU+HRaOUHPon2TK63othHtq4CnM2fqnrWEEgEPy30nSQZaUarNZYcjT45qfJsqNNAOEe/GTQunVrTJgwIeS+OXPmYPDgwXjppZcAAMOHD0ePHj3wj3/8A71796aZzZSDJU0oiwOLRj+p4/hULbk6X6IqTGZmZqbx9tLpwZdEokh2FQ9+CsXBF2VveKo2GpqMg6aHKnY8+DKxjBfH3E7lt0K04NgqiQ6Pg28cYnAMTBfoSXRYqjVOIkkbA3/Xrl244YYbUFBQgPPOOw8jR45U9n311VeYNWuW8r179+4oKyvD6tWrgwx8j8cDr9erfHc6mwZyVgZM9aRGmuWSYG5aagM/8HP6tp0239HKQaTUvMGrF5giqig6mzZtgiRJYfMaqv1kI0kikcvolSTlHaQcRUcysS+oJTqAjgcQZb/xtQBoIRv0cihPLwnfVoGk+rUXarwwikSIrtfc8grAZvY/ILFje6q0X+Bbj2TnJ1EEGviJLJe67TQPlQJdRxszbSV/EOiUi1a9Jc3AX7p0KZYsWRJ2/8CBAzFt2jQAwOjRo9GqVStIkoTff/8dEyZMwIQJE/DUU08BAA4fPoxWrVppft+6dWscPnw46Lxz5szBfffdF7S9vLwcOTk58RQpZTh69Kjy+dixYygvLzclHV8nbeqoTofDtLQAwOVyAfDd5OR0CCGorq4GgOiethTE4/YonyUiRa2/mlqH8tnMujZKxVHtQ7NdklBRUYGTTjoJ69atC5vXUO3ndPrCS7oa3RHLeKSqKU23v284nE7T6qWqqsqXltsNtzty3gCgrqEegO8KSaW2UnPUWev74Lcba6prUE705TXVrz232w0AaGxsjLn+y8vLlYfHUPg8/ER58HZ7PKa2dSLH9lRpv4aGBiBDzlPqXitGkccLAKirq0toudRtV1tbB2Q3bTe7/hwOB7W0aKE2uBPdVqGQ69Bskmbgl5WVYcSIEWH3d+rUSfncvXt3jeZ+6NChOPfcc3HnnXeiffv2sFqt8Hg8mt+73e6Qk2xnzpyJGTNmKN+dTieKi4tRWlrKjIGvprCwEKWlpaacW5IIIPyqfM/MyjItLQCw2+0AfDcjOR35wiwtLU1JIyMaNtt25bMAS9T6y8urAlAHAKbWtVG8gguA74Zmt2fCLtpRWlqKnTt3ghASNq+h2i8zsxFAI2x2e8QyNpJGCMJOAEBOdg5QXwV7RqZp9SK/+cvOzobNZouaTvahasDp07WnUlupqamxAoegLHSVn5+vO6+pfu3J40VWLOPSbt+fFi1bwhZh3QNJIsAuwG61wgvo6hfx0NDQoHyOd2xPlfbL+bMBkJ/VhdS9VoyiNhpzc3MTWi512+X8ITaFsKNQf9nZ2cpnVtpK3f1zc5uZXi7mDfyePXuiZ8+eMf329NNPBwDs27cP7du3R5cuXbB7925lPyEEf/zxB7p06RL0W7vdrgz8agRBSMmbVCwElsOscgW+ZCImphWIOh257dKx/TSvpwVj9ZdS5VXlRSJE0anv3bsXkiRFzGtg+8nKekIil1ETJlOlwTe7XqxWqy5tthxFh+Z1YRQlio7UFIXIaB9Mh2sv5vxFuSaJfIxfyCMZrD/D2Unw2J5y7Rflmk8nzL4Py+0WeB+mVX+65qekIxSuB1r1lhZRdN5//33N0/Arr7yC7Oxs9OjRAwBw8cUX49VXX1X09O+//z6qq6sjviFgGWqae4loFiYxO1kWJ9lqJpjpKFeqllyddXklW6vVijPOOMO/X3/O5WOjzR2TpKbnCou80JWJFSTnS+9CV9406KeyfleOg8/SDTsR40X0UK0SBAGwyg+lFOPgszIOakrBTvej1laBGnyzYaXfhUTQznNLd9Jiku0PP/yAf/zjH+jZsycOHDiA33//HQsXLkRhYSEA4J///CeWL1+OXr16oWvXrlizZg2eeOIJtG7dOrkZZxyite/TIixgqqG9Cej5gXl5iQ/tJFmLxaKZKyGKImw2fcNNU2QXHZNY/XEdLYoH37woMIaj6FBegCYWmgx8318ekUNLtNqQq0t+wKRp4LMCq1F0ZCwRJF6JQNsl6NUgS31Rvm4ZC4OfHgb+Aw88gGnTpuHHH39EQUEBTj/9dOTn5yv78/Pz8e2332LNmjWoqqrCc889p9HwH8+YG9GhycAyOy35/Hq9p+mCxgTUEYTceEx5gh9+q8MZJ+XBajXPvRP4JkK+qdXW+iZxSgaMXflcUePgiyRIomOm98VwHHzSdNNIVQIlOoSHydT+NsrtXn6IExRZGffgxwNLJTL6xi9WxEBPm8mw+CY9pQfpOEgLAx8A2rZti7Zt24bdb7PZMGTIEIo5Sl2oSXQCkjE7VdlwZGpg0RjGhg7XxeffHcOjr+7DtWNaYeIo8yYOBUp0BEGAxWJBz549sXHjRkOr2Srn0iPR8X9WPPg6KujOp3ahR+cc/PVCY2/41Aa+HiTVxLdUJVCiAwYlOvGdI/J+r38QtCgSHXNhauzzw+riYLQMfEKgjDE0a5KpvigXRWAn9CeQJhp8TuyYrv2jqMEH2NIIA4EPSdHLZrSOd+33zUvZf8Rl7IcGUWdLjoMvSRJ27vRFuTHkwfefTYrijRdVb5DUcfCj8fP2erz+2RHd+VHyFaMHP5WXhw2W6LDnwY+HaMan3EUFCCASXWOVFUNEUww2iqTBbKdU4FtLVmK4JwuWiscNfAahN8lWa5JyiY5xNK/cTTi/0+Uz2LIzTb7U1R58ol3JFohNohOtPkRNFB2Lf1vqSHTkvKTyM6kUINFhaZn2xEyyjbzfK/olOn7xrtnzkFga+2QM+jjSBrUH30xEVZ8QBGJqoIFAmOmPGkclI2UCN/CZh9arQYDOzY01D77GeaVHomOwimUDPyvD5Ilemkm2PiPYYrHghBNOAICYJDrRyuoLien7LEskzDRQjRr4yiEp3GWV+lIkOsnLSyoiRpmT0DTPQoBvxWJz88OmBp/FMhkfL+JNRybam89EpsdKe7FRimC4gc8gdMNkqi9289Nk2YOv63iD52+k5MHXTLKVJFgsFoiiiA0bNgAw5sFXZCPRjlOFaVUkOinkwU8riQ5hV6ITz3gRVSYm9wlBNu65Bz8uGHzANPuepemigmruDwXY6Y+K1o5LdDjpA7WBhQLq6CysoI0+o+d4Y5XudPk85zQNfIk0TbLt3LkzAGMefMVGilJWUfK9kgaMTbKNFaOT5uQbbSrbLIqBL9KJAkMTGpNsRVH24AMg5mvwaU3cpAkjxQiClkQnsP5oevBZQwBb/ZEta4kDgK4HX9Bo18x1HbCpwVd91vUDY+d3eXw/yDRbohPwoGKxWCAIAtq0aQPAqAdf+zfscaoDaHrw5ZVsox6fBi9+mzT4XKIjo25bMUo7S0TW4AsACV5V1CxYkioalSmmG+Z78FXnFsx1cgTC0r0YAPfgczgyQZ4D09NjW4NvyvGKhMDgD42mo9bg+6PoiKKI5cuX+7cZ7x16NPgQfPpnOQ65mfNA5DJYrVaDUYFSl6aJqL7vLC10FeskW/XR0eZ0yMaUBQL34McICTBQWYGWBl/dRwUQ0z34aljpg2pYKhE38BmE6hLZlGefsxYHXxtFJ/FhMpvObS4aiY5EYLVaYbFYcPbZZwMwJtHRe4MSRQJB8NWa/Nwnmei+inmSbQrTJNHxfWdxoat4iB6qVa3DEriBHy8MFYleHHztA5LZGnwWJ9mqofmAZDbcwOfETOBAYr4RyaBER/2ApOd4g+eX33jQrDLJP8kWAOx2u7JNLzol+PCKwR78aJKKeG5OaolOLG8kUhEeJjPE71RXWVSJjmqhK0LojYEsoakztooGwHw5VaA9SvMaZuVezKpMjBv4DELPg980yRGg83qauZubenTWZeEbq2O5tswP39f0WfR78CVJwooVK3zbYphkG60/ub2+OSCC0FTOaN4XTXUbrBNar9xp0hRFx/xJyulC4ITxSHj9z3kWQYBA/MHwTUQeA1lydKivc0aKBICmREf1hZIHX3bgsNAHCSFQZs8IhCknBzfwOTETaEzxMJnGIWE+hz0+xqKbPWhpJToSrFYrrFYrLr30UmWbXuRuFU0t4vWqPPj+Bz9vFAOfEMCaKcJiM67WV9+w9ZQnLSbZSrJEx/+mJw3ybDaBazpEQpboyJO8ickhUVl0crDe5WhKdATQkZiw1AcJQYDUOGlZSTi2ZGeAk3hoefCDLgzuwTdOgAM/WhkN17D/VDQHLUKIEmnmyJEjAIyuZOs3OqMc5/ESAMTnPfVv80ZxQUsSQbfL98HjsALkVN15kvMlh//UZeArWiNDyVBFlqDID1OiyIb0CIhDomPAgy9PSrYIoB5FhxVHh+Y+IrAzzqsdAmYS5ME3/W0tUUk/078PBs7xlkj69z0Z7sHnxEzgzc98GQh7cfA15hTRMWDG7MGP7Xd6UedbjqIjSRK2bNkCwJyVbD2iX6LjX0UUiB4FRj6nPUc0/FYjZnlECt8vuEQnFCoNfpQK8SoefHlc4k4Oo7Da5ZIyyZZSFB2WJDrBdkz6l0mGLWuJA4CiBl9CgAfffFjyHAAImmEWzTNstNSKBt/sxU9Un2UNvtVqxYgRIwDEOMk2Smk9XgkQfN5TOQyoJ4oHWn3zi0WDL3vwCSFR+2A69FDZQJUlOiyRiDCZ0fqg/MbIqsTB5xp8o2jLwU65ZEyPg6/uc4JvAUAzYdKDr3mDlMzcJBZu4DMItYWu1JNTQEeiw5LnANB68GWJTiSMFlsJH2m6B7/ps6zBlyQJ27dvB2DUgy8bZpGP83oJBIss0WmKFhTJix9PPaiNK3U+I/wi9sQoIQXUtZeR6EDxoNXg6/PgWy10FgqLx4Pv9kh4Z2WF78E4hWBkKA8iOR58uhp8Fu7DgUVgoEgK3MBnEHor2YJqHHwmX09rBIB6PPix1bHpg756LgHxhZIEgOrqat2adfXv1X/D4fFPsrWojG5B8E++jXJuwLixLz9g6n3ITIcbhWLASuzcsONF+7CqV6IDCCnuwV+8/Aiee/cgFn1cblLuYoMEeKBZ6YPJ0OALAo2ACmxJZQPri6Ew+NzAZxGqC11p0jUtKQWWPAcAAibZRjfwjdoP8vOQ2dWl7gtyHHyLxYIBAwYYX/m1SaMTEY/Xt9CVRbA0PWcKBJ4IumlRiv3aCPTgsxALv2mhK/9DSzIzk2ASs5Jt5GNlZ7g1DQwej8dXmD8ONyY5J1oC65iZsd2P+R587XcawxJL92FCVH5KLtHhpDrJ8uAbDzxoDDY9+Oov0Y3GWJuWogNfWclWkiR89913sFgssU2yjXKc7MG3CoISphACIkoQ1PUXjwZf/p7uiAFGMJfoAOrVfPVKdGyCBSACQClMZixGY2GeL2hedZ3XjKzFTKAGnxWSs5ItiRpoIBHpsWTgSyoNPo03IDThBj6D0JtkS/zxS+isgsnawAIES24SPckWoFRfGukLUSQ6hYWFxiU6qvNEwitKEPwSHas/iolgIRElOpLm2tCdJd9vJcmQBz8dYsorHnwGJTqxevDVkxSjrWSrxMG3+EZBs2svHgO/oJnPwK+pTzEDP+AzS30QoLzQFeh48Flycvg6YOz3hVSGG/gMQuuiEyUCCEQzwdFMWJxkq/Eo69HgxyjRoTvJtkmrftJJJ8Fmsxnz4CsrXUU+zuMlsFh9k2wtKg1+JImOpr5150j+LXse/GCJDjse1FjRhHyNJtHxPw1YBX+o1hRe6Mpm9f3O7Umtfqv1QLNxXQFaD76ZqJ0WtDT4LDnaJI1Ghy0Dny90xThmXoCiX6IjXxs0Xm2xZFwBwUZmdE93bOU2fQJ0QFpWqxWiKGLFihUQdDy4hDqXnkm2ggWwQC3RIYrWOBTqhZx8ebLqzpc8t4BJDT7Yk+jE2ufVXnsSpT7kY20WCwQimK4wice4SlXpQYB9z87Yrppka2qZuAY/LgKLEO2tXTrBPfgMQm32vryKI0WJzvFu4Bv24CvnNfY7owRq261WKywWC0455RTDEh2dDnyfB9/iu9lYZQ++JfJqtupdRt9qqCcPy98jkQ49VNHg+1UbrFxXauJbyTbysbLe2WppesCkQUy67hRt2sBssdIHqd2HA6IQ8Sg6xgiqLza6HwBu4DMJrck9ogTVSqJcohMTARPMzAq9aH51qbyeEGC1WiEIAlq3bm1YoiNnNlpdeP0r2VpVcfB9k2zN0eAbDpOZBncKyT+hVLZLUznHoiRhf0ON6emoQ2Pq1eBbLZamPmgi8WjwUzX8X2A5WBnbaXnwNQaqwD34RiGkScoKpPYYaBRu4DMINe2fpE2HpkSHBXkEoNU86wmTabSGmzT4Znt1tN/lyDlvv/22YYmO4sGPkmW3R1J58P2TbAUSMYqORqJj1EAyOMk2HZAIAZEAwSKBkNQu0/t7N+PhTV9hd+1RXcfHOslWs/hctIdMWaJDWYMfi4GfqrYY6x58mlF0BBDT1zxhzdFGCLTRAFP1STgGuIHPIFQNfKFJokNjoSuWBhbAeBSdWN0LFIPoAH4PvsViwQUXXKDo8XWfS6c32SsSwEI0GnzBEtmDr5XoGDfwjXjw08EVJBG/B4sQgKSuThsAttdUAAAqGut1HR/rGKG+Bo1IdASAmgY/Fq9w033BjJzFjnbiuzFnQCoT6BAwC9lnIfc/8+WYbN2HfZew9g00K6SVgS9JEnbu3Inq6uqQ+ysqKrBt2zZ4PB66GUsxaL0a9A0sTVF0zB6WWRtYgGDD27SVbE2XT6k+o2klW6/Xa1iDH+qcofB4CSz+MJmaSbYRNPiSKsa5Yc+uwUm26dBDJSIBRIAA4vPgJztDEZDrU68UJtYxQv2raA88or8/2ayyRIeeB9/oNZWq/ZHlKDo0pCzEf9XK14XZk0RZuw8TiWglOulfJIW0MfCXLl2KDh064KyzzkKvXr0wY8YMZZ/X68U111yDDh06YOjQoWjbti2++OKLJOY2udBb6IooccgBLtGJH2NhMvW0MzWtZMDp5YWuvvjiixgm2epz4Xu8BLDIcfBVHvxIUXRUTzpGH3qMavDTAUWiY/WtKZDKZTLqgY5ZokNIyM8hj5U9+AIdD74MUxIdEvg9RTNqkHjkVEaQxzTBH9KOpgefBXgUnSSzfv16jBs3Ds8++ywOHz6MP/74A61bt1b2z507F6tWrcLu3buxf/9+3H333Rg/fjxqa2uTmOvkQW9g8f3lEp3YMfp6OjBajV7MHvQ1hhDxSQisVivGjh1rPA4+CXHOEHi8BIIQGAefRI6io7LqjXYhVjX4IAIECZBEIS08+LqPj9WDr6qE6B58vwbfYkHqa/BTc8wMlPexcF0B9O7Dcm3J75BoaPCZmmQLMBsHPy0M/EcffRRXXHEFhg8fju3bt8PlcuH2229X9r/++uu47rrrFKN/2rRpkCQJn376aZJynHzM1v0BfmPJQs+Dz6SBH/A9lnjxkZC7Ac04+IDPg08Iwf79+83V4AdJdBB5kq3ag2/QZDSqwU+PKDo+aY4ACSBNUWFSGaMSHeOTbPW/5VFLdCzqRUFMQq3BN2oIp+rcQaLRPzM0tvvvV6Yb+IHBLvgkW0NIxOcokkn/EjWRtIWuysvLcejQobD7mzdvjo4dOwIAvvvuOwwePBgnnHACsrOzceDAAUyfPh3//e9/AQDbtm3DnXfeqfw2IyMDZWVl2LZtW9B5PR4PvN6mpbqdTicAX0dlobMCTUaiPLCYVS5JIhCgfpo3WWuo8hyIoqiULVwZvaLPm5uVkcLPsYGvB/3lCnu4ah+RCIhOg0Iyu20k7QApR9HZtm0brFYrvF5vyPRDtR9RWfiR8uzxSj4PPprCZAoWAo83fJ/XGPiSZKhOZA++cq6obSV/SN0boeSfXCtYJAgWAgn66yTStWcGIfuIjuON5lEdaYlE6SNyf5Kj6PjmMpg/BsYytjuIE11GH0DDz22jjp00CZJIRLmu0gX1Gz+jY0001G0nO9Ys/jdIomRum8qODvlzureVFPDG1+x7JUDvfpA0A/+jjz7CM888E3b/iBEj8NBDDwEA6urqsHLlSmzYsAHt2rXDzz//jIEDB2LAgAEYPXo0GhsbkZubq/l9bm4uGhsbg847Z84c3HfffUHby8vLkZOTE2epUoOamhrlBlBTU4Py8nJT0qmudgDZAPHfEEVJMi0twDeYuFwuAEBlZSU8Hg8IIcqk68C3Fv9+6Sh+3+/B6/eUmpaneNF4eQXg6NGjQX1ZTX2DQ/l8uLxcWX4+HG63GwDQ0OAwtW2OHXOpvgk4duwYRFFEz549sXz5cng8npDph2o/j9fn7Y/Wn1xuEQQEbrcbx44e9Z8DqDpag/Ly0BPtq4421V9FRRXs3jrdZWxoaIAoijjqT6uysjKiFlU92d/Muo+HRrcLhAgQCCC6rXBbQ7dTKCJde2Yg94vamhqUi9FvXaIoQhAEeL1eQ/VfVdvUR6prayP+1uF0AplAfV0NJFECBHPbuq6uTilXXV2dobS2u/ciq7kHpGslysvLqbdfOBobG4G8pu+VlZUaJ1y6UlNTA0IIXC5X2PEvVtRt5/aPM7LReOxYDcrLXeF+Gjcul0sJolBVVZXUvpMIKqq8mjdvTmej6eO1w+GIflACSJqBP2XKFEyZMkXXsUVFRRgyZAjatWsHADjttNPQv39/rFmzBqNHj0ZRUREqKys1v6mqqkJxcXHQuWbOnKmZoOt0OlFcXIzS0lJmDPxDhw75YoNbrcjLy0NpqTkGbk6zSggSkGGzAx4nIMC0tADfTUg2fouKilBSUqIMaqWlpUEDze/7y5V9qYs2Dn5BQUHE/ObkiAB8g0PLli1ht0V+O5GZ2QDAjaysbFProfBILYBq5XvLli2Rl5eH3377DTk5OXC5XCHTD9V+VssxACIAIWKeJVIBwSIgJzMLLUtKgP0ALATZOc1QWtoi5G/2NxwD/GN3UVERSluGf5gKJCsrC5mZmWjRwnfu5s2bR8yf3f6n8jlV+6Dt0E6fB1+QIFgkWKxW3XmNdO2ZQf12AtiBYw2ZKC2LnkdZHmGz2QzVf621GvDfTpo1izx+2jMOAwCKi4pgO3AYLpPHwNzcXNhsNmRkZCAnJ8dQWrm/HwRQBWumhNLSUurtF46MTJUxJQgoKipSrrF0Zt++fbBarcjOzoYgRB7LjKJuO6vtACQANosVgiAiLy8fpaXNE5ZWIHa7HRkZGQCij4HpgBuNwJGm75mZWaaXiXkD3wgDBw4MMuArKytRWFgIABgwYAC++uorXHfddQCAw4cPY9u2bejfv3/Quex2O+x2e9B2GvFqaaJ+jWtWuYgEwD/JEfBJM8ysw8DZ+3JaclnDpZ3K7UoCPhtrLx19VqVnN7VtNJ99RpUgCIq3J1Deoiaw/dRvLyPl2eMlSv9rWugK8Ijhf6eReUQ5fyDyq2nZexW9rfxpCanbB30afMGvQRUgwdh4Ee3aSyQeL4HFDtQ5RF3pqceLWPNHotSHLI/IsFl846Bg3ngrE+vYngHffc+SKeoeO2mgvSbNvWfRRD1fwowyKfIff/XJc0AkQu8+nOy+kwgI0c7qISbXH0DvfpAWBv6dd96JM888E4899hgGDRqE9957D/v378dVV10FALjrrrswdOhQ9O7dG71798b999+PgQMH4qyzzkpyzpND4MBiFhKBZpItDVkZD5Np7Izy4bSrS17oqk+fPigvLzf0yl2RrkcoKyFEMfA1NxmBwBtxoav4J9nqjSCRDspUAn+YTEIgui0gKf0SUzuZMOrR/nHQeJjM0J9DIfrzZLP65oGYfd+OJzKLlfhu94Jd/4R3GqhligJSd76KUdRtZeb9StHgCxZAIBTWPGFrki0h0ES/Sv8SNZHCsw+bOO2007BixQp8++23mD59OiorK/H999+jQ4cOAIDBgwfjo48+wsqVKzFz5kz07t0bH330Udo/WcYKrYFF9MfBt+o0eOIl1oEllZeeDixGog18uezmt436m6B47deuXatMuNV/Ln+eIxyjDoVpFSxNHnyL/ig6hh+WiDYOPgsPmaJqkq3FLqVFFB29xBqvW32tRI2D799vs/inelvMHW/iCr0oH55it0V1HctvMVlAPV6YPfEa8K/FIPAoOkYJvMZT2FwwTFp48AFg0KBBGDRoUNj9559/Ps4//3yKOUpdaMXfFf0SHdm4MjssICFEI4/Qiz+aZ0qiLYWxBzIjTWv+4ifaz/INoLS0FA6HI6YwmZG6k+KlF7SLrQmC37Mf9txq4013lnzH+2VGLN3ciCzRgQTiFQy/1aCKHPJVZx5jlUVIBkKpysaB3WpR7GavRJBhMUkWSWIPk5mqLWvUyZEuUPPgw3d/swoWRaJjJqwZ+D5Jjup78rKScFLV7uEkABrxdwUAFoscB9+0pABoBxYjA6YYYeGjVCO6B9/Yq0T5cBqrDDchKBKdrl27wm63G5Po6Miz29vk5bcgMA5+JIlO02ejni51XGvf76O0VRrcKiT4Pfj+KDp6w64mE0HnYlKJkOiQKH1Ea+DLIXzNM+bksjC10FVAvlI1n0ZROwRohCi2+D34Zr+FY83AFyWieauVym/8jcINfAah5cGXJAACYJVXsjXZoJEkKTYPfopesIQE1JgOT4/6eD11IBfd7HFYkxd/3xNFEcuWLVM+60U2miLluUmiQ2ARLIpMTI6DH/7c6vqNTYPP0s1N8eBbJdhyvMrCTalJdOmW5mj/Gz/DhrCBha7kvmq1ND1kek3uF7GO7anaspq3JCZ7u2lCz4PvN/D95pyJz5cAYpe+pSqBTUNSTcMWB+y0Ekchnte4RhAlAsECWBWDx1yjJ1bPgdkDXqyEapuoEzc1Fr6eVHwHmf2MI2nu0b42slgs6NevH2w2myEDXw8+I54ErWQbTYOvrj+jl0bgJNtEz5dIBhLgq0aJwOuwpsVbByMSnXhXfI2WVjI8+DFLdFK0Qwa+lUzVfBqFVrALtQYfoOPB1xtoIB3wefD1y/LSCW7gMwg9Db5vIGnSP5ur9VZr8A1JdFLUgy/Jr0Bk9Hh6SMiPEdLwH0txILao9MclJSWw2WyGJDp63jp4vL6HS8B3Y5MV0FardgJu8LnVA7kxAjX4LHgaJeKPogMJUqpr8GV0OthkAz8eKUtUD76/F9ksFkXH6zV5ki0Qo0QnRds2MF8sGI0AxTfpkN8i+T34KRrsIlWRg4XIpPRLTINwA59BqEp0AGWSLUBMM6Z9UoLYJtmmtoGvxqhEJ3oa8iHmz49o+ix78CVJwuLFi2OIouP7G0mD7/FKitfF58H3pWm1NunzQ6GJ2BGD4WckTGY6QEAAIkCwEGQWeFPWCARgeJItgJgMfCN9RCPR8d9OIz1gxou6DxrvvyZlKk60+WJPomP2m/QmD74s0eEGvhECm0ZKWTGbcbiBzyC0DHyvJHuvmiY4mj2hNbYwmWblJj5EUQzS+xmRfRhQ6JgeGkDdHmqJztixY41LdHTk2SsSCJamG5v8FsliBTye8D/USHSMGn5+D75eiU464FvoCrAQCY1HMyhPxo4RA5NsY/PgN32OVh/yXgsssPrHQY+JEh11H2Rlkm3gW6NUzadR4nkYM5SO/6+V0rjEnoFPNG8FGSiSAjfwGYSW50D2VMk3Nt8MfnPSksuRDh78imoPvt9SG/W4IImOLg++MQtfNlDMNtzUZxeEpmHF4XDAarUalOiQoHMG4vEESHQEnwLaJ9GJoMFXndVolag1+Hpu2intDfcje/Ah+HSo6ZBnvX05VgNf68GPcqwsjxAExcBym6zBjzW2eqq2rHaCPhtGI0DvPqxeiwEwX6Ijj4MAG23lFSWNRCf93TZNcAOfUaho8P1iNVn7B5hnTMvliClMJmUD/4Y52/GvZ/fA0RjZay1JkiYsIYGOchEgr10D7LkefcaYDj17QlDfo1VttHr1aiWSid42Uxz4kTT4Kg++LM+xCAIslshhMjUa/BglOgBMj4xBC9mDLwgEGXnelL65yc2l14CJdZKtJoqOjjQAX3+Qx0G3x7yVYuOJzJKqxph2HGPjugLie9tiBKJ6yAToavBZICiKTmpeJjHBTitxFOKZiGUE2YMvew4gmG/gxxYm05QshaW2wXeDj2RoAj6JToDrO+rNTRREtD+3AmUXHNQ1ENF6ttHKaOUJr1ZcdNFFsNvtAKBbpqOe5BSunX0afN9n+cZmESywWKJo8NUe/BjCZMryHLMjY9CCqOLgO6syk52dyBB5vQ2TPfg6+p9yLCSfxEnlwXdRiKJj9thOE6K17xkqF50wmXJ1WRXHCj0Dn4WHMW9AGdK/RE1wA59BaEfRsSmLDJHUlOgkaaGrqK/3gyQ60QdMJeaxjRiaZGv2PVN9fotqku3evXsVo1i3ga9DRuOLoqOdXGaBT4PvjbiSbdPnWFaylW9sejzD6WCn+Dz4AiyCBGuGlBYTzPQY+Oo3fsbjxav7nw4Nvv8Q2dERKUxrvMSzeFKqRkjSPGgLbBiNgFaiQ8eDz6PoxELQJFsGyiTDDXwGoTWwyPaabNAJACSTjOl4JDrJumCjvc3wTbJVY1CDrwdaGvyANxG+bQR79+6FzWYDYMDA1zHNwOWWFA2+RePBj7bQlX7jLei3KgNf18OzzsmgyUSCP0ymIMGWJaa2Bt+fNclAHLt4J9lG+6VEiPJmQQ42QEODH5PzJkWbNjBbLBiNAEUPvr8G7Unw4LPQVoFhbRkokgI38BmE1sAir9hoUTz4qSnRSfAaS7qJFi7P1zbaSzC6x7CpPQ1JdEwftJoSEJSQlVace+65ikRH70RbTbnC5NvpkiD4DWh5krdVEGCx+oz/8LlUa/B1ZUeVL8KkBx+SAAEk5SU6hOjXGKvHC+MLXemfpyFLnIAmD77bm5oa/JT14DM8yTbWCdGG0vH/VaLoUPDgx7IeTaoSWAaJr2TLSWWohckUtQtdAfQm2RrS4CfphhFJKgL4J9mqvhPoCJNpUEMuF93sGtDco1USnY0bNxqX6OjwoDpdEiBPskXTJFubVUCdI3w6RM/TQxjUGnxmJtlCApF8Ep2MZh6QVDawFA++uRId9fHRfqpEIYLKwE9RDT4J+mAen317FBf8/Vc4XdGvea1Eh43rCqB3H5bPTSuKTqzr0aQqsqKO+G2X9C9RE9zAZxB6GnxZ+0dPgx9TFJ0kafCjefADDV5Bh0RHEvQbH+pjzB6HJc09uumBjxASg0RH5UEN88DodDVJdGQPvkUQYLUB9U4x7IOmemsscfDVHnwWbm5EkegQxUOeshpUA305PgNfnaQeD76v3uxWvwbf5Dj4MYfJpNiuj766D45GCX8edhn7YSo/YBpEPV/CXImOD2WSLUUNPgsPY0oZFAdC8vKSaLiBzyC0DXxFg2/iQlfqG7bRciVrDNIl0VEbw9DjwY8t5B/dm2ZTpJnTTjstpESHEIJ//28vvvzxWNCv9eTU6RKbJDpKmEwLrL5nCdSH8eInapKtHg9+qt8nCCE+DT4RIBAJrhp/tKNUNbD8l0pKTbIVgiU6Zhr48tgOGDeuktGqRh7GADBl4NO4DxPStHaFnaKBz1IkJ+U2beANYbrADXyGMdvLKIeXsghQLg6zJTqxDCy04+DrTVeSpCA5SlSjUQj4QRTi8eBLEoEzSiz/pnSaEpDj4IuiiNWrVyvb1R58SQLWbKzBAwv3hc1z4Gc1jkZJs9AV4Pfg+94cK6FKg85tcKEwbb4IUx582ZAlkgDBIiG7yA2gaX2LVMV8D75aBhf1aMhPHjQ8+HEFUEjR7qrNFnsSHTM9+BJp8hHRlOjQeDNBC+U+LQekSGJeEg038BmE1hO2fG0LaJpka9b1Lg8ksQwsyTLwdUl0VB58AfrDZAL67tfxaPDnvXMQY/6+Oaw3PFQ6Ppp06h06dAjpwY/UJno1+Far9g2SRRCU6nR7QtejRv5j0JA1rsFPUYvKj9wGRAIshMDT4J84l+IPLkYNfOMLQulPiwBUJTrxRNGhGSFJvg715FHjHOAefEOIIglaD4R78I2h2BaKnZ/+ZZLhBj6DUIui4zcQBAiqiZSp6ME3JUtR0RdFpwmiJ0ymYCyKjnJMDM3y0ZoqAMDuA87o6ag+qxeD6ty5MzIyMgAESnTCn0sTyjLMg4BXJLDbm6LnAIAVgvKGQ5cGP3wWQufLoAY/1W8TiqdeEiAIEtz1vgexVDfwjeQvJomO5gEzWhs3SXRkAz9w4ZxEEs/qqDQNF9ltYThFxuLgy/MlzPTgy7Vss9J5QGfNg6/EwuCTbDnpADUPPmmKoiPAN1GPRhQd4xr8JEl0dBj48sRGGV2aX/mzjjzI54ulCtq08BnmByp0TJRTy2iFJonO0qVLFaPY4/Eox0RsEx0efFEksPjlOGqJjvyLcPedOILoGNbgpzqyIUD8Bn6ztg7f9hR9Sa0YjWZLdHQstNaUKaK8waSpwY/pzQTN6H+KBz/6oYELXbHiQaXlwRcCPPiiyeMSax585T7t/5Oao19scAOfQagtdCV78AUAEPxx8M1JK1CiY6RcyRqC9El0QmyLgDJpVoKuu6fiwI+hH+Rm+yzoRpev7g9WulDbEDqWfaCOFvAZV2effbYSRUcj0YnowVedN8xxokRgtQVLdOQHoHBeLG0cfOMeUJY0+LIHn0iAQAgaDmf5tqdqGIkYZB+xefDVD9F6PPhaiY6ZcxjikuhQbFYjzxJNYxSYNfDNcgaIklqiY2naZiK0ogPRQrneZYcHj4PPSWVoR9ERZB8WhYWuaEiPEkWkFVUBOQ6+OoqOHolOk9fVkEQnDmTJzcR7tuHa+7ZFTUcdJjMvLw+CIMBut2sM/HAe/MD+Gt6DD2VCrSLRESzK8Xo8+LFE0TGkwU9xO0WejEeIz4MvunwVGri+cqph5M2VbOAbcgjoeIOkIDQZs8okRxMNrLgkOlQ1+PJq1tGPVfJFBKYkOmpD2Kz7sCQhSINvtoFPSwJMi0ADP1X9G7HADXwGoXUBygaCItFBakbRSZa9Ek2iI4pi0wRl1bZIaBe6ik48UXRCUVMfJn8aC78pRvKSJUsgSRIOOLrg193aKDrRTuPbEPo4USKwKFF0mmQzTRKd6B58ox3DuAY/te8Uag++RZBQ0LkBgPHJx7Qx6sE3fH4DaRE0SXT0evC9koTt1RWG8yXnJ9axnaoG3z+s6ZmTRVQfBLDlwY/1bYteRIkEhQumqcFnoa3kN+2C4sFnB27gM4jaGKbjwff/TykOfroMLNEkOt4APROBnsWgjLgX49PgGyGcRGfcuHGwWCzYdrQ7Fq20K0eEN8C1hLtZiRKBxR/zvsmDLyhGdTipWLwefLWBr9vAStE3vk0GvgABBNW/N/NtT3EXllEPvvq7HtQPOFEf0oQmiY7Nv+BatDCFS//Ygmd++wabjx7WnSclP0kyrpwuEU8t3h9WoheIYuDr6UuKF0IAGNF1A9pFyQBzHlzUEh0L9+DHRKAHnyW4gc8g9CbZaj34AKESJtPowJKs69YbxVYXQ1ihZnnwY/JLqJ8lonkyw0h0jh49GvL4sM8+AdvDavDFJg++fGOzqAz88Bp89bmNaphJbAZ+iqIYApIAARIsmb7ySAz4sAINfENtpen3UY61GPfg72uoAQAcaWzQnyc/yZLovLW8Ah9+XYVnlxw09LtoTg5A7cEXAIGk/XUlIxv4sS5Mpi8NX3ALgQhNBj734BtCdjbJHnwWxj8ZbuAziDo8l7lx8GUPvj9MpqBvQI+FeCQ6ybtcI6fs8YhNwXf9RNXgy4cL+nTFiXJORHMKqXerb2jfffddyDKF8+Drfb0sSlBF0bEof5VJtmE1/qE/60GtwbdYLDoexlIbzSRbC0FuaSOA1JXoGJq4GYcHXz2ERf2VQCAQXxp2f4eMZmDFE+1ELfuguZKt/GbWoXPhu4KyWvSYsBeNYnSPf5MGH0xNsqXiwVfFwbfE0a/0EstcuPVbalFV44l6XLJQrlc5TCYb3Q8AN/CZRO3loaHBFyhq8GPVNG7d04CxM7Zg1/7oMd0TRbQsBkl0iB4Pvg/V4sG6jo930IomvdLEq5clM1YrxowZo2jy1egxwEN9V/IjEViUha6aJDryA0JYjX8cUXTUEh2r1ap7oSshRU199SRbC5FQs7uZZnuqYSRX8Rj4mpVso/xOsBBYZA++TV5oKHK/UKKdxPAgFY/3NJ5mtVmNyT9a9PGtoVHtif6WQuvBZ0P2AWjvw/L3hKdBfGEyhaZQF6Zq8NUGvp4+WOfw4u5n9+Dmh383LU/xIgZ48FmKomNLdgb0MG3aNGzfvj1o+4MPPoi+ffsCANavX4958+ahsrISAwcOxB133IGcnBzaWU0JaEzuAQIn2ZrrwTe6km3gTfrbX2tRXefF/HcP4tHbykzJY1AeouwPkugIgDearkd1rBENfjzdgJDo6xtoPfhNsojdu3ejTbtOQcfrnWQb7mYlaeLgN3nw5Rju4fOrljgZN/pYkuhIKg0+BIKMfJ+XLVUNfBkj7RaTgW9EBic0reStRNGJ5sFH7AZ+PBKdeLBaZSPV2O/09CUC/1sk+XuK9z+90PHgQ1mLgYZEJ9DRFm0MbHT7jq+s9o0t9Q4REiHIz00d0zM4TCY7pE4tR2DSpEmora1Vvn/22Wd4/vnncdJJJwEANmzYgHPOOQd33HEHRowYgcceewzr1q3DJ598kqwsJxVaGnwiL3Tll+gIFgJvlNCQsacVu0QHAAqa+bq620vPKIvqwQ+Rl+iTbP0I+ox2ZezSd9aQSCT6+gYaDb48I4MQHDp0CCWl7UOcM4wHP+oGH6JEYFOi6KjDZEbx4Mco0ZFvZGoPfvpLdPw3NAkQBAn2XJ+cgkWJjqE5O9oTRc6ThcAi+nKWoXMl0T8OuYBsYF9FI9BBd7b82YndeROPtlg28PUGUSDE9yJP3/Gq95I6pYfpgPo+DJjjwRclAsECaga+0fVoAlciv+jOzQCAlfN6m5PBGJDvbSxG0UkLA79fv36a7w8++CCuuuoq5OXlKd8vvPBCPPDAAwCAgQMHonPnzvj+++/Rv39/6vlNNrTj4FsEwWdkpZAGPx3uEV5Rago34SeaflI2YAVB30Akj6/x9oOoEh214ayS6AwePDik/jJslJuAG0K4VEUJyLDI/c9vdFsEJYa7ngcII7db9Y0NYC+KjhUSav/MRUEnh+lh9uJF34Ot7yCr3+g25MFX9cGoLWwhEPweeXmSbbSVgOsbJCAbqKk3rksOjGDyx6FGuDwSTuyg5211HAa+/2HaqARTT18i8n+EjRWiZWh48CWJ+D34UKRiZtafUQ9+igfkAsA9+CnF77//jlWrVuGxxx5Ttq1btw7333+/8r1jx4448cQTsW7duiAD3+PxaBbccTgcmr8s4HQ64fF44Ha70djYaFrZPJ5GeF0uuJxOiI1uiG6gvqEBDkfipVEOhwMejweNjY3wer1wOp1wOBwghMDhcMDhcGiit0gSgej1TRp0OhxwuTwQvY3wuC1h68PtkWCxCIreNFaUdJ0OOBxZYY9rcDggum3wuly+33lccIiR28vtalSOdzY44HBE9iKLbidErwiPWzDcDzyeRojeRjQ6Haivz1DKFeo8jU6Hsl/0+NpEkiRs3LgRrdr3CPqto6FRs01uP0ejCNHrRFHXetTuy0ZDgwPZdntQeq5GJzK8LhB//3NIgOhyw+1yQvQ64WhwwOHICPk7L3z11yg4ddeJ2+2Gx+OBy+WCw+GA1+uF2+2O+HuPywVvhgtESs3xpb6hAV6XC6LLBa/oQmZRNbwul+8azoie33DXnll4XS5YbB54XNHHtIaGBmUM9Hg8aGjQH7Gm0elUrjG3N3wfkSQC0dMIr8vXDzz+a7PRGblfiS43JJcLTrfDcL9wuVxwu92wWCxwuVyYdO8mAMAnT/aK+lt3Y6O/vcWIY2fIPMtjQWP48VONt9EFwQI0kOjXmMfVCLhcEDwEXjfgdIopeb0YRb4PNzY2wuPxoL6+PmHnltuuvtEK0eOC1+WFy99v3S7945pR5LIE3ofDUV/v0ozzke4hycLldMDrckFodMHryojpXmkU+fxmv60SSJLeh73++utYuHBh2P1DhgzBzJkzg7ZPnz4da9aswfr165VtNpsN7733Hi688EJl2+DBg3HWWWfhwQcf1Pz+3//+N+67774ElIDD4XA4HA6HwzHO4cOHUVpaatr5k+bBP/PMMyMWrFWrVkHbXC4XFi1ahEceeUSzPSMjA42NjZptjY2NyMzMDDrHzJkzMWPGDOV7Q0MDWrRogcrKyuN2Um4643Q6UVxcjKqqKmRnZyc7OxyD8PZLX3jbpTe8/dIX3nbpjcPhQElJCZo1a2ZqOkkz8Dt16oROnToZ+s3bb78Nr9eL8ePHa7Z37doVO3bsUL6Loog9e/bghBNOCDqH3W6HPcQr/5ycHH6hpDHZ2dm8/dIY3n7pC2+79Ia3X/rC2y69kednmHZ+U8+eYObPn49rrrkmyNN+xRVX4OWXX8axY8cAAIsWLYLL5cLIkSOTkU0Oh8PhcDgcDidppM0k282bN+Obb77B//73v6B906dPx9q1a9G1a1e0b98eu3btwosvvoji4uIk5JTD4XA4HA6Hw0keaWPgFxQUYPXq1Tj55JOD9mVlZeHTTz/F1q1bUVVVhV69eqGgoEDXeW02G+69917YbGlTFRwVvP3SG95+6Qtvu/SGt1/6wtsuvaHVfkmLosPhcDgcDofD4XAST1pp8DkcDofD4XA4HE5kuIHP4XA4HA6Hw+EwBDfwORwOh8PhcDgchjjuZ2js2LEDW7ZsQfv27dGnT59kZ4fj55dffsFvv/2m2dazZ0/07NlT+e7xeLBu3TrU1NRgwIABQQunRdvPSRxLly6F0+kEAHTs2BEDBw4MOqa8vBzfffcdCgsLMWjQoKD1KOLdz4mNAwcOYM2aNcr38847Dy1btlS+79+/H2vXrtX8pm3bthg8eLBm248//oh9+/ahZ8+e6Nq1a1A60fZzYmffvn3YtGkTSkpK0LdvX1itVs3++vp6rF27FoQQnHXWWcjLy0vofk7siKKIn376CUeOHEGPHj3QuXNnZV9DQwM++ugjzfHZ2dm46KKLNNui2THczjGPhoYGrF+/Hl6vF6effnpQ9MZ47ZS47BhyHDN79mySl5dHzj//fFJaWkouvvhi4vF4kp0tDiFkxowZpGPHjmTcuHHKvyVLlij7jxw5Qnr27ElOPPFEMmTIENKsWTND+zmJZerUqWTcuHGkU6dOZNy4cUH73377bdKsWTMyZMgQ0rVrV9KrVy9y5MiRhO3nxM4PP/xAxo0bRy6//HICgKxatUqzf8mSJSQvL09zLT788MPKfo/HQy666CLSqlUrcv7555O8vDxyzz336N7PiZ2Ghgbluhs9ejQpKysjXbt2JXv27FGO2bhxI2nZsiXp27cv6devH2nRogX56aefErafEzurV68mPXr0IH369CGjRo0iubm55JZbblH279mzhwAgY8eOVa69qVOnas4RzY7hdo55LF68mHTp0oUMGzaMDB48mDRr1oy8+uqryv547ZR47Zjj1sD/6aefiCAIZP369YQQQsrLy0nLli3JggULkpwzDiE+A//qq68Ou3/q1Klk4MCBxO12E0IIee6550hhYSGpr6/XtZ9jDpMmTQoy8Ovq6khBQQF57rnnCCGEuFwuMmDAAHLjjTcmZD8nMTidzrAGfrdu3cL+7oUXXiAtW7Yk5eXlhBBC1q9fTwRBID///LOu/ZzYOXr0KHnrrbeIJEmEEEK8Xi8ZPHiwZuzs378/mTx5svJ96tSppE+fPgnbz4md5cuXk507dyrfN23aRACQNWvWEEKaDPy6urqQv49mx3A7x1yWLVtGamtrle9z584l+fn5RBRFQkj8dkq8dsxxa+Dfc889QYPUjTfeSEaPHp2kHHHUzJgxg4wYMYJ88MEHZM2aNUEdOnCQcjqdJCsri3z00Ue69nPMIZSB/+GHH5KsrCzidDqVbQsWLCClpaUJ2c9JDJEM/E6dOpFly5aR5cuXk4qKCs3+UaNGBT1s9enTh9x777269nMSy0033USGDx9OCCHk4MGDBAD58ccflf0bN24kAMi+ffvi3s9JLC6Xi2RlZZH333+fENJk4H/44Ydk2bJlZO/evZrjo9kx3M6hy6effkoyMjKIy+UihMRvp8Rrxxy3k2x3796NLl26aLZ17twZu3fvTlKOOGp69+6NgoICvPbaa5g6dSrKysqwcuVKAD7N25EjRzTtl5WVhdatW2P37t1R93Posnv3brRp0wZZWVnKts6dO6O8vBwOhyPu/Rxzad++Pfr3749FixbhnnvuQceOHTFv3jxlf7SxlI+19Dh8+DDeeecdXHrppQCg1LG6/mWN9+7du+Pez0ksCxYsQG5uLs455xwAQG5uLsaNG4fXX38dTzzxBE466SRMmzZNOZ5fe8nnwIEDWLx4MZ566in8/e9/x6OPPoqMjIy47ZRE2DHH7SRbr9eLjIwMzbbMzEx4vd4k5Yij5sorr8SVV16pfJ85cybGjx+PQ4cOKW0Urv2i7efQJdy1Ju+Ldz/HXPr374/Fixcr399//31cfvnlGDp0KE488cSoYykfa+lw7NgxjBo1CsOHD8cNN9wAACHHQvW1Q/zrXMa6n5M4PvroI/zzn//Ee++9h+bNmwMAWrRoobn2fvvtN/Tv3x9nn302xo0bx6+9FODQoUP44IMPcOTIEXi9XhQWFgIIfe0B+u2URNgxx60Hv7S0FIcPH9ZsO3z4MI+0kqJMmTIFlZWV2L17N/Ly8pCdnR3UfuXl5SgtLY26n0OX0tJSlJeXa7YdPnwYOTk5yMvLi3s/hy6XXHIJCgoK8OOPPwKIPpbysdZ8jhw5gnPPPRe9e/fGokWLlO1yHavrX/5cWloa935OYliyZAmuueYavPfeexg6dGjY43r06IFBgwbh+++/B8CvvVSgT58+WLx4Mb788kssXLgQ1157LbZv3x63nZIIO+a4NfDPOeccrFu3DtXV1QAAQgg++eQT5dUYJ7kEGnQbN26ExWJBmzZtYLFYMHjwYCxbtkzZL7fl4MGDo+7n0GXw4MGorq7GN998o2z7+OOPMXjwYAiCEPd+jrkEXot//PEHqqur0a5dOwC+sfSTTz5RvL3V1dVYt26dMpZG28+Jj/3792Pw4ME466yz8NJLL8Fiabqtn3jiiWjdurVmLPz444/RsmVLnHTSSXHv58TPyy+/jKlTp+LDDz8MMu4Dr73GxkZs375dc+1FsmO4nWMuge3TpUsXEEJQW1sbt52SEDsm5tkEaY7X6yUDBw4kAwYMIM899xy59NJLSevWrZVID5zk0q9fP3LHHXeQF198kcycOZMUFBSQf/3rX8r+b7/9lmRlZZHbb7+dPP3006RDhw5k2rRpuvdzEstXX31F3nzzTXL22WeTgQMHkjfffJOsXLlS2X/zzTeTjh07kqeffprcfvvtJCsri3z33XcJ28+Jnfr6evLmm2+SV155hQAgs2fPJm+++Sb5448/CCGEXHvttWTSpEnk+eefJ4888gjp1KkTGTFihBIpory8nLRu3ZqMHTuWPPfcc6R///5k0KBBuvdzYqeqqop06tSJ9O7dm7z55pvKv2XLlinHvPTSSyQnJ4c88MAD5IEHHiC5ubnkhRdeSNh+Tuy89tprRBAEMn36dE37bd++nRBCyFNPPUVGjBhBnn76afLMM8+Q/v37k7KyMnLs2DFCSHQ7hts55tK3b18yffp08tJLL5HHHnuMdO/enZxzzjlKGNJ47ZR47RiBEL9b5TikoaEB8+bNw6+//or27dvj5ptvRtu2bZOdLQ4Ap9OJhQsX4qeffkJRURFGjhyJIUOGaI7ZuHEjFi5ciNraWpx77rmYOHGixnsVbT8ncTz00EPYuHGjZluPHj1wzz33AAAkScIrr7yC1atXIz8/H3/961/Ru3dv5dh493Nip6KiArfeemvQ9ttuuw0DBw4EIQRvv/02vvrqK2RmZmLAgAG44oorNNfSgQMHMG/ePOzfvx89e/bEzTffjNzcXN37ObGxf/9+3HnnnUHb27Zti8cff1z5/sUXX+Cdd94BAFx66aUYMWKE5vh493NiY+HChfj888+Dtk+aNAkjR44EAKxevRoffPABGhsb0atXL0yaNElz7USzY7idYx6ynbJhwwbk5eVhwIABGDt2rGYRxnjtlHjsmOPawOdwOBwOh8PhcFiDuzM5HA6Hw+FwOByG4AY+h8PhcDgcDofDENzA53A4HA6Hw+FwGIIb+BwOh8PhcDgcDkNwA5/D4XA4HA6Hw2EIbuBzOBwOh8PhcDgMwQ18DofD4XA4HA6HIbiBz+FwOElmy5YtuOyyy9C3b19s2LAh2dlJCSorKzFixAi43e6EnfPee+/Fe++9l7DzcTgcTqrCDXwOh8NJMuPGjUOvXr3w3HPP4cQT/7+9Owup6uvDOP71lHa0SdNKrdRU/ko2kANYVqRlpaXQRJkXzREREWQQmIU0SNBMg6Y3dVEWFA1YFyKWBRaloCRppVk0UM6IVpj1XsR/v57UVPBFPe/zgQPn7L38rXX2hTx7WOv809fD6RcOHz5MYGAgdnZ2vVYzNjaW3bt38+PHj16rKSLSH+mXbEVE+lBNTQ0uLi7U19czcuTIvh5Ov9DU1IS7uzuFhYX4+PgAkJKSQk1NDUePHrVom5iYiJ2dHfv37+9W7alTp5KcnMzSpUt7fdwiIv2FruCLiPShmpoaAIYOHdrHI+k/srKyGD9+vBHuAd6+fcvr16/btS0vL+fNmzfdrh0bG0tmZmavjFNEpL9SwBcR6SP5+fksW7YMgNDQUMLDwwG4desW69ev5+rVqyxfvpzNmzcDv4NvXFwc4eHhJCQkUF9fb9T69esXp06dIjIyktWrV/Po0SPCwsJ48eIFAJs2beLWrVsW/YeGhvLy5Uvj89/qJyQkkJqayoEDB4iMjGT58uU8ffrUol5WVhZr1qwhIiKCI0eO0NraSm5uLosWLaLtzeKWlhbmzp3L48ePOzwujx49Ijg4uIdH8/dJQHBwcLtX2+8dEhLCw4cPe1xbRGQgUcAXEekjAQEBJCcnA3D27FlOnDgBQFVVFZcvXyYzM5Nt27aRkJDA+fPn2bJlCwsXLmT//v1UV1cTERFBa2srAPv27ePkyZNs3bqV+Ph4tm/fTn5+Pk1NTQCUlpZSVVVl0f+zZ89obm4G6LL+69ev2bVrF7a2tiQlJeHh4cHixYuNvz9z5gxr165l9uzZJCUlUVdXx7lz55g5cyYFBQVkZ2cb/d64cYOysrJOQ3xlZSXu7u49Pp5jx44lNTXVeK1bt46ysjK8vb2NNu7u7nz69ImWlpYe1xcRGSgG9/UARET+X40YMYKAgAAAgoKCGDz4v/+Shw4dypUrVzCbzQDMmDGDixcvEhMTA8Ds2bPx9vYmNzeXiIgIjh8/zvXr11m0aBEAbm5uhISEdHssiYmJndafP38+ACtXrmTPnj0AzJo1i7S0NEpKSggODmbv3r2cP3+euLg4AMLDw/n+/TtDhgxhw4YNpKamsmDBAgAjfLf9vm19//69w8m1Dx48aHdSUFFRQWxsLABms9nY/+rVKw4dOsS1a9eYMmWK0X7IkCFGH7a2tt0+PiIiA4kCvohIP+Tj42OE+48fP1JXV0diYqJxxR+gtraWV69e4efnR3NzM0FBQca+6dOnY2Nj062+uqr/b8D39fU19plMJkaMGEFDQwMfPnygoaGBsLAwi7r/humtW7fi7+/Px48faWxsJC8vj4yMjE7HM2bMGGpra9ttnzZtWoeTbP/05csXoqKiOHjwIFFRURb7amtrMZvNDBs2rNP+RUQGOgV8EZF+aNCgQcZ7R0dHTCYTSUlJTJw40aKdh4cHDg4OwO8Ju6NHjwZ+B9m2z73b2tpaLA/Z3NzMz58/u1W/K87OzphMJj5//txh+4kTJzJv3jwyMjKoq6sjPDzcYgLtnwIDA7lz50677Y6Oju2u4Ds5OVl8bmpqYsmSJcTHx7Nx48Z2NYqLiy1OhERErJGewRcR6eccHByIiYnh9u3bBAQEEBwczPTp03n27Bnfvn1j2LBhzJ07lyNHjhihPSUlxaKGr68vOTk5Rug/ffq08b6r+l2xt7dn8eLFJCUl0djYCPx+dObu3btGm23btpGens6lS5eMScOdiY6O5unTp3z9+rX7BwlobW1l1apVTJ482eJORFv3798nOjq6R3VFRAYaBXwRkQEgPT2d5uZmXF1dCQgIYNSoURQXF+Pi4gJAWloa+fn5jBs3jgkTJlBbW2vxHHtCQgJPnjzB09MTT09PKisrLe4SdFW/KxcuXMDGxgZ3d3f8/PyIiopiwoQJxv7o6GgGDx6MyWTqcg16Pz8/goKCuHnzZg+OENy7d4+srCwKCws7XEWnoaGBnJwc1q9f36O6IiIDjX7oSkSkD3379o3nz59bPHpSXV1NdXU1/v7+7do3Njby/v17vLy8sLe3t9j369cvysvLcXZ2xsnJCbPZbLHkZEtLCxUVFbi6ujJy5EgKCgqYNGmSRZ3O6peXl+Pg4ICbm5uxraioCG9vb4YPH25sq6uro7q6Gl9f33ZzAObMmUNISAjHjh3r8rjk5eWxc+dOCgsLAXj37h0tLS3tHu2pqKjAZDLh5eVFfX19h2vle3l54eLiwsGDB6mqquLUqVNd9i8iMpAp4IuIWKk/A35fKi4uJjAwkNLSUovJun9TVFTEpEmTem21m9LSUsaPH68JtiJi9TTJVkRE/qdWrFhBdnY2O3bs6Ha4h9+r5vSmju6IiIhYI13BFxGxUoWFhfj7+xur7PSVkpISzGbzX1fOERGR3qOALyIiIiJiRbSKjoiIiIiIFVHAFxERERGxIgr4IiIiIiJWRAFfRERERMSKKOCLiIiIiFgRBXwRERERESuigC8iIiIiYkUU8EVERERErMh/APij0+d6cP11AAAAAElFTkSuQmCC", + "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 +} diff --git a/notebooks/taptools_py.py b/notebooks/taptools_py.py index 20acb6b..5d5409b 100644 --- a/notebooks/taptools_py.py +++ b/notebooks/taptools_py.py @@ -216,6 +216,29 @@ 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), + "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 +837,106 @@ 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 + 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..e1a148c 100644 --- a/tests/CMakeLists.txt +++ b/tests/CMakeLists.txt @@ -12,9 +12,11 @@ FetchContent_Declare( FetchContent_MakeAvailable(Catch2) add_executable(taptools_kernel_tests + adsr_test.cpp 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/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/tests/harmonizer_test.cpp b/tests/harmonizer_test.cpp new file mode 100644 index 0000000..31d3e78 --- /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..a5bacc6 100644 --- a/tools/capi/taptools_capi.cpp +++ b/tools/capi/taptools_capi.cpp @@ -6,9 +6,11 @@ #include "taptools_capi.h" // The DSP cores are the same headers the Max externals compile — no Max/Min dependency. +#include #include #include #include +#include #include #include #include @@ -757,6 +759,124 @@ 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]); + } + }); +} + +// ---- 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 ca6be9f..6429155 100644 --- a/tools/capi/taptools_capi.h +++ b/tools/capi/taptools_capi.h @@ -252,6 +252,39 @@ 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); + +// ---- 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;