# Gneiss — User Manual

<sub>Gneiss v1.0.1 · manual updated 2026 Jul 06</sub>

Gneiss is a morphing multi‑stage filter. Two resonant pre‑filters feed a Moog‑style ladder that can drive and **break** — and it's that last stage that turns the whole thing from "a nice filter" into a playable chaotic system. This manual explains both halves: the filter you can predict, and the instrument you steer by feel.

---

## 1. What Gneiss actually is

Below a certain point Gneiss behaves the way you'd expect from a good filter: set a cutoff, add resonance, pick a slope, color it a little. As long as break is off and the pre‑filter resonance isn't cranked, that's exactly what you get — a clean, musical, well‑behaved filter with a genuinely nice ladder at its core.

Turn **break** up, or push resonance into self‑oscillation, and it stops being a filter in the textbook sense and becomes a wild feedback system. A filter is only one of the states such a system can settle into. Once you're in the others, the controls don't lie to you, but they stop meaning what their labels promise. A few things to expect:

- some parameters keep their obvious sense — cutoff still moves the centre of things;
- some invert — in certain regimes a push on drive can *settle* a sound rather than intensify it, or more resonance collapses a tone into a click;

That's just the material. And like any chaotic system, it's exquisitely sensitive to what you feed it — both the spectrum and the *level* of the input change which regime you land in. That's why Gneiss tends to bloom on drums, percussion, and busy rhythmic busses: transient‑rich, level‑varying material walks the system through many states per bar, and you get colour and structure that a sustained pad would never coax out.

A useful way to hold the whole thing in your head:

1. **Pre‑filters = preparation.** Shape and colour the input before it hits the chaos — emphasise a band, notch something out, add a resonant bump for the ladder to chew on.
2. **Ladder + break = the live interaction with chaos.** This is where you play.
3. **Damping = your handle on it.** One block that lets you dial *how much* chaos and ring survives, and *how hard* the colouring bites. Don't skip it (see §5).

> A trick worth knowing early: a pre‑filter pushed into high resonance and played from **MIDI note mode** (§11) becomes a tuned resonator — set to the track's key, it welds a loop or a burst of noise into the harmonic structure around it. To pitch a cutoff without MIDI, hold **Alt**/**Opt** while dragging it and it lands right on the note grid.

The reason **morphing** (§8) matters so much here: when the parameter space is this non‑linear, sweeping one knob at a time is a poor map. Dropping a handful of points you like and gliding between them is the best balance of control and surprise there is — you mark islands of predictable behavior out of an ocean of chaos and travel between them on purpose.

---

## Start here — your first few minutes

The fastest way to get Gneiss is to let it show you how much it cares about its input:

1. Drop a synthetic, punchy drum loop and a live / acoustic loop back to back on one track, through a single Gneiss — so you're comparing the two under the exact same settings.
2. Loop playback and step through the **presets** (`‹ ›`).
3. Listen to how differently the *same* preset treats the two — where one crunches and rings, the other stays smooth, and the other way round.
4. On a preset you like, nudge the resonant pre‑filter frequencies (§3): they "select" which part of the input becomes central downstream — tune one to the kick's fundamental and it picks up real gravity through the ladder. Hold **Alt** (**Opt** on a Mac) while setting a cutoff to snap it straight onto the note grid.

With one instance and one setting you hear straight away how headroom, the background noise of a live take, and average loudness push the system into different regimes (§1). What you get is as much about the material as the settings. Once a preset grabs you, open **MORPH** and drag between its points, or bring **break** up and nudge **character** — but the preset pass above is the quickest way in.

---

## The window at a glance

- **Three tabs:** **ALL** (every control), **FREQS** (per‑filter frequency + MIDI‑note playing), and **USER** (a layout you build yourself).
- A **preset strip** sits on every tab — name in the middle, `‹ ›` to step through.
- A **MORPH** toggle, separate from the tabs, drops the window open downward into the morph pad. Turn it on when you want to steer the sound as a field rather than as knobs.
- Drag the bottom right corner to resize the UI.

