{
  "$type": "at.atmosynth.module",
  "descriptionVersion": 1,
  "moduleId": "filter-ladder",
  "versionKey": "6",
  "name": "Ladder filter",
  "description": "A low-pass that sings, built as a transistor ladder is. Four poles with a feedback around them, and Resonance is how much: below one it emphasises what is at the cutoff, at one the feedback exactly makes up for what the poles take off, and above one the filter holds a tone of its own with nothing played into it at all — the whistle the Moogs are asked for, and the one thing the ordinary Filter cannot do however far its resonance is pushed. It sings at the cutoff the knob names, and starts to at one, however high the cutoff is set, so the whistle is in tune wherever it is. Slope is which pole the sound is taken after: 24 decibels an octave after the fourth, and 18, 12 or 6 after the third, second or first. The feedback goes round all four whichever it is, as it does on a Sub 37, so Resonance means the same at every slope and a gentler one keeps more of what is above the cutoff around the same peak. Nothing makes up the bass the feedback takes away: the further Resonance is turned the thinner the low end, which is how the filters this one follows sound. Cutoff and Cutoff depth work as they do on the ordinary Filter, in cents and negative to invert, and the depth reaches eight octaves either way, so an envelope can open a filter set low all the way to the top; Key tracking moves the cutoff with the note played, which needs the note routed here. Drive is how hard the sound is pushed into the filter, and each of its four stages saturates, as a transistor ladder's do: at one gently, and above it into a thick, compressed sound whose resonance swells and is held down by every stage it goes round rather than clipped on the way in. It is kept out of the feedback, so driving the filter does not move the point at which it starts to sing. What its curves leave off centre on a sawtooth or a narrow pulse is taken off below any note, so what comes out sits on centre. This module carries code: nothing in the vocabulary can be fed back into itself a sample at a time, which is the whole of what a filter like this is. Resonance is an input as well, and its depth how far a signal there moves it — an envelope into it makes the filter sing at the start of a note and settle as it decays. However far it is pushed, it stays inside the knob's own range.",
  "audioInputs": [
    {
      "id": "in",
      "label": "In"
    },
    {
      "id": "cutoff",
      "label": "Cutoff"
    },
    {
      "id": "resonance",
      "label": "Resonance"
    }
  ],
  "audioOutputs": [
    {
      "id": "out",
      "label": "Out"
    }
  ],
  "midiInputs": [
    {
      "id": "midi",
      "label": "Note"
    }
  ],
  "nodes": [
    {
      "id": "in",
      "kind": "moduleInput",
      "options": {
        "input": "in"
      }
    },
    {
      "id": "gen",
      "kind": "dsp",
      "options": {
        "code": "// A ladder filter: four poles, and a feedback around them deep enough that the\n// filter sings on its own. The node vocabulary cannot reach it — a\n// BiquadFilter is linear and unconditionally stable, so however far its Q is\n// pushed it rings after something excites it and then stops. The filters this\n// one is modelled on do not stop: past the point where the feedback makes up\n// for what the four poles take off, they hold a tone of their own at the\n// cutoff, and on those instruments that tone is played rather than avoided.\n//\n// Four one-pole lowpasses in series, the last one's output subtracted from what\n// goes in. A one-pole turns the signal an eighth of a cycle at its own cutoff,\n// so at the cutoff the four together are half a cycle round and the\n// subtraction has become an addition; each one also takes the level down to\n// about seven tenths there, so a feedback of four exactly makes up for the four\n// of them. That is what Resonance is scaled against: below one the filter\n// rings, at one it is on the edge, above it it sings.\n//\n// Every stage saturates, as every stage of a transistor ladder does. A stage\n// there is a pair of transistors charging a capacitor, and the current they can\n// push into it is the difference of two tanh curves, one of what arrives and\n// one of what the capacitor already holds. So each pole here moves by the tanh\n// of its input less the tanh of where it stands. For a quiet signal a tanh is\n// the straight line it starts as, so a quiet signal meets four plain poles. A\n// loud one finds every stage able to move only so fast, so a driven filter\n// thickens and compresses through all four rather than clipping at the door,\n// and a resonance pushed into it is held down by every stage it goes round.\n// What holds a tone that sings on its own at a level, rather than doubling\n// every cycle until it is a square, is all four of them.\n//\n// The output is taken after the fourth pole, or the third, second or first —\n// 24, 18, 12 or 6 decibels an octave — and the feedback after the fourth\n// whichever it is. That is how the Sub 37 does it: the loop stays four poles\n// round, so Resonance means the same at every slope and only what is listened\n// to moves. Nothing makes up the bass the feedback takes away, so the more it\n// resonates the thinner the low end, which is the sound and not a fault.\n//\n// Version 5 is this filter with the feedback a sample behind, and each pole's\n// tanh of where it stands read from before the sample too, run twice a sample\n// to halve what that costs. Up high a sample is still a large part of a\n// cycle, and both delays turn the loop half a cycle round below the cutoff,\n// which is where it sang: 44 cents flat at 440 Hz just past one, 160 at 2 kHz,\n// 400 at 6 kHz, and singing from under 0.9 at 2 kHz rather than from one.\n// Version 6 is solved with no sample's delay anywhere round the loop, as\n// filter-sem's is: the poles are trapezoidal and the chain, the feedback and\n// every curve in it, is worked out for this sample's own values, once a\n// sample. So it sings at the cutoff the knob names, from one, at the same\n// level at any height. What its curves do to the tone it sings is the\n// ladder's own, and the same at every height: dragged a little flat as it\n// swells, as version 5's is low down.\n//\n// Each curve is taken as the straight line from nothing to where it stands,\n// which makes the chain one that can be worked out in a line: each pole a\n// share of what arrives plus what it holds, so the last a share of what goes\n// into the first plus what the four hold, and the feedback folded into that.\n// The lines are the last sample's to begin with. Through them the chain says\n// where the sound goes in; the four poles are followed from there, each handed\n// the curve of what arrives as it is, and each line moved to where its curve\n// now stands; and the two are done once more. Every divisor is one plus things\n// that cannot be negative, so there is always an answer.\n//\n// Every curve here is the same either side of nothing, and still the filter\n// leaves a sawtooth off centre. A curve like that keeps a wave centred only\n// while the wave spends as long at each height as at the same depth below,\n// which a sawtooth does going in and no longer does once the poles have moved\n// its harmonics against each other, and which a narrow pulse never does. The\n// lean grows with the square of the level, and every voice of a chord leans\n// the same way, so a chord adds it up. So the output leaves through a one-pole\n// at 5 Hz, as the analog oscillator's does, which takes the lean off below\n// any note and leaves what is played as it was.\nimport { AtmoProcessor, Rng } from \"atmosynth:dsp\";\n\nfunction clamp(value, low, high) {\n  return value < low ? low : value > high ? high : value;\n}\n\n// A tanh, near enough: x(27 + x²) / (27 + 9x²), which leaves the origin at the\n// slope a tanh does and arrives at one at three with no slope left, where it\n// stays — taken as the slope of the straight line from nothing to where it is\n// at `value`: one at nothing and less further out, written so it divides only\n// by what is past three. It is a few multiplications and one division where\n// Math.tanh is a call, and it is arithmetic and nothing else, so the plugin\n// works it out to the same double, which two libraries' tanh need not do.\nfunction slope(value) {\n  const size = Math.abs(value);\n  return size > 3 ? 1 / size : (27 + size * size) / (27 + 9 * size * size);\n}\n\nexport default class AtmosynthLadder extends AtmoProcessor {\n  static spec = 1;\n  // Channel 0 of what arrives: a mono source arrives on both sides, and a\n  // stereo one is heard by its left.\n  static inputs = [2];\n  static outputs = [1];\n  // Not smoothed here: a knob's move reaches these already eased, and what is\n  // wired in is followed exactly.\n  static params = {\n    frequency: { min: 20, max: 20000, default: 1200, rate: \"a\", smooth: 0 },\n    // Eight octaves either way, so an envelope into the cutoff from a low\n    // setting can open the filter the whole way.\n    detune: { min: -9600, max: 9600, default: 0, rate: \"a\", smooth: 0 },\n    resonance: { min: 0, max: 1.2, default: 0.4, rate: \"a\", smooth: 0 },\n    // Into the first tanh, and only there: the feedback is left alone, so how\n    // hard the filter is driven does not move the point at which it starts to\n    // sing.\n    drive: { min: 0.1, max: 10, default: 1, rate: \"a\", smooth: 0 },\n    // Which pole the output is taken after, by the Slope choice's position:\n    // 24, 18, 12 and 6 decibels an octave are the fourth, third, second and\n    // first. Rounded, since a choice turned by a controller glides between\n    // positions on its way to one.\n    slope: { min: 0, max: 3, default: 0, rate: \"k\", smooth: 0 },\n  };\n\n  constructor() {\n    super();\n    // The four poles' integrators, first to last.\n    this.s1 = 0;\n    this.s2 = 0;\n    this.s3 = 0;\n    this.s4 = 0;\n    // Each curve's line, as the last sample left it: c0 the curve of what\n    // goes into the first pole, and c1 to c4 the curve of each pole, which it\n    // moves less by and the next is handed. Straight before anything arrives.\n    this.c0 = 1;\n    this.c1 = 1;\n    this.c2 = 1;\n    this.c3 = 1;\n    this.c4 = 1;\n    // The cutoff and detune the coefficient below was last worked out for:\n    // not yet any, which no value equals.\n    this.frequency = 0 / 0;\n    this.detune = 0 / 0;\n    this.coefficient = 0;\n    /** The 5 Hz one-pole on the way out, and the two samples it remembers. */\n    this.pole = 1 - (2 * Math.PI * 5) / sampleRate;\n    this.lastRaw = 0;\n    this.centred = 0;\n    // The dither below, drawn from the node's own generator.\n    this.rng = new Rng(this.seed);\n  }\n\n  process(inputs, outputs, parameters) {\n    const channel = outputs[0][0];\n    const source = inputs[0][0];\n    // In a browser's audio thread `sampleRate` is an accessor on the global\n    // scope rather than a variable, so it is read once a call.\n    const contextRate = sampleRate;\n    const ceiling = contextRate * 0.45;\n    const tap = clamp(Math.round(parameters.slope[0]), 0, 3);\n    const pole = this.pole;\n    let lastRaw = this.lastRaw;\n    let centred = this.centred;\n    let s1 = this.s1;\n    let s2 = this.s2;\n    let s3 = this.s3;\n    let s4 = this.s4;\n    let c0 = this.c0;\n    let c1 = this.c1;\n    let c2 = this.c2;\n    let c3 = this.c3;\n    let c4 = this.c4;\n\n    for (let index = 0; index < channel.length; index += 1) {\n      const frequency = parameters.frequency[index];\n      const detune = parameters.detune[index];\n      // A Math.pow and a Math.tan, worked out again only when they would come\n      // out different.\n      if (frequency !== this.frequency || detune !== this.detune) {\n        this.frequency = frequency;\n        this.detune = detune;\n        const hz = clamp(frequency * Math.pow(2, detune / 1200), 20, ceiling);\n        // The integrators' gain, prewarped so the cutoff lands where the knob\n        // says rather than flat of it.\n        this.coefficient = Math.tan((Math.PI * hz) / contextRate);\n      }\n      const g = this.coefficient;\n      const k = 4 * parameters.resonance[index];\n\n      // What starts it. An analogue filter is pushed into oscillation by its own\n      // noise; this one, handed digital silence, would sit at exactly zero for\n      // ever — and a filter that sings only once something else has sounded is\n      // not the thing being modelled. A millionth of full scale is a hundred and\n      // twenty decibels down, inaudible on its own and enough to grow into the\n      // tone within a note.\n      const x = parameters.drive[index] * source[index] + 1e-6 * this.rng.bipolar();\n\n      let y1 = 0;\n      let y2 = 0;\n      let y3 = 0;\n      let y4 = 0;\n      // Twice, both at this sample's moment: through the last sample's lines,\n      // then through the lines that puts each curve at.\n      for (let pass = 0; pass < 2; pass += 1) {\n        // A pole stands at what it holds, plus g of the curve of what\n        // arrives, less g of its own curve: through the lines, what it holds\n        // plus g of what arrives along its line, over one plus g of its own.\n        const r1 = 1 / (1 + g * c1);\n        const r2 = 1 / (1 + g * c2);\n        const r3 = 1 / (1 + g * c3);\n        const r4 = 1 / (1 + g * c4);\n        const a1 = g * c0 * r1;\n        const a2 = g * c1 * r2;\n        const a3 = g * c2 * r3;\n        const a4 = g * c3 * r4;\n        // So the last pole is a share of what goes into the first plus what\n        // the chain holds, and the feedback from it folds into what goes in.\n        const share = a1 * a2 * a3 * a4;\n        const held = ((s1 * r1 * a2 + s2 * r2) * a3 + s3 * r3) * a4 + s4 * r4;\n        const u = (x - k * held) / (1 + k * share);\n        // The four followed from there, each handed the curve of what\n        // arrives as it is, and each line moved to where its curve stands.\n        c0 = slope(u);\n        y1 = (s1 + g * c0 * u) * r1;\n        c1 = slope(y1);\n        y2 = (s2 + g * c1 * y1) * r2;\n        c2 = slope(y2);\n        y3 = (s3 + g * c2 * y2) * r3;\n        c3 = slope(y3);\n        y4 = (s4 + g * c3 * y3) * r4;\n        c4 = slope(y4);\n      }\n      s1 = 2 * y1 - s1;\n      s2 = 2 * y2 - s2;\n      s3 = 2 * y3 - s3;\n      s4 = 2 * y4 - s4;\n\n      // What its curves leave off centre, taken off under 5 Hz.\n      const raw = tap === 0 ? y4 : tap === 1 ? y3 : tap === 2 ? y2 : y1;\n      centred = raw - lastRaw + pole * centred;\n      lastRaw = raw;\n      channel[index] = centred;\n    }\n\n    this.s1 = s1;\n    this.s2 = s2;\n    this.s3 = s3;\n    this.s4 = s4;\n    this.c0 = c0;\n    this.c1 = c1;\n    this.c2 = c2;\n    this.c3 = c3;\n    this.c4 = c4;\n    this.lastRaw = lastRaw;\n    this.centred = centred;\n    return true;\n  }\n}\n"
      }
    },
    {
      "id": "cutoffin",
      "kind": "moduleInput",
      "options": {
        "input": "cutoff"
      }
    },
    {
      "id": "cutoffdepth",
      "kind": "gain",
      "options": {}
    },
    {
      "id": "note",
      "kind": "midiInput",
      "options": {
        "midiInput": "midi"
      }
    },
    {
      "id": "trackdepth",
      "kind": "gain",
      "options": {}
    },
    {
      "id": "trim",
      "kind": "gain",
      "options": {}
    },
    {
      "id": "out",
      "kind": "moduleOutput",
      "options": {
        "output": "out"
      }
    },
    {
      "id": "resonancein",
      "kind": "moduleInput",
      "options": {
        "input": "resonance"
      }
    },
    {
      "id": "resonancedepth",
      "kind": "gain",
      "options": {}
    }
  ],
  "connections": [
    {
      "from": {
        "node": "in",
        "output": 0
      },
      "to": {
        "node": "gen",
        "input": 0
      }
    },
    {
      "from": {
        "node": "gen",
        "output": 0
      },
      "to": {
        "node": "trim",
        "input": 0
      }
    },
    {
      "from": {
        "node": "trim",
        "output": 0
      },
      "to": {
        "node": "out",
        "input": 0
      }
    },
    {
      "from": {
        "node": "cutoffin",
        "output": 0
      },
      "to": {
        "node": "cutoffdepth",
        "input": 0
      }
    },
    {
      "from": {
        "node": "cutoffdepth",
        "output": 0
      },
      "to": {
        "node": "gen",
        "param": "detune"
      }
    },
    {
      "from": {
        "node": "note",
        "output": 0
      },
      "to": {
        "node": "trackdepth",
        "input": 0
      }
    },
    {
      "from": {
        "node": "trackdepth",
        "output": 0
      },
      "to": {
        "node": "gen",
        "param": "frequency"
      }
    },
    {
      "from": {
        "node": "resonancein",
        "output": 0
      },
      "to": {
        "node": "resonancedepth",
        "input": 0
      }
    },
    {
      "from": {
        "node": "resonancedepth",
        "output": 0
      },
      "to": {
        "node": "gen",
        "param": "resonance"
      }
    }
  ],
  "automation": [],
  "parameters": [
    {
      "id": "cutoff",
      "label": "Cutoff (Hz)",
      "range": {
        "min": "20",
        "max": "18000"
      },
      "default": "1200",
      "targets": [
        {
          "node": "gen",
          "param": "frequency"
        }
      ],
      "scale": "log"
    },
    {
      "id": "resonance",
      "label": "Resonance (sings above one)",
      "range": {
        "min": "0",
        "max": "1.2"
      },
      "default": "0.4",
      "targets": [
        {
          "node": "gen",
          "param": "resonance"
        }
      ]
    },
    {
      "id": "slope",
      "label": "Slope (per octave)",
      "values": [
        "24 dB",
        "18 dB",
        "12 dB",
        "6 dB"
      ],
      "default": "24 dB",
      "targets": [
        {
          "node": "gen",
          "param": "slope"
        }
      ]
    },
    {
      "id": "drive",
      "label": "Drive",
      "range": {
        "min": "0.1",
        "max": "10"
      },
      "default": "1",
      "targets": [
        {
          "node": "gen",
          "param": "drive"
        }
      ]
    },
    {
      "id": "cutoffAmount",
      "label": "Cutoff depth (cents)",
      "range": {
        "min": "-9600",
        "max": "9600"
      },
      "default": "2400",
      "targets": [
        {
          "node": "cutoffdepth",
          "param": "gain"
        }
      ]
    },
    {
      "id": "keyTrack",
      "label": "Key tracking",
      "range": {
        "min": "0",
        "max": "2"
      },
      "default": "0",
      "targets": [
        {
          "node": "trackdepth",
          "param": "gain"
        }
      ]
    },
    {
      "id": "level",
      "label": "Level",
      "range": {
        "min": "0",
        "max": "2"
      },
      "default": "1",
      "targets": [
        {
          "node": "trim",
          "param": "gain"
        }
      ]
    },
    {
      "id": "resonanceAmount",
      "label": "Resonance depth",
      "range": {
        "min": "-1.2",
        "max": "1.2"
      },
      "default": "0.4",
      "targets": [
        {
          "node": "resonancedepth",
          "param": "gain"
        }
      ]
    }
  ],
  "sampleSlots": [],
  "createdAt": "2026-10-14T00:00:00.000Z"
}