Kinematic Physics Envelope — v1.5 User Guide

A bouncing-ball physics model used as a control source for time-varying amplitude shaping. The simulated height and speed trajectory can be stretched, kept in real time, or looped across the selected Sound.

Author: Shai Cohen Version: 1.5 (2026) Input: exactly one Sound Engine: fixed 1 ms physics timestep License: MIT

Contents:

What it does Quick start Processing pipeline Presets Physics parameters Envelope mappings Time mapping Modifiers Output & normalization Visualization Validation & limits

What this does

Kinematic Physics Envelope simulates one physical system: a point-like ball moving vertically under gravity, optionally with linear air resistance, and reflecting from the ground according to a bounce coefficient. The resulting trajectory is converted to a gain envelope and multiplied directly with every channel of the selected Sound.

One model, many presets: preset names such as Earthquake Tremor and Heartbeat Pulse describe the resulting impact pattern. They are not separate seismic, cardiovascular, pendulum, spring, or rolling-body models.

The physics simulation is independent of the Sound duration. It runs in real time at a fixed 1 ms step, with sub-step refinement at each ground crossing. Only after that simulation is complete is the trajectory mapped onto the audio timeline.

Quick start

Select exactly one Sound.
Run Kinematic_Physics_Envelope.praat.
Choose one of the named Preset entries, or use Custom.
Choose the Mapping that turns the trajectory into amplitude: Height, Speed, Kinetic energy, or Combined.
Choose Time_mapping: Stretch, Real-time, or Loop.
Optionally reverse or smooth the envelope, then choose whether to Normalize, Visualize, and Play.

Preset precedence: a named preset replaces the physics parameters, Mapping, and Amplitude_scale listed in the preset table. It does not replace Time_mapping, Reverse_envelope, Smoothing_passes, Min_amplitude, Normalize, Visualize, or Play.

Processing pipeline

1. Simulate vertical fall + rebounds at 1 ms 2. Detect/refine ground-contact times 3. Resample the physics trajectory onto an audio-rate control grid 4. Apply Stretch / Real-time / Loop time mapping 5. Convert height and/or speed to normalized amplitude 6. Apply Amplitude_scale and Min_amplitude; clamp maximum to 2.0 7. Optional Reverse_envelope 8. Optional repeated smoothing 9. Build a mono control Sound over the source time domain 10. Multiply all source channels by that control Sound 11. Optional explicit peak normalization to 0.95

The envelope is applied in the linear-amplitude domain. The script does not use Sound & IntensityTier: Multiply, so there is no hidden peak rescaling before the explicit Normalize option.

Presets

The form contains Custom plus 12 named presets. All named presets run the same fall-and-bounce equations.

Preset	h0 (m)	v0 (m/s)	g (m/s²)	Bounce	Max rebounds	Drag	Mapping	Amp scale
Bouncy Rubber Ball	1.2	6.0	9.8	0.75	8	0	Combined	1.0
Steel Ball Drop	2.0	3.0	9.8	0.92	12	0	Height	1.2
Ping Pong Frenzy	0.8	10.0	9.8	0.85	15	0	Speed	0.9
Basketball Dribble	1.5	4.0	9.8	0.70	6	0	Combined	1.1
Super Ball Chaos	1.0	8.0	9.8	0.95	20	0	Speed	0.85
Dropping Stone	3.0	0.0	12.0	0.00	0	0	Speed	1.5
Feather Falling	2.0	1.0	9.8	0.30	3	6.5	Height	0.8
Moon Gravity	1.5	4.0	1.62	0.65	8	0	Combined	1.0
Tennis Ball	1.3	5.5	9.8	0.73	7	0	Combined	1.0
Water Skipping Stone	0.5	12.0	9.8	0.60	10	0	Speed	0.75
Earthquake Tremor	0.3	3.0	15.0	0.88	25	0	Speed	1.3
Heartbeat Pulse	0.8	6.0	18.0	0.65	12	0	Speed	1.4

Physics model and parameters

Free flight

At each 1 ms Euler step, velocity and height are updated as:

v_next = v - g·dt - drag·v·dt h_next = h + v_next·dt dt = 0.001 s

When the trajectory crosses the ground, the script linearly interpolates within the 1 ms step to refine the contact time. The incident velocity at that sub-step is reflected according to:

v_after = -v_at_contact · Bounce_coefficient

The ball settles instead of reflecting when the rebound budget has been exhausted or when the post-impact speed is below 0.01 m/s.

Parameter	Default	Meaning
Initial_height_m	1.0	Starting height. Must be ≥ 0.
Initial_velocity_m_s	5.0	Initial vertical velocity. Positive values launch the ball upward before gravity turns it downward.
Gravity_m_s2	9.8	Downward acceleration. Must be > 0.
Bounce_coefficient	0.7	Velocity reflection coefficient, constrained to 0–1.
Max_bounces	10	Maximum number of actual rebounds. The final settling ground contact is reported separately and does not count as a rebound.
Drag_coefficient	0.0	Linear velocity-proportional damping term. The numerical stability limit is enforced by the script.

Simulation limits: physics runs for at most 30 seconds. If the ball has not settled by then, the simulation is truncated and reported. Lowering Bounce_coefficient or Max_bounces, or increasing Drag_coefficient, tends to shorten the sequence.

Envelope mappings

After the physics run, the script measures the actual simulated maximum height and speed and uses them to normalize the selected control quantity. This includes trajectories in which a positive initial velocity sends the ball above its starting height.