---

## 2. Signal flow

```
in ─▶ pre‑filters A & B (parallel/sequential routing) ─▶ MAIN LADDER ─▶ mix ─▶ gain ─▶ out
          (resonant)                                     saturation (drive), break
```

Everything runs **oversampled** (see §7). The two pre‑filters and the main ladder are two different kinds of filter, and it's worth knowing which is which:

- **Pre‑filters A and B** are **state‑variable filters** — resonant, surgical, and able to ring or self‑oscillate on their own. Think of them as tunable resonators you place in front of the ladder.
- **The main filter** is a **Moog‑style transistor ladder** — the warm, saturating, 4‑pole character, and the stage where drive and break live.

---

## 3. The pre‑filters — the preparation stage

Each pre‑filter (A and B) has four controls:

- **Freq** — cutoff. Hold **Alt** (**Opt** on Mac) while dragging to snap it to the nearest note.
- **Res** — resonance. Low and gentle for tone‑shaping; high for a ringing resonant peak that pushes the ladder hard.
- **Pass type** — **LP, HP, BP, BR** (band‑reject / notch), **P** (peak). Pick the shape.
- **Detune** — splits the filter across the stereo field (left drifts down, right up), in cents. A little adds width and beating; a lot smears.

Used gently, the pre‑filters are just pre‑EQ / pre‑colour. Pushed into high resonance, they become the thing that *provokes* the ladder — a loud resonant bump is often what tips the main stage into its more interesting behaviour.

### Routing — how the pre‑filters feed the ladder

Three controls decide *how much* of the pre‑filter shaping reaches the ladder and in what form:

- **Processing order** — crossfades the two pre‑filters from **parallel** (A and B side by side) to **sequential** (input → A → B). Sequential stacks their shapes; parallel keeps them independent.
- **Band mode** — a crossfade with three landmarks: **pass** (the ladder hears only the band the pre‑filters passed), **bypass** (the ladder hears the full signal — pre‑filter colour effectively out of the way), and **stop** (the ladder hears only the *complement* — what the pre‑filters rejected). This is your pre‑filter wet/dry, with a sign.
- **Neg band mix** — mixes the untouched complementary band back in *around* the ladder, in parallel. Handy for keeping the body or low end intact while the ladder mangles a narrow band.

Band mode is one continuous control from **stop** (−) through **bypass** (centre) to **pass** (+). At the exact centre the ladder receives the raw input and the pre‑filter shaping is inaudible — so if you've dialled a pre‑filter and hear nothing change, band mode is probably sitting at centre. Move it toward **pass** to hear the filtered band, toward **stop** to hear its inverse.

"Negative band" is computed *after* the ladder, from the unprocessed complement, so neg‑band mix is a clean parallel dry path — it can be pushed past unity for emphasis. AP (all‑pass) is intentionally not offered on the pre‑filters; the ladder keeps it.

---

## 4. The main filter — the Moog, and the chaos

The ladder's own controls:

- **Cutoff / Res / Detune** — as you'd expect. **Alt**/**Opt** on the cutoff snaps it onto the note grid, and the readout switches to note names.
- **Pass type + variation** — LP, HP, AP, BP, BR, P, plus a **variation** knob that morphs the response *within* a type (e.g. the effective slope / character of an LP).
- **Drive** — saturates the signal.
- **Drive variation** — a **continuous ring** of saturation curves. It's an endless knob: you can sit *between* two curves for an in‑between shape, and it wraps around with no end stop. Drive sets how hard you hit it; Variation sets what the "hit" sounds like.

Heads‑up for later: when you **morph between two different pass types** (§8), the pass‑type selector can read *unselected* and the variation knob grey out, with a **USER BLEND** plate in their place. That's expected — a filter shape with no single name, and often a good place to be.

