Envelope Application — User Guide

Apply a reproducible time-varying gain envelope directly to a selected Sound, using eleven envelope families, optional curve shaping, inversion, time reversal, smoothing, and visualization.

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

Contents:

What this does Quick start Presets Envelope types Parameters & modifiers Processing details Visualization Limits & cautions

What this does

Envelope Application v1.5 creates a mono control envelope over the full duration of one selected Sound and multiplies that envelope directly into every input channel. The original channel count, sampling frequency, and duration are preserved. The result is named <original>_<EnvelopeName>, for example voice_ADSR or texture_Tremolo.

Core rule: the processor is a time-varying gain stage. Before optional peak normalization, output(sample) = input(sample) × envelope(sample). The envelope is clamped to the range 0–1, so the envelope stage itself never amplifies above unity.

The script no longer uses IntensityTier or AmplitudeTier multiplication. It renders the control shape as an actual Sound and applies it by direct sample-column multiplication. Therefore the envelope displayed in the Picture window is the envelope applied to the audio, including optional smoothing.

Quick start

Select exactly one Sound object.
Run Envelope_Application.praat.
Choose a preset or use Custom.
Choose an envelope type and set the relevant levels, times, curve, modulation, and modifiers.
Leave Peak_normalize_output off when you want the envelope's absolute gain levels to remain meaningful.
Enable Visualize to inspect the input, the applied envelope, and the result.

Important: most controls remain visible even when a particular envelope does not use them. The tables below identify which parameters actually affect each envelope type.

Presets

Preset	Envelope / values imposed by the preset
Custom	Uses the values currently shown in the form.
Fade In	Linear; Start 0, End 1.
Fade Out	Linear; Start 1, End 0.
Swell (triangle)	Triangle; Peak 1.
Percussive	Percussive; Attack 5 ms, Release 300 ms, Peak 1, Exponential curve, Curve_amount 4.
ADSR Pad	ADSR; Attack 300 ms, Decay 200 ms, Sustain level 0.7, Sustain 0 = auto, Release 500 ms, Peak 1.
Plucked	Percussive; Attack 1 ms, Release = 80% of the file duration, Peak 1, Exponential curve, Curve_amount 3.
Tremolo	Tremolo; Peak 1, Rate 6 Hz, Depth 0.4.
Gate	Trapezoid; Peak 1, Attack 50 ms, Release 50 ms; the flat section fills the remaining duration.

Presets overwrite only the parameters explicitly assigned by the script. Other form values can remain present but may be irrelevant to the selected envelope.

Envelope types

Let p = t / duration, with p running from 0 to 1. After the base envelope is evaluated, Mirror may reverse time and Invert may replace the gain by 1 − gain.

1. Linear

E(t) = Start + (End − Start) × p

Uses Start_level and End_level.

2. Exponential

shape(p) = (1 − exp(−k p)) / (1 − exp(−k))
E(t) = Start + (End − Start) × shape(p)

k = Curve_amount. The normalized shape reaches the requested endpoints even when Start or End is zero. Curve_amount = 0 is treated as the linear limit. Negative values are clamped to 0 and reported.

3. Sine (S-curve)

E(t) = Start + (End − Start) × (1 − cos(πp)) / 2

A fixed raised-cosine interpolation between Start and End. The Curve dropdown does not alter this envelope type.

4. Triangle

0 ≤ p < 0.5: E = Peak × (p / 0.5)
0.5 ≤ p ≤ 1: E = Peak × (1 − (p − 0.5) / 0.5)

Rises from zero to Peak_level at the midpoint, then returns to zero.

5. Trapezoid

Attack rises 0→Peak using the selected Curve, the middle remains at Peak, and Release falls Peak→0 using the same Curve. The middle duration is duration − Attack − Release. If the requested stages exceed the file duration, stage times are proportionally reduced to fit.

6. Gaussian

A Gaussian centered at the middle of the file with σ = duration/4, then normalized so the envelope is exactly zero at both edges and reaches Peak_level at the center.

7. Step

t < duration/2: E = Start
t ≥ duration/2: E = End

The midpoint transition is rendered as a true hard step rather than as a short interpolation ramp. Smoothing can intentionally soften it afterward.

8. ASR

Attack rises 0→Peak, Sustain holds Peak, and Release falls Peak→0. Sustain = 0 means automatic sustain: the script fills the remaining time after Attack and Release. A positive Sustain value requests an explicit duration.

9. Percussive

Attack rises 0→Peak and Release falls Peak→0; after Attack + Release the envelope remains zero. Both stages use the selected Curve.

10. ADSR

Attack rises 0→Peak, Decay falls Peak→Sustain_level × Peak, Sustain holds that level, and Release falls to zero. Sustain = 0 automatically fills the unused time. If explicitly requested stage times exceed the file duration, they are proportionally compressed to fit.

11. Tremolo

LFO(t) = 0.5 + 0.5 sin(2π f t)
E(t) = Peak × [1 − Depth × (1 − LFO(t))]

Depth = 0 gives constant Peak_level; Depth = 1 reaches zero at each trough while still reaching Peak_level at each crest. Depth is clamped to 0–1. Rate must be greater than 0 Hz and below the Sound's Nyquist frequency.

