Physics-Based Stereo Dynamics — User Guide

A stereo transformation in which an analytically resolved bouncing-ball simulation controls level while a prescribed horizontal path controls stereo position. The tool can use either simple lateral-position weighting or an optional geometric distance model, then mixes the processed result with the source under selectable wet/dry and output-gain policies.

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

Contents:

What this does Quick start Simulation & mapping Named presets Parameters Input, mix & gain Visualization Limits & interpretation

What this does

Physics-Based Stereo Dynamics uses one selected Sound object and produces a stereo result of the same duration. Its vertical control signal comes from a ballistic point-mass model under constant gravity. Ground impacts are solved analytically within each simulation step and the outgoing velocity is scaled by a coefficient of restitution. Horizontal motion is separate: it is a user-defined linear or sinusoidal pan path, not a solved physical trajectory.

What is physically simulated — and what is not: vertical height and velocity follow ballistic motion with bounce events. Horizontal position is a prescribed control path. Consequently, presets such as Spring Oscillation and Pendulum Swing are names for musical scenarios: they use ballistic height plus sinusoidal panning, not spring or pendulum equations.

The instantaneous height/speed state is mapped to an amplitude control. That level is optionally modified either by a simple function of stereo position or by a geometric distance calculation. The resulting amplitude is split between left and right with a square-root constant-power pan law.

Key implementation points

Exactly one Sound is required.
15 named presets + Custom. The named presets own the complete Custom physics/pan/level/mapping block; the global input/mix/output controls remain active.
Ballistic impact timing: impacts are solved inside the timestep rather than detected only after the state has crossed below the ground.
Two mapping families: normalized control curves (height, speed, or their mean) and energy-derived curves (potential, kinetic, or total mechanical energy).
Two level-vs-position families: lateral weighting based only on |pan|, or geometric distance based on pan, height and listener distance.
True panning by default: multichannel/stereo input is downmixed to mono before the pan law. A separate Preserve stereo option performs balance modulation instead.
Selectable wet/dry law: equal-power or linear.
Selectable output gain: attenuate only, peak-normalize to 0.99, or no gain change.

Quick start

Select exactly one Sound object in Praat.
Run Physics-Based_Stereo_Dynamics.praat.
For a first test, leave the default Bouncy Rubber Ball (L to R) preset.
Leave Input_handling on Downmix to mono and pan (true panning) if you want the sound to move as one source.
Choose the wet/dry and output-gain policy. The default is 100% wet, equal-power mix, attenuate only.
Run the script. The result is named originalName_Preset_Name; the original Sound remains in the Objects list.

Named presets versus Custom: when a named preset is selected, the fields from Physics through Amplitude_scale are intentionally ignored and replaced by the preset values. Input_handling, Mix_percent, Mix_and_output_gain, Draw_visualization, and Play_result remain active for every preset.

Simulation & mapping

Vertical ballistic model

Between impacts: h(t + Δt) = h(t) + v(t)Δt − ½gΔt² v(t + Δt) = v(t) − gΔt Impact time τ inside a step is obtained from: ½gτ² − vτ − h = 0 At an impact: v_after = −v_impact × e where e is the coefficient of restitution.

The simulation nominally runs at 2000 Hz, with at least 400 states and at most 400,000 states. The final stored state is exactly at the end of the audio. Since v0.6.2 the script does not integrate one additional step beyond that endpoint, so reported bounce counts cannot include an impact occurring after the rendered sound.

Negative starting height is clamped to 0; non-positive gravity falls back to 9.8; negative restitution is clamped to 0. Restitution above 1 is allowed as a deliberate superelastic effect and is reported as non-physical. If the object begins at ground level with no upward velocity, the script stops because no motion would occur.

Prescribed horizontal path

Linear: pan(q) = start + (end − start)q Oscillating: centre = (start + end)/2 halfRange = (end − start)/2 pan(q) = centre + halfRange × sin(2π × cycles × q) where q runs from 0 to 1 over the Sound duration.

The DSP clamps the resulting pan to [-1,+1] before both the stereo pan law and the level-vs-position stage. An endpoint outside that interval is therefore a saturation request, not a virtual position beyond the loudspeakers. Since v0.6.2 the Motion Path visualization shows this same clamped position.

Physics-to-amplitude mappings

Mapping	Amplitude control before level-vs-position weighting
Height (control curve)	`h / max(h)`, using the measured maximum over the simulation.
Speed (control curve)	`\|v\| / max(\|v\|)`, using the measured maximum.
Height and speed, mean	Arithmetic mean of the two normalized control curves.
Potential energy	`sqrt((g·h) / max(g·h))`.
Kinetic energy	`sqrt((v²/2) / max(v²/2))`.
Total mechanical energy	`sqrt((g·h + v²/2) / max(g·h + v²/2))`. Since v0.6.4 the denominator is the maximum of the total energy at one simulation instant, not `max(Ep)+max(Ek)`.

