Waveset Distortion — v1.6 User Guide

Time-domain waveset processing built from zero-crossing segments, with repeat, skip, reverse, duration scaling, shuffling, amplitude alternation, loudness-based deletion, and a pitch-synchronous telescope mode.

Author: Shai Cohen Affiliation: Department of Music, Bar-Ilan University, Israel Version: 1.6 (2026) License: MIT License Repo: GitHub

Contents:

What it does Quick start Presets Operation types Pitch-Sync Telescope Parameters Length & level Visualization FAQ / troubleshooting

What this does

Waveset Distortion divides a Sound into short time-domain segments and processes those segments as compositional units. For modes 1–9, the boundaries are consecutive zero crossings detected on a mono working signal. The processed wavesets are then concatenated to form a new mono Sound. The material before the first boundary and after the last boundary is preserved by default.

Multichannel input: Waveset boundaries are channel-specific, so the processor does not attempt to preserve a multichannel spatial image. For a multichannel source you can Fold to mono (default), Use channel 1 only, or Stop. If folding nearly cancels the signal, the script automatically falls back to channel 1 and reports this. The output is always mono.

Available operations: Repeat, Skip, Reverse, Stretch, Compress, Randomize, Amplitude, Keep Strongest, Delete Weakest, and Pitch-Sync Telescope. The first nine operate on zero-crossing wavesets. Telescope instead tries pitch-synchronous periods first and uses zero-crossing wavesets only as a fallback.

What is a waveset?

In this processor, a waveset is the short piece of waveform between two consecutive detected zero-crossing boundaries in the mono working signal. Its duration is therefore determined by the waveform itself rather than by a fixed time grid: rapidly oscillating material produces shorter wavesets, while slower waveform motion produces longer ones. Operations such as Repeat, Reverse, Stretch, Compress, Shuffle, and Amplitude treat these waveform-defined pieces as the basic units of transformation.

Wavesets are not fixed-size grains. Their lengths can vary from one segment to the next, and they are derived from zero crossings rather than from an arbitrary grain duration. Pitch-Sync Telescope is the exception in this script: it first tries pitch-synchronous periods and falls back to zero-crossing wavesets only when there are not enough detected pitch periods.

Quick start

In Praat, select exactly one Sound object at least 50 ms long.
Run script… → Waveset_Distortion.praat.
Choose one of the 11 presets, or choose Custom.
For multichannel input, choose how the mono processing signal should be obtained.
For Custom, choose the operation and set only the parameters used by that operation.
Leave Keep_head_and_tail on if you want the material outside the detected processing span retained.
Choose an output-level policy. The default is Safety ceiling, which attenuates only when necessary.
Click OK. The result is named source_WSD_preset.

Starting points: Repeat gives a compact waveset stutter; group shuffle rearranges local blocks while preserving each block's internal order; Keep Strongest produces sparse thinning; Pitch-Sync Telescope compresses groups of detected periods into averaged cycles.

The 11 presets (+ Custom)

Preset	Type	Amount	Group	What it sets
Waveset Repeat	Repeat	2	—	Two copies of every waveset. Repeat level multiplier remains the form value (default 0.8).
Waveset Skip	Skip	2	—	Each waveset has probability 1/2 of being replaced by silence.
Waveset Reverse	Reverse	unused	—	Reverses the samples inside every waveset.
Waveset Stretch	Stretch	2	—	Approximately doubles each waveset duration.
Waveset Compress	Compress	2	—	Approximately halves each waveset duration.
Waveset Shuffle (individual)	Randomize	unused	1	Fisher-Yates shuffle of individual wavesets.
Waveset Shuffle (groups, CDP)	Randomize	unused	4	Shuffles four-waveset blocks; the tail remainder stays in order.
Waveset Amplitude	Amplitude	2	—	Alternates gain ×2 and ×0.5.
Keep Strongest (CDP)	Keep Strongest	unused	4	Keeps only the strongest waveset in each complete group.
Delete Weakest (CDP)	Delete Weakest	unused	4	Deletes only the weakest waveset in each complete group.
Pitch-Synchronous Telescope (CDP-inspired)	Pitch-Sync Telescope	unused	4	Collapses groups of four detected periods into averaged cycles; longest-cycle reference by default.

Presets override only their relevant operation fields. Settings such as multichannel handling, head/tail preservation, Preserve_length, output-level mode, ceiling, visualization, and playback remain under user control.

Operation types

Type	Control	Implemented behavior
Repeat	Amount, Repeat_level_multiplier	`round(Amount)` total copies of each waveset. Copy r after the original is scaled by `multiplier^r`. Amount is limited to 64 copies.
Skip	Amount ≥ 1	Each waveset is independently silenced with probability `1 / Amount`. The segment remains in place, so its duration is unchanged.
Reverse	Amount unused	Reverses samples inside each waveset; waveset order itself remains sequential.
Stretch	Amount > 0	Changes the sample count so each waveset lasts approximately `Amount` times as long, then returns it to the original sampling frequency.
Compress	Amount > 0	Resamples each waveset to roughly `sr / Amount` and then restores the sampling-frequency metadata, shortening duration by approximately the factor Amount.
Randomize	Group_size	Group size 1 shuffles individual wavesets. Larger values shuffle complete groups while preserving order inside each group; an incomplete final group is left in place.
Amplitude	Amount > 0	Alternates waveset gain between `Amount` and `1 / Amount`.
Keep Strongest	Group_size ≥ 2	Within each complete group, ranks wavesets by integrated absolute magnitude (mean \|x\| × duration) and keeps only the strongest. Remainder wavesets are retained.
Delete Weakest	Group_size ≥ 2	Uses the same absolute-magnitude measure, but removes only the weakest waveset in each complete group. Remainder wavesets are retained.
Pitch-Sync Telescope	Group_size, Telescope_mode	Uses pitch-period boundaries when available, otherwise zero-crossing wavesets. Each full group is time-normalized to a common reference duration and averaged into one waveform.