Under the surface, the ladder's response is a mix vector across its poles, and any single pass‑type is just one way to produce that vector — the **USER BLEND** plate simply shows the resulting mix. You can drop the full component readout into the USER tab if you want to see the numbers.

---

## 5. Damping — don't skip it

It's easy to walk past **damping** as a noise gate. Don't. It's the block that gives you real control over how much ring, chaos and self‑oscillation actually survives — which makes it a real sound‑design tool, well beyond cleanup. Three controls:

- **Thresh** — the input level below which damping engages. Low thresholds only tuck in the tails; high thresholds engage on most of the material, which makes the filter choke and crunch on transients — a deliberate effect, and often exactly what you want.
- **R (release / decay)** — how fast energy bleeds away once damping engages. Short = tight and gated; long = a slow drain; all the way up reads **inf** (off).
- **H (hold)** — how long it waits after the input drops, *and* how soft the whole action is. At **H 0** it's instantaneous and gritty (it reacts sample‑by‑sample, pre‑envelope); raise it for a smoother, more forgiving grab.

Some concrete uses:

- **Articulation** — clamp the decay of each hit so a busy loop stays articulate instead of turning to mush.
- **Transient work** — set the threshold high (−18 dB or higher) with hold and release at zero. Damping now drains almost everywhere and opens only on the loudest peaks, so the filter speaks in short, sharp bursts locked to the transients. Bring **break** up and its chaos rides along — pinned to those well‑defined high‑amplitude windows, painting the hits and leaving the quieter parts clean.
- **Taming ring and self‑oscillation** — especially a **low resonant frequency that a kick keeps re‑triggering** in a drum loop. Damping lets the resonance speak on the transient and then get out of the way before it booms.
- **Metering the chaos** — because it drains the very feedback that break and high resonance feed on, damping doubles as a *chaos‑amount* and *colouring‑intensity* knob. Back it off for more mayhem, bring it in to keep only the good parts.

Whole presets can be built on this: a high threshold with short, snappy **H** and **R** makes damping the main voice of the patch — sharpening transients and adding grit and texture rather than just taming a tail.

Mechanically, a per‑channel envelope follower watches the raw input and, sample by sample, decides whether to drain. The two filter families are drained differently by design: the pre‑filters get a gentle state decay; the ladder gets a self‑shrinking kill on its *feedback* (a hard reset there would click at high resonance) with a smooth recovery ramp on release. The **H** knob also scales that recovery softness, which is why H 0 is the gritty, immediate setting and higher H is progressively smoother.

---

## 6. Break — the chaos engine

**Break** is where Gneiss stops being a filter. It's a family of nonlinear shapers folded into the ladder's feedback — turn it up and the whole system tips out of "filter".

- **Break (intensity)** — the master amount. At 0 the whole stage is dormant. Bring it up and the ladder starts to bend, fold, and misbehave.
- **Character** — chooses the *flavour* of the misbehaviour. Under the surface there's wavefolding, bitcrushing, click generation, and a spread of other shapers — and because it's a **continuous** control, you can sit between two flavours and blend them. It's less a menu than a coastline.
- **Variation** — a second dimension per flavour. For example, for bitcrushing it maps to bit depth.
- **Double** — folds the signal through the break stage a second time for denser, more saturated results.
- **FB inversion** — flips the sign of the broken feedback; a global change of behaviour rather than a tone tweak.

Because break lives inside a high‑quality ladder, the result goes well past distortion: many distinct bands of colour smeared across the spectrum of chaos, tracking pitch and level as it goes. This is the block where the semantics from §1 dissolve the hardest, and where feeding it drums or bass with sub-octave saw pays off the most.

---

## 7. Oversampling

Gneiss runs oversampled, selectable 1×–8×. For most patches, higher just means cleaner.

But because the interesting behaviour is genuinely nonlinear, a minority of regimes are mathematically sensitive to the oversampling rate — the exact artefacts shift, sometimes a lot, when you change it (the factory preset TRANSMISSION is one).

