Adaptive Wave Shaper — User Guide

File-level adaptive distortion driven by Praat jitter and shimmer analysis. Jitter calibrates drive, shimmer calibrates fold count, and the resulting static transfer function is applied to every channel of the selected Sound.

Author: Shai Cohen Affiliation: Department of Music, Bar-Ilan University, Israel Version: 0.8.1 (2026) License: MIT License Category: Distortion

Contents:

What this does Quick start Jitter & shimmer analysis Shaping pipeline Presets Parameters Output level Visualization Limitations

What this does

Adaptive Wave Shaper analyzes one selected Sound with Praat's pitch/pulse tools, obtains one file-level local-jitter value and one file-level local-shimmer value, and maps them to distortion parameters. The processing is therefore content-calibrated but not time-varying: the derived drive and fold count remain fixed from the beginning to the end of the file.

Channel behavior: analysis is performed on a mono analysis copy, but the shaping itself is applied directly to a copy of the original Sound. The output therefore preserves the input channel count and channel structure.

The signal path is:

Sound → mono analysis copy → Pitch + PointProcess → jitter/shimmer → calibrated drive/folds → drive → iterative wave folding → optional saturation → output-level stage

The original Sound is preserved. The processed object is named originalname_shaped_PresetName.

Quick start

Select exactly one Sound in Praat.
Run Adaptive_Wave_Shaper.praat.
Choose a preset. Use Custom only when you want to enter Base drive, Jitter sensitivity, and Shimmer sensitivity yourself.
Choose the saturation type and fold threshold.
Set the pitch range used by the analysis. The default is 75–600 Hz.
Choose what should happen when usable pulse-based calibration is unavailable.
Choose the output-level policy, visualization, and playback options, then click OK.

Important: the preset controls only the three calibration parameters: base drive, jitter sensitivity, and shimmer sensitivity. Saturation type, fold threshold, pitch range, fallback mode, output level, visualization, and playback remain active user choices for every preset.

Jitter & shimmer analysis

The script converts the selected Sound to mono for analysis only, creates a Pitch object with the chosen pitch range, and combines the mono Sound with that Pitch to create a PointProcess (cc). At least four pulses are required before jitter and shimmer are queried.

What are jitter and shimmer?

Jitter measures small cycle-to-cycle irregularities in the timing of a periodic signal. In voice analysis, it describes how much the duration of successive pitch periods varies. A very steady periodic tone has low jitter; less regular pulse timing produces a higher value.

Shimmer measures small cycle-to-cycle irregularities in amplitude. It describes how much the amplitude of successive periods varies. A signal whose periodic cycles maintain nearly the same level has low shimmer; stronger period-to-period level variation produces a higher value.

In this effect: jitter and shimmer are not treated as diagnoses or generic measures of “roughness.” They are periodicity-based control measurements. Jitter increases the calculated drive; shimmer increases the calculated fold count. Because the script measures them once over the analyzed file, they calibrate one static shaping configuration for the whole Sound rather than modulating the distortion moment by moment.

The period limits used by both perturbation measures are derived from the same pitch range:

shortestPeriod = 1 / Max_pitch_Hz / 1.5
longestPeriod = 1 / Min_pitch_Hz × 1.5

The script then requests Praat's local jitter and local shimmer. Here “local” is the name of the perturbation measure; the script still obtains one value for the whole file rather than a moving control curve.

jitter_percent = jitter_local × 100
shimmer_percent = shimmer_local × 100

adaptive_drive = base_drive × (1 + jitter_percent × jitter_sensitivity / 100)
adaptive_fold = 1 + round(shimmer_percent × shimmer_sensitivity / 20)

The calculated drive is constrained to 0.5–8.0. The fold count is constrained to 0–8. These are parameter bounds, not guarantees that the waveform peak stays below 1.0.

Partial and failed calibration

Condition	Behavior
Jitter and shimmer both available	Both mappings are used normally.
Jitter undefined, shimmer available	Drive remains at the preset/base value; shimmer still determines fold count.
Shimmer undefined, jitter available	Fold count remains 1; jitter still calibrates drive.
Fewer than 4 usable pulses, or neither measure defined	Calibration is skipped and the selected Unpitched fallback is used.

Unpitched fallback

Base shaping

Uses the preset/base drive, one fold, and the selected saturation type.

Drive only

Uses the preset/base drive but forces fold count to 0 and disables saturation.

Shaping pipeline

1. Drive

x₁ = x × adaptive_drive

2. Iterative wave folding

