Adaptive Wave Shaper — User Guide

Jitter and shimmer-controlled wave shaping: adaptive distortion and wave folding based on voice quality metrics for dynamic saturation, harmonic enhancement, and creative audio mangling.

Author: Shai Cohen Affiliation: Department of Music, Bar-Ilan University, Israel Version: 0.1 (2025) License: MIT License Repo: https://github.com/ShaiCohen-ops/Praat-plugin_AudioTools

Contents:

What this does Quick start Wave Shaping Theory Parameters & Presets Applications

What this does

This script implements adaptive wave shaping — a dynamic distortion effect that adjusts its parameters based on jitter (pitch perturbation) and shimmer (amplitude perturbation) analysis. Unlike static distortion with fixed drive/fold settings, this creates content-aware processing: higher jitter increases drive amount, higher shimmer increases wave folding iterations. The result: organic, voice-responsive distortion that adapts to signal characteristics. Applications: expressive guitar processing, vocal enhancement, synthesizer mangling, experimental sound design, adaptive harmonic generation.

Key Features:

Jitter-Controlled Drive — Pitch irregularity scales distortion amount
Shimmer-Controlled Folding — Amplitude variation determines fold iterations
4 Presets — Default, Gentle Saturation, Aggressive Drive, Fold Emphasis
Wave Folding — 1-8 iterations of amplitude reflection
Sinusoidal Shaping — Final sine-based character for harmonic richness
Auto-Normalization — Optional peak scaling to 0.9

What is wave shaping? Wave shaping = nonlinear transformation of audio waveform. Input amplitude determines output amplitude via transfer function (mapping curve). Types: (1) Soft clipping: gradual saturation (tube amps, tape). (2) Hard clipping: abrupt cutoff (transistor distortion, fuzz). (3) Wave folding: signal reflects at threshold (Buchla/Serge modulars, additive harmonics). (4) Polynomial: mathematical curves (Chebyshev, harmonic generation). This script combines: multiplicative drive (gain boost) + iterative folding (reflection at ±0.6) + sinusoidal shaping (30% sine + 70% original). Result: rich harmonic distortion with adaptive intensity.

Technical Implementation: (1) Analyze jitter and shimmer (demonstration uses fixed values: jitter=1.2%, shimmer=4.5% — real implementation would extract from audio), (2) Calculate adaptive drive: drive = base_drive × (1 + jitter × sensitivity / 100), constrained 0.5-5.0, (3) Calculate adaptive folds: folds = 1 + round(shimmer × sensitivity / 20), constrained 1-8, (4) Apply drive: multiply signal by adaptive_drive, (5) Apply wave folding (iterative): for each fold iteration, reflect values >0.6 to 0.6-(value-0.6), reflect values <-0.6 to -0.6-(value+0.6), (6) Apply sinusoidal shaping: output = sin(signal × 2) × 0.3 + signal × 0.7, (7) Optional normalize to peak 0.9. Key insight: Jitter/shimmer metrics (normally used for voice quality assessment) repurposed as creative control parameters. High perturbation = more aggressive processing. Adaptive to source material characteristics.

Quick start

In Praat, select exactly one Sound object.
Run script… → Adaptive_Wave_Shaper.praat.
Choose Preset: Default (drive 2.0), Gentle Saturation, Aggressive Drive/Folds, Fold Emphasis, or Custom.
If Custom: adjust Base_drive (distortion amount), Jitter_sensitivity (pitch response), Shimmer_sensitivity (amplitude response), Normalize (yes/no).
Click OK — processing applies adaptive wave shaping, displays results in Info window, auto-plays.

Quick tip: Start with Default for balanced distortion. Try Gentle Saturation on vocals/acoustic instruments for subtle warmth. Use Aggressive Drive/Folds for heavy distortion effects. Fold Emphasis creates metallic, folded textures with moderate drive. Processing instant (<1 second typical). Check Info window for calculated parameters: "Jitter: X%, Shimmer: Y%, Final drive: Z, Final folds: N". Output named "originalname_adaptive". Normalization prevents clipping but may reduce dynamics — disable for manual gain staging.

Important: Current implementation uses demonstration values (jitter=1.2%, shimmer=4.5%) — not actual audio analysis. Real jitter/shimmer extraction requires pitch tracking and periodicity detection (computationally intensive). For production use, implement actual analysis or treat sensitivity parameters as creative controls rather than voice-quality metrics. Very high drive (>4.0) creates extreme distortion/clipping. Very high folds (>6) can produce harsh, aliased artifacts. Wave folding works best on smooth, pitched material — noise/percussion creates chaotic results. Normalization to 0.9 standard but adjust if clipping occurs.

Wave Shaping Theory

Fundamental Concepts

Nonlinear Transformation

Linear processing: Output proportional to input (gain, EQ, delay)

Nonlinear processing: Output related to input via curve/function (distortion, compression)

Linear: y = a × x (straight line) Nonlinear: y = f(x) (curved transfer function) Example transfer functions: Soft clip: y = tanh(x) Hard clip: y = max(-1, min(1, x)) Sine: y = sin(x) Polynomial: y = xÂ³ - 0.5x

