Modulator Bank — manual

Eight independent CV sources running alongside the tracks — LFOs, envelopes, random walks, chaos, and a struck-spring resonator — plus two bank-wide modes (JustF rate-link and the Geode rhythmic engine).

Introduction

The Modulator bank is a set of 8 independent CV sources that run alongside the tracks. Each slot generates a continuous control signal — an LFO, an envelope, a random walk, a chaotic attractor, or a struck-spring resonator — and routes it to CV outputs, the internal modulation bus, or MIDI. The bank is not a track: it has no steps and no pattern. It is a panel of motion you assign wherever you need it.

On top of the per-slot shapes sit two bank-wide modes that retune the whole set at once: JustF (a Just Friends / ochd-style rate link, M1 master + harmonic spread) and Geode (a 6-voice Just-Friends rhythmic engine). They are mutually exclusive and toggle from the same page.

Everything here is grounded in the firmware as built — defaults, ranges, enum members, key bindings, and label strings come from the model (Modulator.h, GeodeConfig.h), the engine (ModulatorEngine.h, GeodeEngine.h), and the UI (ModulatorPage.cpp).

Prerequisites

• Familiarity with the xformer page model (Page+ combos, F-keys, the encoder).
• Understanding of CV/gate conventions (1V/oct; the output stage where 64 = 0V).
• A destination in mind — a CV output, a routing target, or a MIDI CC.

Part 1 · Overview

The bank holds 8 modulator slots (M1..M8, CONFIG_MODULATOR_COUNT = 8). Each slot is one Modulator: a shape plus its parameters, evaluated every engine tick by ModulatorEngine into a single output in 0..127 (64 = 0V at the CV stage). That value is then routed.

A slot is always running — there are no steps to advance. What moves the output is the shape's own motion and the slot's gate behavior (free-run vs triggered/held).

Three things define a slot:

• Shape which generator runs (10 choices).
• Parameters the shape's controls; one canonical 15-field table, reinterpreted per shape.
• Routing where the output goes (CV / bus CV / MIDI), plus gate source and run mode.

Part 2 · The 10 Shapes

The shape is changed by focusing SHAPE (F1) and turning the encoder.

LFO shapes (Sine / Triangle / Saw Up / Saw Down / Square)

A bipolar waveform scaled by depth and shifted by offset, with a phase control.

Random

A sample-and-hold of a random value, slewed between samples. MODE decides when it samples (FREE = clocked, TRIG = on gate rising, HOLD = track-and-hold while gate high).

ADSR

A gated attack/decay/sustain/release envelope. Unipolar: rests at the floor, rises toward the amplitude ceiling. Two pages.

Page 1 — SHAPE / ATTACK / DECAY / SUSTAIN / RELEASE:

Page 2 — DEPTH (F3) / INVERT (F4) / OFFSET (F5):

State machine: Idle → Attack → Decay → Sustain → Release → Idle, driven by the gate source; output mapped through unipolarOutput(env, amplitude, floor, invert).

Chaos (Lorenz / Latoocarfian)

A chaotic attractor sampled into CV. Two pages.

Page 2: SLEW (_smooth, 0–5000 ms) on F1 and OFFSET on F5. P1/P2 reuse the ADSR attack/decay storage, curve-mapped to the attractor constants.

Spring

A 3-mode inharmonic resonator (a struck "spring"). Two pages. Spring relabels the reused fields.

Page 2: PICKUP (_phase 0–4: Position / Velocity / Kinetic / Potential / Total), DEPTH (strike force 0.7 × depth/127), OFFSET. Frequency ratios [1.0, 2.76, 5.40], semi-implicit integration, tanh soft-saturation. See docs/spring-modulator-spec.md.

Part 3 · Rate Domain, Mode, Invert, Offset

These four are shape-orthogonal — they apply across families.

Rate domain (Free vs Tempo)

Rate is domain-keyed. Re-pressing RATE when it is focused cycles the domain (on shapes that show RATE on F2).

• FREE — wall-time Hz, tempo-independent. Centi-Hz 1–1600 (0.01–16 Hz). Runs even when stopped.
• TEMPO — clock division, tempo-locked. PPQN ticks 6–6144. Freezes with the transport. (6 = 1/64 … 96 = 1/4 … 384 = 1 bar … 6144 = 16 bars.)

Mode (gate behavior)

For Random, FREE/TRIG/HOLD select clocked S&H / gate-triggered S&H / track-and-hold.

Invert, Offset / floor, Gate source

• INVERT — unipolar shapes duck from the top; bipolar shapes flip around the center.
• OFFSET — biases the value and sets the unipolar rest level via floorValue() = clamp(64 + offset, 0, 127).
• Gate source — when MODE is TRIG/HOLD (or Random is triggered): GateOut 1–8, CvIn 1–4, BusCv 1–4, Mod 1–8 (own index filtered out). Cycled in the routing overlay (F2 GATE).

Part 4 · JustF (Just Friends rate link)

JustF turns the bank into an ochd / Just Friends rate cluster: one master rate (M1) with the rest spread harmonically. It is not a shape — it is a runtime engine mode (_justfActive, _intone).

• M1 is the master; its Free-domain rate is the reference.
• INTONE (−1..+1, hosted on M2) is the spread. Noon = unison; CW = harmonic (Mₖ = k × M1); CCW = subharmonic (Mₖ = M1 / k).
• M2..M8 derive their rate from M1 + INTONE; on those slots the rate cell is read-only.
• A B-clamp caps the master so the fastest follower stays ≤ 16 Hz.