Oversampling lives in the **workspace** rather than the patch (§12): browsing the preset strip leaves it exactly where you set it, and it travels with a preset only when you open that preset from an `.fxp` file. So a browse can't dial in the right rate for you — which is why **OS‑sensitive factory presets carry a suffix in their name** giving the rate they were voiced at: a `…os4x` suffix, for instance, means 4× is the sweet spot. See a suffix, try matching the OS selector to it.

---

## 8. Morphing — the way to actually steer this thing

Open **MORPH** and the window extends into a pad. The pad already holds a set of **morph points** — each one a saved snapshot of the morph‑able parameters. You drag them where you want, switch each on or off (double‑click), and move a **user point** around the pad; the sound blends toward whichever *active* points are nearest. This is the intended way to navigate Gneiss: instead of hunting one knob at a time through a jumpy space, you keep a few sounds you like as landmarks and travel between them.

### The basics

- **Distance is the blend:** the params glide toward the nearest active points — the closer the **user point** sits to one, the more it weighs in.
- **Play vs edit** (the lock toggle on the pad):
  - **Play:** the normal knobs grey out and show the *resolved* blend — you're steering the blend, and the knobs just follow.
  - **Edit:** select a point and its sound loads into the knobs — turn them to reshape *that point*. Touch the user point to deselect and go back to blending.
- **Editing one point or all at once:** in edit mode you can select a single point, or target all active points together, so a knob move (or a RAND/MUTATE) reshapes the whole rig coherently.
- **Copy/paste a point's sound** — grab the sound from one point and drop it onto another (the point row's copy/paste). The quickest way to duplicate a sound and vary it.
- **Loading presets into a point:** while you're in edit with a point selected, choosing a preset (from the strip *or* an opened file) loads its sound **into that point** instead of swapping the whole patch — so you can build a rig out of factory sounds. (See §12.)
- **What morphs, and what sits out:** any parameter mapped to an **Absolute** MIDI CC (§10) is left out of the blend — that hardware knob keeps owning it wherever the pad sits. (A **Modulate** CC instead rides on top of the morphed value.)
- **Turning morph off keeps the sound:** if you moved anything, the resolved blend is written into the base patch on exit, so what you hear is what you keep.

### Contrast, weights, and the visuals

- **Distance contrast** — how sharply the nearest point dominates. Low = broad, gooey cross‑fades; high = crisp, almost‑switching transitions. **This one is audio** — it sets the sharpness of every move on the pad (the appearance sliders below only affect display).
- **Histogram** — the little bar display shows the **real, current weights** of the points, i.e. how much each one is contributing right now. Trust it; it's the actual blend.
- **Brightness / iso‑density / grid** — purely cosmetic (how the weight‑field map is drawn). Turn them up to see the field's structure, down to declutter. They don't touch the sound.

### Teleport — the seamless in/out

One point is special, with its own glyph: **teleport**. Its whole job is a glitch‑free transition between morphing and simple modes.

- **On entry:** turning morph **on** captures your current (pre‑morph) sound into teleport and parks it under the user point — so switching morph on changes nothing, and you drag away from your own patch.
- **You can tune it** like any point — edit its sound, drag it anywhere, even sit it on top of a morph point. But teleport's sound **isn't kept when you leave morph**: it's re‑captured from the current sound each time you enter, since seamless entry is all it's for.
- **On exit:** it's the **user point**'s sound — the resolved blend — that bakes into the controls and becomes your patch (the fold has the exact conditions).

---

## 9. Random and Mutate

Two buttons, one idea: generate coherent patches instead of random noise (well, *oftentimes* at least).

- **RAND** — a fresh patch. The frequencies land on real notes, the resonance/drive/pre‑filter choices are generally picked to go together musically.
- **MUTATE** — a *variation* of what you have. It keeps most of the patch and re‑rolls a fraction of it.