Pitch-Synchronous Telescope (CDP-inspired)

How Telescope works

Praat analyzes the mono working signal with To Pitch: 0.01, 75, 600 and converts the result to a pulse PointProcess.
If there are enough pulses for at least one full group, adjacent pulses define the processing periods.
If not, the mode falls back to consecutive zero-crossing wavesets.
For each complete group, the reference duration is either the longest cycle or the mean cycle length.
Every period in the group is resampled to that reference duration.
The normalized waveforms are added sample-by-sample and divided by the group size.
The whole group is therefore replaced by one averaged waveform. Any incomplete remainder passes through unchanged.

This is intentionally labelled CDP-inspired: the zero-crossing fallback resembles the waveset idea behind CDP telescope processing, while the main path is pitch-synchronous and therefore not a literal clone of CDP distort_tel.

Pitch tracking is fixed at 75–600 Hz. Material outside that useful pitch range, strongly unpitched material, or material that does not yield enough pulses will use the zero-crossing fallback if possible.

Parameters & defaults

Parameter	Default	Meaning
Preset	Custom	Chooses a prepared operation setting.
Multichannel_handling	Fold to mono	Fold, use channel 1, or refuse multichannel input. Output is mono.
Type	Repeat	One of the ten processing modes.
Amount	2.0	Mode-specific; unused by Reverse, Randomize, Keep/Delete, and Telescope.
Repeat_level_multiplier	0.8	Per-repeat level multiplier; below 1 decays, 1 is unchanged, above 1 grows.
Group_size	4	Rounded to an integer; minimum 2 for Keep/Delete/Telescope, 1 allowed for individual shuffle.
Telescope_mode	Longest cycle	Reference duration for the averaged cycle: longest or mean.
Preserve_length	off	Forces total output seconds to match the source by trimming the end or padding silence at the end.
Keep_head_and_tail	on	Restores source material before the first detected boundary and after the last.
Output_level_mode	Safety ceiling	None, attenuate-only ceiling, or unconditional peak normalization.
Ceiling_peak	0.95	Linear sample-peak target/ceiling; must be greater than 0 and at most 1.
Draw_visualization	on	Draws the diagnostic Picture.
Play_result	on	Plays the resulting Sound.

Length and output level

Length behavior

Skip, Reverse, Randomize, Amplitude: do not intrinsically change duration. With head/tail preservation on and Preserve_length off, the script corrects any sample-grid drift so total duration matches the source.
Repeat, Stretch, Compress: intentionally change duration.
Keep Strongest / Delete Weakest: remove wavesets and therefore shorten the processed span.
Telescope: replaces each full group by one reference-length averaged cycle, so full groups are compressed in time; remainder periods pass through.
Preserve_length: does not time-warp or realign the processed material. A long result is trimmed at the end; a short result is padded with silence at the end.

Output level modes

Mode	Behavior
None	Leaves the processed sample level unchanged.
Safety ceiling (default)	Scales down only when the sample peak exceeds `Ceiling_peak`. Quiet outputs are not boosted.
Peak normalize	Scales any non-silent result to `Ceiling_peak`, upward or downward.

The peak measurement is Praat's absolute sample extremum. It is not a true-peak or inter-sample-peak measurement.

Visualization

When Draw_visualization is enabled, the Picture contains:

Input waveform in grey.
Output waveform in blue.
Original spectrogram from 0–5 kHz.
Processed spectrogram from 0–5 kHz.
Summary strip with operation, Amount when relevant, segment count, durations, channel handling, output-level action, and processing time.

For multichannel sources, the displayed input waveform and input spectrogram use channel 1 for the visual reference. The summary states whether the actual processing signal was folded to mono or taken from channel 1.

FAQ / troubleshooting

Not enough zero crossings

Modes 1–9 need at least two detected zero crossings, which bound one complete waveset. Very quiet, strongly DC-offset, or unusually shaped material may not provide enough crossings.

Fold to mono loses most of the signal

If the folded peak falls below 10% of the original multichannel peak, the script treats this as strong cancellation and automatically uses channel 1 instead.

Telescope uses zero-crossing fallback

This means the 75–600 Hz pitch analysis did not provide enough pulses for the selected group size. The mode then uses ordinary zero-crossing wavesets if at least two crossings exist.

Preserve_length changes the ending

This option is deliberately simple: it trims a long result at the tail or appends silence to a short result. It does not redistribute or stretch the processed events to fit the original timeline.

Keep Strongest / Delete Weakest measurement

The ranking quantity is integrated absolute magnitude, implemented as mean |x| over the waveset multiplied by its duration. It is not Praat Get energy and not an RMS measurement.

Processing limit

The script refuses runs with more than 100,000 detected wavesets/periods. Use a shorter selection if that limit is reached.