For ADSR followers, attack/decay/release spread by the same ratio per index; sustain is copied from M1; amplitude stays per-slot.

Part 5 · Geode (6-voice rhythmic engine)

Geode reskins the bank into a Just-Friends-style rhythmic / stochastic clock engine (GeodeConfig + GeodeEngine). Separate subsystem, mutually exclusive with JustF. Shift+SHAPE toggles it; turning it on parks M2's depth to 0 so the run signal starts neutral.

• M1 — the clock; its page 2 hosts the shared globals.
• M2 — the run source.
• M3..M8 — the six voices (VoiceCount = 6).

The five globals (M1 page 2)

Stored 0..16383; intone and curve are bipolar (8192 = centre).

Per-voice params (M3..M8)

Part 6 · The Modulator Page UI

The header reads MOD n - MODULATOR (or ROUTING / GEODE). Track buttons T1..T8 select the slot. The layout is a left rolling scope and a right param list.

• Left scope box (x=1, y=12, 119×40): a live rolling trace of the output, center line at the box midline.
• Divider at x=122.
• Right param list (x=124, 5 rows, Tiny font): each row is one F-key; name flush-left, value flush-right; the selected row is drawn in a bright box.
• CV routing label inside the scope box bottom-left (-> CV1,CV3) when assigned.
• A Pg n/m counter sits in the header's active-function slot on multi-page shapes.

F-keys (per shape)

• LFO / Random (single page): SHAPE / RATE / DEPTH / (PHASE | SLEW) / OFFSET.
• ADSR p1: SHAPE / ATTACK / DECAY / SUSTAIN / RELEASE. p2: – / – / DEPTH / INVERT / OFFSET.
• Chaos p1: SHAPE / RATE / DEPTH / P1 / P2. p2: SLEW / – / – / – / OFFSET.
• Spring p1: SHAPE / STRIKE / TENS / RING / CLANG. p2: PICKUP / – / DEPTH / – / OFFSET.
• Geode M1 p2: TIME / INTONE / RAMP / CURVE / MODE. Geode voice: VOICE / DIVS / REPEAT / TUNE / TIME.

Encoder, re-press, Shift, Page+

• Encoder turn edits the focused param; pressed + turn is fine resolution.
• Re-press SHAPE (F1) fires a one-shot audition pulse (ADSR / triggered-Random / Chaos-trig / Geode voice respond; a FREE-mode LFO ignores it).
• Re-press RATE (F2) cycles the rate domain Free ↔ Tempo.
• Shift+SHAPE toggles Geode; Shift+RATE toggles JustF.
• Right walks the cursor: param page(s) → routing overlay; Left walks back.

Part 7 · Routing the output

Press Right from the last param page to open the routing overlay (header reads ROUTING). The overlay is a membership grid — a modulator can drive multiple destinations at once.

• CV row — CV 1–8. MIDI rows — MIDI 1–16.
• Filled cell = assigned; the cursored cell is highlighted. Encoder turn moves the cursor; encoder push adds; F3 CLEAR removes.

Routing edits are staged; the context menu (Shift+Page) offers CANCEL (revert) and COMMIT (apply CV / MIDI assignments).

Beyond CV and MIDI, a modulator routes into Routing::Target — the routing engine's full target set: tempo, swing, mute/fill, per-track octave / transpose / probability biases, per-sequence first/last/divisor/scale, Tuesday / Stochastic / Fractal targets, the chaos and wavefolder effects, DiscreteMap, indexed modulation, and the BusCv 1–4 sinks.

Part 8 · Teletype ops (MO.* / G.*)

The bank is fully scriptable from Teletype 2. Modulator slots are addressed 1-based (1..8); Geode is single-instance. Ops live in TeletypeNativeOps.cpp; names in TT2OpNames.cpp.

MO.* — modulator slot ops

The MO.P addresses are the Modulator::Param table: Shape(0), Rate(1), Depth(2), Mode(3), Offset(4), Attack(5), Decay(6), Sustain(7), Release(8), Amplitude(9), Smooth(10), Phase(11), Invert(12), RateDomain(13), GateSource(14).

G.* — Geode ops

G.O, G.BAR, G.R are intentionally unregistered — no live GeodeConfig field; run goes through MO 2, bars through the transport.

How the ops map to the params

• MO.RATE / MO.DEPTH / MO.OFF / MO.MODE / MO.SHAPE set the same per-slot fields the F-keys edit; MO.TRIG is the script form of the SHAPE re-press audition.
• MO.P slot 14 … writes the gate source as a raw Routing::Source ordinal — unvalidated, no UI curation.
• G.TIME / G.TONE / G.RAMP / G.CURV / G.MODE are the five Geode globals (M1 page 2). G.TUNE writes a voice's tune ratio, G.V triggers the DIVS/REPEAT burst, and G.RUN / G.VAL drive and read the engine.

Part 9 · Setup summary

Per-slot params (the 15-field dictionary): Shape, Rate, Depth, Mode, Offset, Attack, Decay, Sustain, Release, Amplitude, Smooth, Phase, Invert, RateDomain, GateSource. Shapes reinterpret the labels (Spring → STRIKE/TENS/RING/CLANG/PICKUP; Chaos → P1/P2).

Defaults at clear(): Shape Sine, Rate 0.05 Hz (Free), Depth 25, Mode FREE, Offset 0, Attack 900 / Decay 1240, Sustain 100, Release 200, Amplitude 127, Smooth 100, Phase 0, Invert off, gate source GateOut1.

Each slot → 0..127 (64 = 0V) → routed to CV outputs / bus CV / MIDI via the routing overlay, or driven from Teletype MO.* / G.*.