Mapping	Normalized control	Interpretation
Height	`h / maxHeight`	Height trajectory; a potential-energy proxy for fixed mass and gravity.
Speed	`\|v\| / maxVelocity`	Velocity magnitude, not kinetic energy.
Kinetic energy	`v² / maxVelocity²`	Quantity proportional to kinetic energy for fixed mass.
Combined	`(h/maxHeight + \|v\|/maxVelocity) / 2`	Equal average of normalized height and normalized speed.

For every mapping, the raw normalized value is then processed as:

amp = normalized_mapping · Amplitude_scale amp = max(amp, Min_amplitude) amp = min(amp, 2.0)

Amplitude_scale is therefore a literal gain scale before the floor and upper clamp. Min_amplitude is a gain floor, not a dB value; its allowed range is 0–2.

Time mapping

Stretch

The complete simulated physics sequence is proportionally mapped across the complete Sound duration:

physics_time = audio_time · physics_duration / audio_duration

This changes the apparent timing of the physics but does not change the audio duration.

Real-time

The physics trajectory keeps its actual simulated timing:

physics_time = audio_time

Once the ball has settled, interpolation remains at the settled state. After amplitude mapping and clamping, the remaining audio therefore uses the resulting floor — normally Min_amplitude, not literal silence.

Loop

The physics sequence is tiled across the Sound:

physics_time = audio_time mod physics_duration

To reduce discontinuities at loop seams, the last 5% of each physics cycle is blended toward the start state. The crossfade is capped at 50 ms.

Bounce markers in the visualization follow the same time mapping. Loop mode repeats markers for repeated cycles; Reverse_envelope mirrors the markers shown on the envelope panel.

Modifiers

Reverse_envelope

Reverses the completed gain-envelope array in time. It does not reverse the underlying physics simulation itself. The physics-trajectory panel remains unreversed, while the envelope panel mirrors its bounce markers to match the applied curve.

Smoothing_passes

Each pass applies a weighted three-point smoother to interior control points:

smoothed[i] = (env[i-1] + 2·env[i] + env[i+1]) / 4

The first and last control points are preserved on each pass. Smoothing is applied after reverse, if reverse is enabled.

Control-grid resolution

The envelope aims for approximately 2 ms control spacing:

numPoints ≈ round(audio_duration / 0.002) + 1 minimum = 100 points maximum = 20,000 points

On long files the 20,000-point cap makes the effective spacing coarser than 2 ms; the exact spacing is reported in the Info window. Sample times use Praat's sample-center convention so the computed control values align with the control Sound that is actually applied.

Envelope application, output & normalization

The final envelope is written to a mono control Sound spanning the selected Sound's actual start and end times. A copy of the source is then multiplied directly by the time lookup of that envelope:

output(t, channel) = input(t, channel) · envelope(t)

The same gain envelope is applied to every channel; channel count and audio sampling rate are preserved. The temporary envelope Sound is removed at the end.

Output name

Envelope-processing output is named <source>_<PresetName>. For Custom, the suffix is _Custom.

Normalize

Normalize defaults to on. When enabled, the final result is explicitly peak-scaled to 0.95 only if its current peak is non-zero. A fully silent result is left unchanged and the skipped normalization is reported.

Normalization changes absolute envelope gain. Because peak normalization can amplify as well as attenuate, literal values produced by Amplitude_scale and Min_amplitude are preserved only when Normalize is off.

Visualization

When Visualize is enabled, the script draws an 8-inch suite-style figure with four main data panels plus a summary strip:

Physics trajectory: mapped height trajectory with a ground line and unreversed ground-contact markers.
Envelope: the actual gain curve after mapping, scale/floor/clamp, optional reverse, and smoothing. A dashed line marks unity gain; bounce markers follow the displayed envelope.
Input: original waveform.
Result: processed waveform.
Summary: physical parameters, mapping/time-mapping choice, rebound count, marker count, reverse status, audio/physics duration, smoothing passes, and output peak.

The physics and envelope panels both use the Sound's real time domain. Reverse_envelope only reverses the envelope panel; the physics trajectory remains a representation of the forward physical simulation.

Validation & safety limits

Setting	Rule
Selected input	Exactly one Sound is required.
Initial_height_m	Must be ≥ 0.
Gravity_m_s2	Must be > 0.
Bounce_coefficient	Must be 0–1.
Drag_coefficient	Must be ≥ 0 and ≤ 500 at the fixed 1 ms step. Higher values are rejected because the explicit-Euler damping factor would become numerically unstable.
Max_bounces	Custom values above 30,000 are clamped and reported. This equals the maximum number of 1 ms steps available in the 30 s physics window.
Amplitude_scale	Must be ≥ 0.
Min_amplitude	Must be 0–2.
Smoothing_passes	Must be ≥ 0.
Physics duration	Hard cap: 30 s. Truncation before settling is reported.
Envelope grid	100–20,000 points, targeting ~2 ms spacing.
Envelope gain	After Amplitude_scale, constrained to Min_amplitude…2.0.

Implementation notes

The script distinguishes rebounds (actual reflections, capped by Max_bounces) from ground contacts (which also include the final settling contact).
Physics maxima used for envelope normalization are measured from the simulated arrays rather than estimated from the starting conditions.
The source Sound is retained. The final result is selected and optionally played.
There is no random component and no seed parameter; identical inputs and settings are deterministic.