The square root in the energy mappings converts a normalized energy-like quantity into an amplitude-like control under the usual proportionality between signal energy and squared amplitude. Amplitude_scale is then applied multiplicatively.

Level versus position

Lateral weighting, louder at centre: d = |pan| gain = 1 / (1 + amount·d) Lateral weighting, louder at edges: d = |pan| gain = 1 / (1 + amount·(1 − d)) Geometric distance: x = pan × stage_half_width distance = sqrt(x² + h² + listener_distance²) distance = max(distance, reference_distance) gain = reference_distance / distance

Terminology: the first two modes are not physical distance models; they use only the absolute stereo-pan coordinate and ignore height. Only Geometric distance uses a spatial distance. Even there, the model is intentionally simple: it applies inverse-distance gain only and does not model air absorption, propagation delay, HRTF cues, room acoustics, Doppler shift, or source directivity.

Stereo pan law

p = clamp(pan, −1, +1) panNorm = (p + 1)/2 L = amplitude × sqrt(1 − panNorm) R = amplitude × sqrt(panNorm) Therefore: L² + R² = amplitude²

This is a constant-power square-root amplitude law. It mathematically preserves the sum of squared channel gains for the generated mono source. It should not be interpreted as a complete psychoacoustic localization or loudness model.

Named presets

The 15 named presets all use lateral weighting, louder at centre and the control-curve mapping family. Their values below replace the Custom block. Only Spring Oscillation and Pendulum Swing use sinusoidal panning; all other named presets use linear panning.

Preset	Physics: h0 / v0 / g / e / bounces	Pan	Level amount	Control mapping	Amp
Bouncy Rubber Ball	1.2 / 6.0 / 9.8 / 0.75 / 8	−0.9 → +0.9, linear	0.30	Height+Speed mean	1.00
Steel Ball Drop	2.0 / 3.0 / 9.8 / 0.92 / 12	0 → 0, linear	0.00	Height	1.20
Ping Pong Frenzy	0.8 / 10.0 / 9.8 / 0.85 / 15	−1 → +1, linear	0.50	Speed	0.90
Basketball Dribble	1.5 / 4.0 / 9.8 / 0.70 / 6	+0.5 → +0.7, linear	0.20	Height+Speed mean	1.10
Super Ball Chaos	1.0 / 8.0 / 9.8 / 0.95 / 20	−0.8 → +0.2, linear	0.40	Speed	0.85
Dropping Stone	3.0 / 0.0 / 12.0 / 0.00 / 0	0 → 0, linear	0.00	Speed	1.50
Feather Falling	2.0 / 1.0 / 2.0 / 0.30 / 3	−0.5 → +0.5, linear	0.20	Height	0.80
Moon Gravity	1.5 / 4.0 / 1.62 / 0.65 / 8	−0.8 → +0.8, linear	0.20	Height+Speed mean	1.00
Tennis Ball	1.3 / 5.5 / 9.8 / 0.73 / 7	−1 → +1, linear	0.60	Height+Speed mean	1.00
Water Skipping Stone	0.5 / 12.0 / 9.8 / 0.60 / 10	−0.2 → +1.5, linear; DSP clips at +1	0.80	Speed	0.75
Earthquake Tremor	0.3 / 3.0 / 15.0 / 0.88 / 25	−0.3 → +0.3, linear	0.10	Speed	1.30
Heartbeat Pulse	0.8 / 6.0 / 18.0 / 0.65 / 12	0 → 0, linear	0.00	Speed	1.40
Spring Oscillation	1.0 / 7.0 / 8.0 / 0.82 / 15	−1 ↔ +1, sine, 2 cycles	0.40	Height+Speed mean	0.95
Pendulum Swing	1.8 / 2.5 / 5.0 / 0.90 / 10	−1 ↔ +1, sine, 2 cycles	0.70	Height	1.10
Rolling Downhill	2.5 / 1.0 / 15.0 / 0.45 / 5	−1 → +1, linear	0.50	Speed	1.30

Preset names are compositional metaphors. They are useful starting configurations, but the script does not claim to reproduce the full mechanics or acoustics of a basketball, pendulum, rolling object, skipping stone, earthquake, or heartbeat.

Parameters

Custom-only block

Control	Default	Meaning / behavior
Physics	`h0=1.2 v0=6.0 grav=9.8 rest=0.75 bounces=8`	Starting height (m), vertical velocity (m/s), gravity (m/s²), restitution, and maximum bounce count. Keep the key names; order and spacing may change.
Pan_path	`start=-0.9 end=0.9 cycles=2`	Horizontal pan endpoints and the cycle count used only by Oscillating motion.
Pan_motion	Linear	Linear interpolation or sine oscillation between the endpoints.
Level_model	Lateral weighting, louder at centre	Centre weighting, edge weighting, or geometric distance.
Attenuation_amount	0.3	Non-negative strength for the lateral-weighting modes. It is not used by the geometric-distance formula.
Geometry	`width=3.0 listener=4.0 ref=1.0`	Stage half-width, listener distance, and reference distance in meters for Geometric distance. Invalid/non-positive values fall back to 3, 4, and 1 respectively.
Mapping	Height and speed, mean	Six mappings: three control curves and three energy-derived curves.
Amplitude_scale	1.0	Multiplicative scale after mapping and position/distance weighting. Negative values are clamped to 0.