Harmonic generation:

Linear processing preserves frequency content
Nonlinear processing generates harmonics (multiples of input frequencies)
Sine wave input → multiple sine waves output (fundamental + overtones)
More extreme nonlinearity = more harmonics = richer/harsher timbre

Drive (Gain-Based Distortion)

Concept

Drive = pre-distortion gain boost

signal_driven = input × drive_amount Example: input = 0.3, drive = 2.0 → signal_driven = 0.3 × 2.0 = 0.6 Higher drive → larger amplitudes → more clipping/folding

Effect on Spectrum

Low drive (1.0-1.5):

Subtle saturation
Low-order harmonics (2nd, 3rd)
Warm, tube-like character

Medium drive (1.5-3.0):

Moderate distortion
Mid-order harmonics (2nd-6th)
Crunchy, overdriven character

High drive (3.0-5.0):

Heavy distortion
High-order harmonics (all overtones)
Harsh, fuzzy, aggressive character

Wave Folding

Concept

When signal exceeds threshold, reflect it back

Threshold: ±0.6 If signal > 0.6: new_signal = 0.6 - (signal - 0.6) (reflects downward from +0.6) If signal < -0.6: new_signal = -0.6 - (signal + 0.6) (reflects upward from -0.6) Example: signal = 0.9 → 0.9 > 0.6, difference = 0.3 → new_signal = 0.6 - 0.3 = 0.3 (folded back down)

Multiple Folds (Iterations)

Each fold iteration re-applies threshold check

Input: 0.8 Fold 1: 0.8 > 0.6 → fold down Result: 0.6 - (0.8 - 0.6) = 0.4 Fold 2: 0.4 < 0.6 → no fold (within threshold) Result: 0.4 (unchanged) Input: 1.5 (after high drive) Fold 1: 1.5 → 0.6 - (1.5 - 0.6) = -0.3 Fold 2: -0.3 (within threshold) Fold 3: -0.3 (within threshold) More folds = more complex reflection patterns

Harmonic Effect

Wave folding adds upper harmonics:

Each fold adds sharp discontinuities
Discontinuities = high-frequency content
Result: bright, metallic, bell-like timbre
Classic Buchla/Serge modular sound
Different from clipping (more musical, less harsh)

Sinusoidal Shaping

Formula

output = sin(signal × 2) × 0.3 + signal × 0.7

Components: sin(signal × 2) × 0.3 — 30% sine transformation signal × 0.7 — 70% original signal Blend: 30% nonlinear + 70% linear Why sine? - Smooth, continuous nonlinearity - Adds odd harmonics (3rd, 5th, 7th...) - Musical, less harsh than polynomial Why multiply by 2 before sine? - Increases input range to sine - More of signal experiences nonlinear region - Stronger harmonic generation

Perceptual Effect

Character:

Smooth saturation
Warmth without harshness
Retains original dynamics (70% preservation)
Adds richness without overwhelming

Jitter and Shimmer as Control

Jitter (Pitch Perturbation)

Definition: Cycle-to-cycle variation in fundamental frequency

Typical values:

Stable tone: <1% (0.01)
Normal voice: 0.5-1.5%
Expressive/vibrato: 2-5%
Irregular/rough: >5%

Control mapping:

adaptive_drive = base_drive × (1 + jitter × sensitivity / 100) Example: base=2.0, jitter=1.2%, sensitivity=1.5 adaptive_drive = 2.0 × (1 + 1.2 × 1.5 / 100) = 2.0 × (1 + 0.018) = 2.0 × 1.018 = 2.036 Higher jitter → higher drive → more distortion Interpretation: irregular pitch = more aggressive processing

Shimmer (Amplitude Perturbation)

Definition: Cycle-to-cycle variation in peak amplitude

Typical values:

Stable tone: <3% (0.03)
Normal voice: 2-5%
Breathy/irregular: 5-10%
Unstable: >10%

Control mapping:

adaptive_fold = 1 + round(shimmer × sensitivity / 20) Example: shimmer=4.5%, sensitivity=1.2 adaptive_fold = 1 + round(4.5 × 1.2 / 20) = 1 + round(5.4 / 20) = 1 + round(0.27) = 1 + 0 = 1 Example: shimmer=8.0%, sensitivity=2.5 adaptive_fold = 1 + round(8.0 × 2.5 / 20) = 1 + round(20 / 20) = 1 + 1 = 2 Higher shimmer → more folds → more reflection Interpretation: amplitude variation = more folding complexity

Complete Processing Pipeline

STEP 1: Analyze source (demonstration) jitter = 1.2% shimmer = 4.5% STEP 2: Calculate adaptive parameters adaptive_drive = base_drive × (1 + jitter × j_sens / 100) adaptive_fold = 1 + round(shimmer × s_sens / 20) Constrain: drive [0.5, 5.0], fold [1, 8] STEP 3: Apply drive signal = input × adaptive_drive STEP 4: Apply wave folding (iterative) for fold = 1 to adaptive_fold: if signal > 0.6: signal = 0.6 - (signal - 0.6) if signal < -0.6: signal = -0.6 - (signal + 0.6) STEP 5: Apply sinusoidal shaping output = sin(signal × 2) × 0.3 + signal × 0.7 STEP 6: Normalize (optional) scale to peak = 0.9 Result: Adaptive distortion responsive to source characteristics

