Skip to content

WaveShaper

Tier: Primitives | ComponentType: 4 | Params: 6

Nonlinear waveshaping with 7 transfer functions, per-half asymmetric clipping, and DC blocker.

Overview

WaveShaper applies nonlinear transfer functions to shape the input waveform. It supports 7 curves: tanh soft saturation, hard clipping, sine wave folding, asymmetric tanh, full-wave rectification, half-wave rectification, and crossover distortion. Each half of the waveform (positive and negative) can use a different curve and threshold, enabling asymmetric distortion that models real-world tube and transistor behavior.

A dead zone parameter adds crossover distortion near zero crossing. A DC blocker automatically engages when rectifier curves are selected, since full-wave and half-wave rectification produce DC offset.

File Locations

Path
Header Sources/FolioDSP/include/FolioDSP/Primitives/WaveShaper.h
Implementation Sources/FolioDSP/src/Primitives/WaveShaper.cpp
Tests Tests/FolioDSPTests/WaveShaperTests.swift
Bridge Sources/FolioDSPBridge/src/FolioDSPBridge.mm (WaveShaperBridge)

Parameters

Index Name Description Min Max Default Min Default Max Default Unit
0 Drive Input gain before waveshaping 0.1 100.0 1.0 10.0 1.0 x
1 Shape Clipping curve: 0=Tanh, 1=HardClip, 2=SineFold, 3=Asymmetric, 4=FullRect, 5=HalfRect, 6=Crossover 0.0 6.0 0.0 6.0 0.0
2 Negative Curve Curve for negative half (-1=use positive curve, 0-6=independent) -1.0 6.0 -1.0 6.0 -1.0
3 Positive Threshold Clipping threshold for positive half 0.01 10.0 0.1 2.0 1.0 x
4 Negative Threshold Clipping threshold for negative half (-ve=mirror positive) -10.0 10.0 -2.0 2.0 -1.0 x
5 Dead Zone Crossover distortion zone width near zero 0.0 1.0 0.0 0.5 0.0

Processing Algorithm

1. Per-Half Processing

Positive and negative halves are processed independently:

\[\text{driven} = \frac{x \cdot \text{drive}}{\text{threshold}}\]
\[y = \text{curve}(\text{driven}) \cdot \text{threshold}\]

2. Transfer Functions

  • Tanh: \(y = \tanh(x)\)
  • HardClip: \(y = \text{clamp}(x, -1, 1)\)
  • SineFold: \(y = \sin(x \cdot \pi / 2)\)
  • Asymmetric: \(y = \tanh(x)\) for \(x \geq 0\), \(y = \tanh(0.5x)\) for \(x < 0\)
  • FullWaveRectify: \(y = |x|\)
  • HalfWaveRectify: \(y = \max(0, x)\)
  • Crossover: Soft transition with dead zone

3. DC Blocker (rectifier shapes only)

\[R = 1 - \frac{2\pi \cdot 10}{f_s}\]
\[y_{\text{dc}}[n] = x[n] - x[n-1] + R \cdot y_{\text{dc}}[n-1]\]

Snapshot Fields

Field Type Range Unit Description
Drive Float 0.1–100 x Current drive
Shape Float 0–6 Active curve
Input Float 0–1 Input amplitude
Output Float 0–1 Output amplitude
Pos Curve Uint8 0–6 Positive half curve
Neg Curve Uint8 0–6 Negative half curve
Pos Thresh Float 0.01–10 x Positive threshold
Neg Thresh Float 0.01–10 x Negative threshold
Dead Zone Float 0–1 Dead zone width

Implementation Notes

  • Drive scaling driven = input * drive / threshold makes drive intuitive across threshold values
  • DC blocker only activates for FullWaveRectify and HalfWaveRectify (which produce DC offset)
  • Dead zone crossover distortion uses smooth quadratic ramp: sign(x) · x² / threshold
  • Negative curve = -1 means "use the positive curve for both halves" (symmetric mode)

Equation Summary

y = curve(x·drive/thresh)·thresh