Global controls — active for Custom and every named preset

Control	Default	Behavior
Input_handling	Downmix to mono and pan	True point-source panning, or Preserve stereo / modulate balance. Preserve-stereo is meaningful for 2-channel input; inputs with more than two channels are forced to downmix.
Mix_percent	100	Wet percentage, clamped to 0–100.
Mix_and_output_gain	Equal-power mix, attenuate only	Six combinations: equal-power or linear wet/dry, each paired with attenuate-only, peak-normalize, or no output gain change.
Draw_visualization	On	Draws the suite-standard diagnostic figure.
Play_result	On	Plays the generated result after processing.

Compact sentence fields: if a required key= item is missing or malformed in Custom, the script substitutes that item's default and reports the fallback in the Info window. The numeric values can be reordered or respaced; the key names themselves must remain.

Input, wet/dry mix & output gain

Input handling

Downmix to mono and pan — default

If the source has more than one channel, Praat converts it to mono. The processed mono source is duplicated into two paths and the computed left/right envelopes implement the constant-power pan. This is the appropriate mode when the physical metaphor is one moving point source.

Preserve stereo, modulate balance

For a stereo source, the left envelope multiplies the original left channel and the right envelope multiplies the original right channel. This preserves the source's channel assignment but does not make material already isolated in one channel travel through the opposite channel. It is therefore balance modulation rather than true panning. A source with more than two channels cannot use this mode and is automatically downmixed.

Wet/dry law

Equal-power mix: wet = sin(mixFraction × π/2) dry = cos(mixFraction × π/2) Linear mix: wet = mixFraction dry = 1 − mixFraction

If the dry source is mono, it is placed at stereo center with 1/√2 in each channel before mixing, rather than duplicated at full level. If Preserve stereo is active on a stereo source, its original stereo dry signal is retained.

Output gain policies

Policy	What it does
Attenuate only	Default. If the mixed peak exceeds 0.99, apply one shared gain to bring it down to 0.99. If the peak is already below 0.99, do not amplify it. This preserves meaningful differences created by `Amplitude_scale` and attenuation.
Peak normalise	If the peak is nonzero, scale it to exactly 0.99. This may amplify a quiet result as well as attenuate a loud one.
No gain change	Leave the mixed level unchanged, even if the peak exceeds 1.0.

A floor of 1e-6 (−120 dB) is applied only to the left/right gain values written to the IntensityTiers so that log10 remains defined.

Visualization

The v0.6.4 visualization contains a title plus five diagnostic panels. It is intended to show what the algorithm actually computed rather than to imply a literal 3D acoustic scene.

Panel	Contents
A — Motion Path	Pan versus simulated height. The horizontal coordinate is the clamped pan used by the DSP; vertical position is ballistic height. Path color changes with time. Red ground markers are approximate sampled detections of impact states and are sized by the amplitude trace.
B — Height & Speed	Height and absolute speed versus time, each divided by its own measured maximum.
C — Channel Gains	The computed left and right gain traces before the −120 dB tier floor. These include mapping, amplitude scale, level-vs-position weighting, and the constant-power pan law.
D — Output	Final left and right waveforms after wet/dry mixing and the selected output-gain policy.
E — Summary	Preset/source, physical parameters, bounce count, measured maxima, simulation grid, pan mode, mapping, level model, wet percentage, mix law, gain policy, and peak before/after output gain.

Impact markers are visual diagnostics, not the authoritative bounce counter. The simulation itself resolves impacts analytically; the panel detects marker locations from the downsampled states used for drawing.

Limits & interpretation

The model is a control generator for composition, not a full rigid-body or acoustic simulation.
Horizontal motion is not affected by gravity, collisions, momentum, friction, or the vertical state.
The listener/speaker symbols in the Motion Path panel are explanatory graphics; the pan axis remains a normalized stereo-control coordinate.
The geometric-distance option uses a simple Euclidean distance and inverse-distance amplitude factor. It does not render binaural or multichannel spatial acoustics.
The constant-power pan law preserves squared gain for a mono source mathematically; perceived loudness still depends on playback system, room, source content, and listener position.
Named presets are not measurements of real balls or physical objects. Their names summarize the intended compositional gesture.
Because the audio is controlled by time-varying gain envelopes rather than resynthesized motion acoustics, the tool does not generate Doppler shift or propagation-delay cues.

Practical uses

The tool is well suited to experimental panning, physically inspired amplitude envelopes, rhythmic bounce structures, pedagogical demonstrations of restitution and ballistic motion, and sound-design gestures in which a simple physical model serves as a compositional controller.