The part worth understanding is the **mutation session**. A run of consecutive MUTATE presses all explores variations of **one baseline** — press it five times and you keep circling the same sound. That baseline only re‑captures when you make **some other gesture**: load a preset, turn a knob by hand, hit RAND, or undo out of the run. So MUTATE is a "give me more like this" button, and it stays anchored until *you* decide to move the anchor.

While morphing, both act on points (§8), so RAND/MUTATE become ways to populate and vary a whole rig.

---

## 10. MIDI CC — mapping hardware to controls

Right‑click almost any control for a MIDI menu: **Learn** a CC, **Clear** it, and choose how it behaves. A small **presence dot** appears on any mapped control, so you can see what's bound and what's moving.

Every mapping is one of two modes:

- **Absolute** — the CC *is* the value, across a min/max range you can set. It writes the parameter directly, like automation. An absolute‑mapped parameter **overrides morph** (§8) and shows only the presence dot (no arc).
- **Modulate** — the CC is an *offset on top of* whatever the parameter already is — including the morph‑resolved value. This is the one that **composes**: morph decides the base, CC bends it from there. Modulate mappings draw an **arc**.

### Setting depth, and the visual language

- **Set Depth (Modulate):** arm it from the menu of a control, then **drag the knob** — the distance you drag becomes the signed depth, and the knob springs back to base. While armed, the **presence dot blinks** and the arc previews both directions. For **cutoffs**, a live `+1oct 2st 35ct` readout floats by the cursor as you drag (hold **Shift** for fine. The readouts are duplicated on the FREQS tab).
- **The arc** shows the reachable range at the current base value, coloured by source. A **live dot travels the arc** to show where the parameter *actually resolves* right now given the incoming CC — the resolved value itself, live, on top of the range.
- **Bipolar (±)** centres the CC on the base and swings both ways (a mod‑wheel that bends up and down); **Invert** flips the direction.
- **Clicking the presence dot** toggles Absolute/Modulate; while learning, the dot blinks too.

Your CC map is **workspace**: it's preserved when you step through presets (so your controller stays wired while you audition sounds) and it is *not* morph‑able — a mapping's identity is its `cc#→param` binding, which doesn't meaningfully interpolate between two points. A full project load restores it along with everything else. You can export/import the whole map as a file (§12).

---

## 11. Playing cutoffs with MIDI notes (FREQS tab)

Any of the three filter cutoffs — **main, pre‑A, pre‑B** — can be played from the keyboard instead of set by knob. The **FREQS** tab has a row per stage:

- **Note on** — hand this cutoff over to incoming notes.
- **Channel** — listen on **all** channels or a specific one (1–16). Because each stage has its own channel, you can play the three cutoffs from three different MIDI channels — e.g. a bassline driving the main cutoff while a separate part moves a pre‑filter.
- **Oct / Semi / Cent shift** — transpose this stage relative to the played note. Set an interval between the three stages and the whole filter structure tracks the keyboard in harmony.
- **Glide** — portamento time between notes.
- **Glide mode** — **legato** (glide only when notes overlap) or **always**.

### How this interacts with the rest

- **CC over a note‑played cutoff:** a CC in **Modulate** mode becomes a **pitch offset** (in octaves) on that cutoff — pitch‑bend for the filter. When a cutoff is note‑played its CC is kept in Modulate for you (Absolute would fight the note engine).
- **Morph + notes:** when a stage is note‑played, its *pitch* comes from the keyboard, so the cutoff frequency itself drops out of the morph blend — but the **shifts and glide are still morph‑able**. In practice: the note decides where you are, and morph moves the intervals and glide around it.
- **Note‑anchored display:** cutoffs authored on exact notes read as **note names** (`F#‑2`, `A4+`) instead of Hz, and stay readable as you morph near them.

Even without note mode, **Alt‑drag / Alt‑wheel / Alt‑click** on a cutoff snaps it to the nearest note and flips the readout to a note name. That "authored as a note" state travels with the patch and with each morph point, which is what lets the readout stay note‑named through a blend (within ±25 cents of an anchored note; it falls back to Hz in the gaps).