For each fold pass, a sample can be reflected at most once. An overshoot that crosses the opposite threshold is carried into the next fold pass rather than reflected twice in the same pass.

if x > T: x = T - (x - T)
else if x < -T: x = -T - (x + T)
else: x unchanged

Repeat for adaptive_fold passes.

T is Fold_threshold (default 0.6). Multiple passes do not guarantee that the result is confined to ±T; large drive with a small threshold can still leave a large post-fold peak.

3. Saturation

Mode	Transfer	Character
Sin blend (rippled)	`0.3·sin(2x) + 0.7x`	A smooth, monotonically increasing transfer with sinusoidal ripple.
Tanh (cleaner)	`tanh(1.5x)`	Conventional smooth saturation with bounded output.
None	No additional transfer	Drive + folding only.

When the Drive only fallback is active because calibration failed, saturation is disabled regardless of the menu selection.

Presets

Presets set only Base drive, Jitter sensitivity, and Shimmer sensitivity.

Preset	Base drive	Jitter sens.	Shimmer sens.
Default	2.0	1.5	1.2
Gentle Saturation	1.2	1.0	0.8
Aggressive Drive	4.0	2.0	1.8
Fold Emphasis	2.5	1.2	2.5
Maximum Destruction	5.0	3.0	3.0
Custom	Uses the three Base Parameters entered in the form.

Parameters

Parameter	Default	Actual role
Preset	Default	Selects base drive and the two sensitivities.
Base_drive	2.0	Custom preset only. Starting gain before jitter calibration.
Jitter_sensitivity	1.5	Custom preset only. Scales the jitter contribution to drive.
Shimmer_sensitivity	1.2	Custom preset only. Scales the shimmer contribution to fold count.
Saturation_type	Sin blend	Sin blend, Tanh, or None. Active for every preset.
Fold_threshold	0.6	Positive reflection threshold ±T used by every fold pass.
Min_pitch_Hz	75	Lower pitch-analysis bound; must be below Max_pitch_Hz.
Max_pitch_Hz	600	Upper pitch-analysis bound and part of the derived perturbation-period range.
Unpitched_fallback	Base shaping	Controls processing when usable pulse-based calibration cannot be obtained.
Output_level	Normalize to 0.9	Final global level policy; see below.
Draw_visualization	Yes	Draws the transfer function, analysis report, output waveform, and summary.
Play_result	Yes	Plays the processed Sound when finished.

Output level

The script measures the peak after drive, folding, and saturation and before the final output-level stage.

Mode	Behavior
Normalize to 0.9	Always applies `Scale peak: 0.9`. This can attenuate or amplify the entire file.
Attenuate to 0.9 only if peak > 1	If the pre-output peak exceeds 1.0, the entire file is uniformly scaled to peak 0.9. Otherwise its level is unchanged. This is not a dynamic limiter.
Preserve	No final scaling. If the peak exceeds 1.0 the script reports a clipping warning.

Peak safety: the drive and fold-count caps do not guarantee a bounded waveform. Use one of the first two output-level modes when you need controlled peak amplitude.

Visualization

The v0.8.1 Picture view uses the suite-standard canvas and contains four functional regions:

Static shaping function

Plots the actual drive → fold → saturation transfer function using the calibrated parameters. The Y range expands to fit the true function; the graph is explicitly before the output-level stage. Dotted horizontal lines mark ±Fold_threshold and a diagonal reference shows y=x.

Analysis report

Shows analyzed jitter and shimmer, any fallback/undefined-metric state, calibrated drive/folds, and the two sensitivities.

Output waveform

Mono output is shown directly. For multichannel output, Ch 1 is blue and Ch 2 orange. If more than two channels exist, the title states that only the first two are displayed; all channels remain in the Sound.

Summary bar

Reports preset, source, jitter, shimmer, drive, folds, saturation, threshold, sensitivities, output-level action, duration, full channel count, and final peak.

Limitations & interpretation

Not time-varying: jitter and shimmer are measured once for the file and produce one fixed transfer function.
Voice-quality metrics are used as compositional controls: reliable calibration depends on usable periodic pulses. Noise, percussion, strongly polyphonic material, or an unsuitable pitch range may invoke the fallback.
Analysis is mono: a multichannel source is downmixed only for jitter/shimmer analysis. Processing itself remains multichannel.
Folding is iterative reflection, not clipping: one reflection is allowed per pass, and extreme settings can remain well outside ±Fold_threshold.
No oversampling: strong nonlinear shaping can generate high-frequency components that may alias.
No wet/dry control: the created Sound is fully processed. Parallel blending must be done elsewhere if desired.