Parameters & Presets

Preset Options

🎵 Default (drive 2.0)

Parameters: Base drive 2.0, Jitter sens 1.5, Shimmer sens 1.2

Character: Balanced distortion, moderate saturation

Best for: General use, guitars, synths, vocals

💫 Gentle Saturation

Parameters: Base drive 1.2, Jitter sens 1.0, Shimmer sens 0.8

Character: Subtle warmth, tape-like saturation

Best for: Acoustic instruments, vocals, subtle enhancement

🔥 Aggressive Drive/Folds

Parameters: Base drive 4.0, Jitter sens 2.0, Shimmer sens 1.8

Character: Heavy distortion, intense folding, aggressive

Best for: Experimental sound design, harsh textures, heavy processing

🌀 Fold Emphasis

Parameters: Base drive 2.5, Jitter sens 1.2, Shimmer sens 2.5

Character: Metallic folding, moderate drive, complex reflections

Best for: Bell tones, metallic percussion, Buchla-style sounds

Custom Parameters

Parameter	Type	Default	Description
Preset	option	Default	Choose preset or Custom
Base_drive	positive	2.0	Initial drive/gain amount (0.5-5.0 typical)
Jitter_sensitivity	positive	1.5	Pitch perturbation response scaling
Shimmer_sensitivity	positive	1.2	Amplitude perturbation response scaling
Normalize	boolean	yes	Scale output peak to 0.9

Parameter Details

Base_drive

Range: 0.5-5.0 (practical), unlimited (script constrains calculated value)

Default: 2.0

Effect:

0.5-1.0: Clean to minimal saturation
1.0-2.0: Subtle to moderate distortion (sweet spot)
2.0-3.5: Heavy distortion, crunchy
3.5-5.0: Extreme distortion, fuzzy

Interaction: Multiplied by jitter factor — actual drive varies per signal

Jitter_sensitivity

Range: 0.0-5.0 (typical 0.5-2.5)

Default: 1.5

Effect:

0.0: No jitter influence (static drive)
0.5-1.0: Subtle adaptation
1.0-2.0: Moderate adaptation (recommended)
>2.0: Strong adaptation (can over-respond)

Formula impact: Higher sensitivity → drive increases more with jitter

Shimmer_sensitivity

Range: 0.0-5.0 (typical 0.5-3.0)

Default: 1.2

Effect:

0.0: No shimmer influence (1 fold always)
0.5-1.5: Subtle folding changes (1-2 folds typical)
1.5-2.5: Moderate folding (2-4 folds)
>2.5: Heavy folding (4-8 folds possible)

Formula impact: Higher sensitivity → more fold iterations with shimmer

Normalize

Options: Yes (1) or No (0)

Default: Yes

Effect:

Yes: Peak scales to 0.9 (prevents clipping, may reduce dynamics)
No: Raw output (may clip, preserves relative levels)

Recommendation: Enable for safety, disable for manual gain staging

Calculated Output Values

Info window displays:

Adaptive Wave Shaper Results: Jitter: 1.20% Shimmer: 4.50% Final drive: 2.04 Final folds: 1 Interpretation: - Low jitter → minimal drive increase (2.04 vs 2.0 base) - Moderate shimmer → single fold (4.5% not enough for 2 folds) - Processing: moderate distortion, minimal folding

Applications

Voice Processing

Use case: Adaptive vocal saturation

Preset: Gentle Saturation or Default

Effect:

Irregular/expressive moments get more distortion
Stable passages stay cleaner
Natural-sounding dynamic processing
Adds character without over-processing

Guitar/Bass

Use case: Dynamic overdrive

Preset: Default or Aggressive Drive

Effect:

Pick attack variations influence distortion
Vibrato sections get more harmonics
Responsive, player-sensitive tone
Alternative to static pedal distortion

Synthesis

Use case: Harmonic enhancement

Preset: Fold Emphasis or Custom

Effect:

Adds upper harmonics to simple waveforms
Metallic, bell-like character
Buchla/Serge-style wave folding
Transforms sine → complex timbre

Sound Design

Use case: Experimental mangling

Preset: Aggressive Drive/Folds or Custom high settings

Effect:

Extreme transformation of source material
Unpredictable, organic results
Harsh textures, industrial sounds
Granular/glitchy artifacts with high folds

Mixing Applications

Parallel processing: Mix 30-50% processed with original for controlled distortion. Serial chain: Adaptive shaper → EQ → compression for sculpted tone. Frequency-specific: Apply only to midrange (300-3000 Hz) for focused distortion. Automation: Adjust sensitivity parameters over time for evolving character. Mastering: Gentle Saturation preset adds warmth and glue to full mixes.

Comparison to Traditional Distortion

Feature	Traditional	Adaptive Shaper
Parameter control