---

## 12. Saving and loading

Gneiss keeps two kinds of state, and they're saved and restored differently. Getting this straight saves a lot of "where did my morph rig go" confusion.

- **Patch** = the sound: the actual filter/break/etc. parameters.
- **Workspace** = the rig around the sound: the morph points and field, the morph on/off + XY, the MIDI‑CC map, the USER‑tab layout, the oversampling rate, and the UI scale/tab.

### What each action saves or loads

| Action | What happens |
|---|---|
| **Host saves the project** | **Everything** — patch *and* workspace — goes into the project. Reopen it and you're exactly where you left off. |
| **Preset strip `‹ ›` (browse)** | **Patch only.** Your workspace is *preserved* — morph rig, CC map, USER layout, oversampling and all stay put while you audition sounds. |
| **Open a preset file (`.fxp`) explicitly** | **The whole patch** — sound *and* the saved workspace: morph rig, mode, layout, and the oversampling rate. "Open this complete patch," as opposed to auditioning. |
| **Save a preset** | Writes the full state, so a preset carries its own rig and layout. |
| **Choose a preset while morphing + a point selected** | Loads that preset's **sound into the selected point** rather than swapping the whole patch (see §8). With no point selected, browsing is a no‑op. |

### Section files (`.hvoya`) — export one piece at a time

Beyond whole presets, three subsystems can be exported and imported **on their own** via `.hvoya` files: the **morph rig**, the **MIDI‑CC map**, and the **USER‑tab layout**. Each lives in its own named section of the file.

The rule to remember: **each import reads only its own section and ignores the rest.** So if you import a **CC map**, Gneiss pulls the CC section and *ignores* any morph‑rig or USER‑layout data that happens to be in the same file — and vice‑versa. A `.hvoya` can hold several sections at once, but each context takes only the slice it owns. Unknown or unrelated sections are left untouched, so files stay forward‑compatible.

---

## 13. The USER tab

The **USER** tab is a blank layout you fill yourself: pick the controls you actually reach for and arrange them in slots, so a complex patch collapses to the handful of knobs that matter for it. Edit/lock the layout, and **save / load / copy / paste** it — it travels as the `[user-tab]` section of a `.hvoya` file (§12), independent of the sound. Good for performance setups and for taming a patch down to its two or three live controls.

---

## Two Gneiss in series

One of the more rewarding setups is **two instances back to back**:

- The **first** on a **low mix** — just colouring the input: a resonant bump, a little break, something for the second stage to chew on.
- The **second** on **full or half mix** — the main character.

Because the first instance changes *what* the second is reacting to — and the whole thing is this sensitive to its input (§1) — small moves in the first stage open a wide space of textures downstream. Two modest settings will often out‑interest one extreme one.

---

## Quick reference

| Block | Controls | In one line |
|---|---|---|
| **Pre‑filter A / B** (§3) | freq, res, pass type, detune | Two resonant filters to prepare/colour the input |
| **Routing** (§3) | processing order, band mode, neg band mix | How much pre‑filter shaping (and which side) reaches the ladder |
| **Main filter** (§4) | cutoff, res, detune, pass type + variation | The Moog ladder |
| **Drive** (§4) | drive, drive variation (ring) | How hard you hit the saturator, and its curve |
| **Break** (§6) | intensity, character, variation, double, FB inversion | The chaos engine — wavefold / bitcrush / clicks and more |
| **Damping** (§5) | thresh, R (release), H (hold) | Your handle on ring, transients, and how much chaos survives |
| **Output** (§2, §7) | mix, gain, oversampling | Dry/wet, level, and the OS rate (a workspace setting — see §7) |
| **Morph** (§8) | points, teleport, distance contrast, histogram | Steer the sound as a field between saved landmarks |
| **MIDI** (§10–11) | CC learn (Absolute/Modulate), note mode per cutoff | Hardware control and keyboard‑played cutoffs |
