{
  "$type": "at.atmosynth.module",
  "descriptionVersion": 1,
  "moduleId": "clipper",
  "versionKey": "1",
  "name": "Clipper",
  "description": "A ceiling the sound is not let past. Drive is how hard it is pushed into it, in decibels: at nothing only what already reaches the ceiling is cut, and turned up the quieter parts rise under it while the peaks stay where it is, so a drum gets louder without getting taller and a held note turns square. Ceiling is where it is, in decibels of full scale, and so also how loud the module is once it is clipping. Knee is the corner: at nothing the sound runs straight up to the ceiling and flat along it, the hard, bright clip; turned up it bends over before the ceiling and meets it gently, which takes the edge off and makes fewer of the high harmonics a corner makes. Cutting a peak off makes harmonics without end, and every one above half the sample rate would fold back down under the note at a pitch that has nothing to do with it, so the clip is worked out at four times the rate and filtered back down. The filters are flat to 20 kHz and look at nothing ahead: what comes out is about three samples behind what went in, under a tenth of a millisecond, where a waveshaper oversampling four times is four milliseconds behind. Bringing a clipped sound back down smooths its corners, and a smoothed corner overshoots. Ceiling mode chooses what happens to that: exact clamps what comes down to the ceiling, so nothing leaves above it, which is what a clipper in front of the speakers is for, but cutting those peaks at the ordinary rate folds again, and on a sound driven lightly it undoes most of what the oversampling cleaned; clean leaves the overshoot in, up to three decibels over on a sine and more on a drum driven hard, and keeps all of it. Dry/wet keeps the sound that went in, at the level it came in, beside the clipped one, and the two are blended before the way down so they stay together sample for sample; under exact the ceiling holds over the blend as well. Each side is clipped on its own. Drive is an input as well, with a depth in decibels for how far a signal there moves it: an envelope into it pushes the start of a note harder than its tail. This module carries code: the vocabulary's one way to clip at a higher rate is a waveshaper's oversampling, whose filters are the browser's and four milliseconds long, and nothing else in it runs at any rate but the context's.",
  "audioInputs": [
    {
      "id": "in",
      "label": "In"
    },
    {
      "id": "drive",
      "label": "Drive"
    }
  ],
  "audioOutputs": [
    {
      "id": "out",
      "label": "Out"
    }
  ],
  "midiInputs": [],
  "nodes": [
    {
      "id": "in",
      "kind": "moduleInput",
      "options": {
        "input": "in"
      }
    },
    {
      "id": "gen",
      "kind": "dsp",
      "options": {
        "code": "// A clipper: a ceiling the sound is not let past, worked out at four times the\n// rate so that what is cut off does not come back down as tones the note never\n// had, and with nothing held back to look ahead with.\n//\n// The vocabulary clips already: a `waveShaper` with the hard curve is exactly\n// this ceiling. What it cannot do is clip cleanly without being late. Cutting\n// a peak off makes harmonics without end, and every one above half the rate\n// folds back under the note at a pitch that has nothing to do with it — a 9\n// kHz tone driven into a hard clip comes back with folded partials a fifteenth\n// of its own level. The vocabulary's one remedy is the shaper's oversampling,\n// and its resamplers are the browser's: linear-phase filters a hundred and\n// ninety-two frames long at four times, four milliseconds late, which a\n// clipper on a drum or a whole mix is the last place to be. Nothing else in\n// the vocabulary runs at any rate but the context's, so no filters of another\n// shape can be put round a curve there either.\n//\n// So the rate is raised and lowered here, by two half-band filters each way,\n// each one two chains of first-order allpasses side by side (Laurent de\n// Soras's polyphase IIR half-band; the coefficients below are his design,\n// worked out once for these bands and written in as numbers). An allpass pair\n// is flat in the band it passes — nothing under twenty kilohertz is louder or\n// quieter for coming through — and it is late only by its phase: three\n// samples low down, nearer four towards the top, and nothing waits for anything\n// that has not arrived. The first stage, from the context's rate to twice it,\n// is the sharp one: flat to 20.8 kHz at 48 and down 79 dB from 28 kHz, so what\n// would fold below twenty is gone before it can. The second, from twice to\n// four times, only has to keep what the first left clear of its images, and\n// three coefficients reach 89 dB.\n//\n// The curve is hard at Knee nothing and rounds into the ceiling as Knee rises:\n// a straight line to (1 − knee) of the ceiling, then a parabola that meets it\n// flat at (1 + knee), so the slope never jumps and a soft knee makes fewer high\n// partials than a corner to begin with. At one the line is gone and the curve\n// bends from the first sample up.\n//\n// Bringing a clipped sound back down to the rate smooths its corners, and a\n// smoothed corner overshoots: up to three decibels over the ceiling on a sine,\n// more on a drum driven hard. Exact clamps what comes down to the ceiling, so\n// nothing leaves above it — the promise a clipper in front of the speakers is\n// for — and pays for it with corners of its own on every peak it cuts, at\n// the context's rate: on a sound driven lightly they undo most of what the\n// oversampling cleaned, on one driven hard about half. Clean leaves the\n// overshoot in and keeps all of it.\n//\n// Dry/wet is mixed at four times the rate, before the way down, so the two are\n// through the same filters and stay together sample for sample. The dry half is\n// what came in, at the level it came in, not driven. Under Exact the clamp is\n// on the blend, so the ceiling holds whatever the mix.\n//\n// Each side is clipped on its own. A mono source arrives on both.\nimport { AtmoProcessor } from \"atmosynth:dsp\";\n\n/** The first stage's coefficients: from the context's rate to twice it. */\nconst FIRST = 5;\nconst F0 = 0.06269763101794223;\nconst F1 = 0.22599158738859354;\nconst F2 = 0.43760701050340967;\nconst F3 = 0.6575439455002928;\nconst F4 = 0.8796161375236565;\n/** The second stage's: from twice the rate to four times. */\nconst SECOND = 3;\nconst S0 = 0.07022405925320405;\nconst S1 = 0.2850862804444172;\nconst S2 = 0.6845413589235864;\n\n/**\n * Where each filter's memory starts within a side's: the way up through the\n * first stage, then the second, then down through the second and the first.\n */\nconst UP_FIRST = 0;\nconst UP_SECOND = FIRST;\nconst DOWN_SECOND = FIRST + SECOND;\nconst DOWN_FIRST = FIRST + SECOND + SECOND;\nconst SIDE = FIRST + SECOND + SECOND + FIRST;\n\n/** What a dB value is held as before it is first seen, which no reading of it equals. */\nconst UNSEEN = 0 / 0;\n\n/** The most frames a call is handed: a grid step. */\nconst MOST = 128;\n\n// Each stage runs over the whole call at once, its allpasses' memory in locals\n// for the length of it, rather than a sample at a time through every stage:\n// the same arithmetic in the same order, for about a third of the work. Each\n// allpass is `y = a (x − y₋₁) + x₋₁` at the rate its path runs at, and keeps\n// its last input and output at its own index of `ins` and `outs`, from `base`.\n\n/**\n * Up through the first half-band: each sample in becomes two, the even path's\n * (coefficients 0, 2, 4) first and the odd path's (1, 3) second.\n */\nfunction upFirst(ins, outs, base, from, to, count) {\n  let x0 = ins[base];\n  let x1 = ins[base + 1];\n  let x2 = ins[base + 2];\n  let x3 = ins[base + 3];\n  let x4 = ins[base + 4];\n  let y0 = outs[base];\n  let y1 = outs[base + 1];\n  let y2 = outs[base + 2];\n  let y3 = outs[base + 3];\n  let y4 = outs[base + 4];\n  for (let i = 0; i < count; i += 1) {\n    const x = from[i];\n    const e0 = F0 * (x - y0) + x0;\n    x0 = x;\n    y0 = e0;\n    const e1 = F2 * (e0 - y2) + x2;\n    x2 = e0;\n    y2 = e1;\n    const e2 = F4 * (e1 - y4) + x4;\n    x4 = e1;\n    y4 = e2;\n    const o0 = F1 * (x - y1) + x1;\n    x1 = x;\n    y1 = o0;\n    const o1 = F3 * (o0 - y3) + x3;\n    x3 = o0;\n    y3 = o1;\n    to[2 * i] = e2;\n    to[2 * i + 1] = o1;\n  }\n  ins[base] = x0;\n  ins[base + 1] = x1;\n  ins[base + 2] = x2;\n  ins[base + 3] = x3;\n  ins[base + 4] = x4;\n  outs[base] = y0;\n  outs[base + 1] = y1;\n  outs[base + 2] = y2;\n  outs[base + 3] = y3;\n  outs[base + 4] = y4;\n}\n\n/** Up through the second half-band: even path (0, 2) first, odd (1) second. */\nfunction upSecond(ins, outs, base, from, to, count) {\n  let x0 = ins[base];\n  let x1 = ins[base + 1];\n  let x2 = ins[base + 2];\n  let y0 = outs[base];\n  let y1 = outs[base + 1];\n  let y2 = outs[base + 2];\n  for (let i = 0; i < count; i += 1) {\n    const x = from[i];\n    const e0 = S0 * (x - y0) + x0;\n    x0 = x;\n    y0 = e0;\n    const e1 = S2 * (e0 - y2) + x2;\n    x2 = e0;\n    y2 = e1;\n    const o0 = S1 * (x - y1) + x1;\n    x1 = x;\n    y1 = o0;\n    to[2 * i] = e1;\n    to[2 * i + 1] = o0;\n  }\n  ins[base] = x0;\n  ins[base + 1] = x1;\n  ins[base + 2] = x2;\n  outs[base] = y0;\n  outs[base + 1] = y1;\n  outs[base + 2] = y2;\n}\n\n/**\n * Down through the second half-band: each pair's later sample through the even\n * path, its earlier through the odd, and the two averaged.\n */\nfunction downSecond(ins, outs, base, from, to, count) {\n  let x0 = ins[base];\n  let x1 = ins[base + 1];\n  let x2 = ins[base + 2];\n  let y0 = outs[base];\n  let y1 = outs[base + 1];\n  let y2 = outs[base + 2];\n  for (let i = 0; i < count; i += 1) {\n    const later = from[2 * i + 1];\n    const earlier = from[2 * i];\n    const e0 = S0 * (later - y0) + x0;\n    x0 = later;\n    y0 = e0;\n    const e1 = S2 * (e0 - y2) + x2;\n    x2 = e0;\n    y2 = e1;\n    const o0 = S1 * (earlier - y1) + x1;\n    x1 = earlier;\n    y1 = o0;\n    to[i] = 0.5 * (e1 + o0);\n  }\n  ins[base] = x0;\n  ins[base + 1] = x1;\n  ins[base + 2] = x2;\n  outs[base] = y0;\n  outs[base + 1] = y1;\n  outs[base + 2] = y2;\n}\n\n/** Down through the first half-band, the same way. */\nfunction downFirst(ins, outs, base, from, to, count) {\n  let x0 = ins[base];\n  let x1 = ins[base + 1];\n  let x2 = ins[base + 2];\n  let x3 = ins[base + 3];\n  let x4 = ins[base + 4];\n  let y0 = outs[base];\n  let y1 = outs[base + 1];\n  let y2 = outs[base + 2];\n  let y3 = outs[base + 3];\n  let y4 = outs[base + 4];\n  for (let i = 0; i < count; i += 1) {\n    const later = from[2 * i + 1];\n    const earlier = from[2 * i];\n    const e0 = F0 * (later - y0) + x0;\n    x0 = later;\n    y0 = e0;\n    const e1 = F2 * (e0 - y2) + x2;\n    x2 = e0;\n    y2 = e1;\n    const e2 = F4 * (e1 - y4) + x4;\n    x4 = e1;\n    y4 = e2;\n    const o0 = F1 * (earlier - y1) + x1;\n    x1 = earlier;\n    y1 = o0;\n    const o1 = F3 * (o0 - y3) + x3;\n    x3 = o0;\n    y3 = o1;\n    to[i] = 0.5 * (e2 + o1);\n  }\n  ins[base] = x0;\n  ins[base + 1] = x1;\n  ins[base + 2] = x2;\n  ins[base + 3] = x3;\n  ins[base + 4] = x4;\n  outs[base] = y0;\n  outs[base + 1] = y1;\n  outs[base + 2] = y2;\n  outs[base + 3] = y3;\n  outs[base + 4] = y4;\n}\n\n/**\n * The curve over the four samples each frame became, with the ceiling at one:\n * a line up to `low`, a parabola from there that meets the ceiling flat at\n * `high`, and the ceiling beyond — at no knee `low` and `high` are both one\n * and the parabola is never reached — blended with the sample as it was by\n * the frame's own wet and dry.\n */\nfunction shape(samples, wets, drys, low, high, bend, count) {\n  for (let i = 0; i < count; i += 1) {\n    const x = samples[i];\n    const size = Math.abs(x);\n    let curved = x;\n    if (size >= high) curved = x < 0 ? -1 : 1;\n    else if (size > low) {\n      const over = size - low;\n      curved = (x < 0 ? -1 : 1) * (size - over * over * bend);\n    }\n    const frame = i >> 2;\n    samples[i] = wets[frame] * curved + drys[frame] * x;\n  }\n}\n\nexport default class AtmosynthClipper extends AtmoProcessor {\n  static spec = 1;\n  static inputs = [2];\n  static outputs = [2];\n  // Not smoothed here: a knob's move reaches these already eased, and what is\n  // wired into them is followed exactly.\n  static params = {\n    // The gain into the ceiling, in decibels. Its own range is wider than the\n    // knob's so that a signal at the Drive input can move it past either end.\n    drive: { min: -48, max: 72, default: 6, rate: \"a\", smooth: 0 },\n    // Where the ceiling is, in decibels of full scale.\n    ceiling: { min: -48, max: 0, default: 0, rate: \"a\", smooth: 0 },\n    knee: { min: 0, max: 1, default: 0, rate: \"k\", smooth: 0 },\n    mix: { min: 0, max: 1, default: 1, rate: \"a\", smooth: 0 },\n    // Exact or Clean, by the choice's position. Rounded, since a choice\n    // turned by a controller glides between positions on its way to one.\n    mode: { min: 0, max: 1, default: 0, rate: \"k\", smooth: 0 },\n  };\n\n  constructor() {\n    super();\n    // Every allpass's last input and last output, one side after the other.\n    this.ins = new Float64Array(2 * SIDE);\n    this.outs = new Float64Array(2 * SIDE);\n    // Per frame of the call: the gain into the curve, the ceiling it is\n    // brought back up to, and the blend.\n    this.intos = new Float64Array(MOST);\n    this.ceilings = new Float64Array(MOST);\n    this.wets = new Float64Array(MOST);\n    this.drys = new Float64Array(MOST);\n    // A side at the rate, at twice it and at four times.\n    this.single = new Float64Array(MOST);\n    this.double = new Float64Array(2 * MOST);\n    this.quad = new Float64Array(4 * MOST);\n    // The decibels last turned into gains, and the gains they were turned into.\n    this.driveDb = UNSEEN;\n    this.ceilingDb = UNSEEN;\n    this.driveGain = 1;\n    this.ceilingGain = 1;\n    this.into = 1;\n    this.dry = 1;\n  }\n\n  process(inputs, outputs, parameters) {\n    const input = inputs[0];\n    const output = outputs[0];\n    const frames = output[0].length;\n    const drives = parameters.drive;\n    const ceilingDbs = parameters.ceiling;\n    const mixes = parameters.mix;\n    const knee = parameters.knee[0];\n    const exact = Math.round(parameters.mode[0]) === 0;\n    const low = 1 - knee;\n    const high = 1 + knee;\n    const bend = knee > 0 ? 1 / (4 * knee) : 0;\n    const intos = this.intos;\n    const ceilings = this.ceilings;\n    const wets = this.wets;\n    const drys = this.drys;\n    const single = this.single;\n    const double = this.double;\n    const quad = this.quad;\n\n    for (let index = 0; index < frames; index += 1) {\n      // Decibels into gains only when they move, since a power on every\n      // sample of a still knob is the most of what this would cost.\n      const driveDb = drives[index];\n      const ceilingDb = ceilingDbs[index];\n      if (driveDb !== this.driveDb || ceilingDb !== this.ceilingDb) {\n        if (driveDb !== this.driveDb) {\n          this.driveDb = driveDb;\n          this.driveGain = Math.pow(10, driveDb / 20);\n        }\n        if (ceilingDb !== this.ceilingDb) {\n          this.ceilingDb = ceilingDb;\n          this.ceilingGain = Math.pow(10, ceilingDb / 20);\n        }\n        // Into the curve with the ceiling at one, and the dry half back out\n        // of the drive, so that it leaves at the level it came in at.\n        this.into = this.driveGain / this.ceilingGain;\n        this.dry = 1 / this.driveGain;\n      }\n      intos[index] = this.into;\n      ceilings[index] = this.ceilingGain;\n      const wet = mixes[index];\n      wets[index] = wet;\n      drys[index] = (1 - wet) * this.dry;\n    }\n\n    for (let side = 0; side < 2; side += 1) {\n      const base = side * SIDE;\n      const arriving = input[side];\n      for (let index = 0; index < frames; index += 1) single[index] = arriving[index] * intos[index];\n      upFirst(this.ins, this.outs, base + UP_FIRST, single, double, frames);\n      upSecond(this.ins, this.outs, base + UP_SECOND, double, quad, 2 * frames);\n      shape(quad, wets, drys, low, high, bend, 4 * frames);\n      downSecond(this.ins, this.outs, base + DOWN_SECOND, quad, double, 2 * frames);\n      downFirst(this.ins, this.outs, base + DOWN_FIRST, double, single, frames);\n      const leaving = output[side];\n      for (let index = 0; index < frames; index += 1) {\n        const down = single[index];\n        const level = exact ? Math.min(Math.max(down, -1), 1) : down;\n        leaving[index] = level * ceilings[index];\n      }\n    }\n    return true;\n  }\n}\n"
      }
    },
    {
      "id": "out",
      "kind": "moduleOutput",
      "options": {
        "output": "out"
      }
    },
    {
      "id": "drivein",
      "kind": "moduleInput",
      "options": {
        "input": "drive"
      }
    },
    {
      "id": "drivedepth",
      "kind": "gain",
      "options": {}
    }
  ],
  "connections": [
    {
      "from": {
        "node": "in",
        "output": 0
      },
      "to": {
        "node": "gen",
        "input": 0
      }
    },
    {
      "from": {
        "node": "gen",
        "output": 0
      },
      "to": {
        "node": "out",
        "input": 0
      }
    },
    {
      "from": {
        "node": "drivein",
        "output": 0
      },
      "to": {
        "node": "drivedepth",
        "input": 0
      }
    },
    {
      "from": {
        "node": "drivedepth",
        "output": 0
      },
      "to": {
        "node": "gen",
        "param": "drive"
      }
    }
  ],
  "automation": [],
  "parameters": [
    {
      "id": "drive",
      "label": "Drive (dB)",
      "range": {
        "min": "0",
        "max": "24"
      },
      "default": "6",
      "targets": [
        {
          "node": "gen",
          "param": "drive"
        }
      ]
    },
    {
      "id": "ceiling",
      "label": "Ceiling (dB)",
      "range": {
        "min": "-24",
        "max": "0"
      },
      "default": "0",
      "targets": [
        {
          "node": "gen",
          "param": "ceiling"
        }
      ]
    },
    {
      "id": "knee",
      "label": "Knee",
      "range": {
        "min": "0",
        "max": "1"
      },
      "default": "0",
      "targets": [
        {
          "node": "gen",
          "param": "knee"
        }
      ]
    },
    {
      "id": "mode",
      "label": "Ceiling mode",
      "values": [
        "exact",
        "clean"
      ],
      "default": "exact",
      "targets": [
        {
          "node": "gen",
          "param": "mode"
        }
      ]
    },
    {
      "id": "mix",
      "label": "Dry/wet",
      "range": {
        "min": "0",
        "max": "1"
      },
      "default": "1",
      "targets": [
        {
          "node": "gen",
          "param": "mix"
        }
      ]
    },
    {
      "id": "driveAmount",
      "label": "Drive depth (dB)",
      "range": {
        "min": "-24",
        "max": "24"
      },
      "default": "6",
      "targets": [
        {
          "node": "drivedepth",
          "param": "gain"
        }
      ]
    }
  ],
  "sampleSlots": [],
  "createdAt": "2026-11-11T00:00:00.000Z"
}