Parameters & modifiers

Parameter	Default	Actual behavior
Start_level	0.0	Used by Linear, Exponential, Sine, and Step. Clamped to 0–1.
End_level	1.0	Used by Linear, Exponential, Sine, and Step. Clamped to 0–1.
Peak_level	1.0	Peak or ceiling for Triangle, Trapezoid, Gaussian, ASR, Percussive, ADSR, and Tremolo. Clamped to 0–1.
Sustain_level	0.7	ADSR sustain ratio relative to Peak_level. Clamped to 0–1.
Attack	0.02 s	Stage time for Trapezoid, ASR, Percussive, ADSR. Negative values are clamped to 0; 0 means an instantaneous/skipped attack.
Decay	0.1 s	Used by ADSR. Negative values are clamped to 0; 0 means an instantaneous decay.
Sustain	0 s	ASR/ADSR sustain duration. 0 means auto. Negative values are clamped to 0.
Release	0.2 s	Used by Trapezoid, ASR, Percussive, ADSR. Negative values are clamped to 0; 0 means an instantaneous release.
Curve	Linear	Stage shape for Trapezoid, ASR, Percussive, and ADSR: Linear, normalized Exponential, or Sine.
Curve_amount	4	Curvature constant for normalized Exponential shapes, including the standalone Exponential type. Negative values are clamped to 0; 0 is the linear limit.
Tremolo_rate_Hz	5	Used only by Tremolo. Must be >0 and <Nyquist.
Tremolo_depth	0.5	Used only by Tremolo. Clamped to 0–1.
Invert	off	After the base shape is computed, replaces gain by `1 − gain`, then clamps to 0–1.
Mirror	off	Time-reverses the envelope by evaluating it at `duration − t`. For ADSR, the stage visualization also reverses to R→S→D→A.
Smoothing	0	When greater than 0, applies that many passes of a multi-tap moving average spread across approximately ±5 ms. The first and last samples are then restored to the exact requested boundary levels.
Peak_normalize_output	off	If on and the result is non-silent, `Scale peak: 0.95` is applied. Silent output is left unchanged.
Visualize	on	Draws the input, applied envelope, result, and summary.
Play	on	Plays the final Sound after processing.

Processing details

Envelope grid

The envelope control grid uses approximately 500 points per second, with a minimum of 200 and a normal maximum of 10,000. Tremolo can densify the grid to at least 30 points per LFO cycle, capped at 100,000 points. Adjacent control points are rendered as piecewise-linear segments into a one-channel Sound at the input sampling frequency.

Exact boundaries and Step handling

After optional smoothing, the first and last samples of the envelope Sound are explicitly set to the requested boundary values. Step is separately re-rendered as a hard time-domain jump at the midpoint before smoothing, so with Smoothing = 0 it is not approximated by a short ramp.

Stage-time fitting

For Trapezoid, ASR, Percussive, and ADSR, if requested stages do not fit in the selected Sound, the relevant stage times are proportionally scaled so the envelope completes within the file. The adjustment is reported in the Info window.

Direct multichannel multiplication

The same mono envelope is applied by sample index to every channel of the selected Sound. There is no channel summing and no change of channel count. After smoothing and boundary anchoring, the envelope is clamped to 0–1 before multiplication.

Peak normalization

Peak_normalize_output is intentionally off by default. When enabled, it rescales a non-silent result to a peak of 0.95, which can either attenuate or amplify the processed Sound. This means absolute envelope levels are no longer preserved: for example, a constant gain of 0.5 can be re-amplified by the normalization stage. A fully silent output skips normalization.

Output naming

The final object is named <input name>_<EnvelopeName>. The suffix is based on the actual envelope type, not the preset name.

Visualization

The Picture window uses the Praat AudioTools 8-inch layout and shows three principal panels plus a summary strip:

Input: the original Sound waveform.
Envelope: the actual envelope Sound that is multiplied into the audio. ADSR adds colored A/D/S/R stage regions.
Result: the processed waveform.
Summary: input duration/rate/channels, envelope/preset, relevant parameters, modifier states, smoothing, normalization state, and output peak.

ADSR + Mirror: the stage map follows the time reversal. It is displayed as R → S → D → A at the reversed positions. If an explicitly timed ADSR occupies less than the file duration, unused zero-level time is left neutral rather than being mislabeled as Release.

Limits & cautions

Step discontinuity: with Smoothing = 0, a hard gain jump can create a click or broad-band transient if the input sample value is non-zero at the boundary.
Normalization changes the intended absolute level: use it only when a fixed final peak matters more than preserving the envelope's gain scale.
Tremolo at high rates: the script rejects control rates at or above Nyquist, but high-rate amplitude modulation can still create spectral sidebands that exceed the audio Nyquist limit for high-frequency source material. The Nyquist validation is not a guarantee of alias-free output.
Smoothing changes the interior shape: multiple passes progressively round sharp corners and steps; endpoints are re-anchored afterward.
Mirror reverses time, not labels only: it reverses the complete envelope before application.
Envelope gain is capped: after modifiers and smoothing the control signal is clamped to 0–1, so this stage cannot intentionally boost above unity.