DBAP with Movement Control — User Guide

Distance-Based Amplitude Panning for 2–8 output channels, with eleven 2D trajectories, tempo-independent path control, smooth AmplitudeTier rendering, optional listener-distance depth, explicit 5.1/7.1 LFE handling, channel-order control, monitoring, and visual diagnostics.

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

Contents:

What this does DBAP theory 11 trajectories Speaker layouts Quick start Parameters Monitoring & output Visualisation

What this does

DBAP with Movement Control moves one selected Sound through a virtual two-dimensional loudspeaker map. At each control point, the script calculates the source position, measures its distance from every directional speaker, converts those distances to DBAP gains, optionally normalises the directional gain set, and writes the resulting curves into AmplitudeTiers.

Source Sound
→ convert working copy to mono and reset time origin to 0
→ generate 2D source trajectory
→ measure blurred distance to each directional speaker
→ compute 1 / d^a gains
→ optional unit-power normalisation
→ optional listener-distance attenuation
→ AmplitudeTier interpolation over the whole source
→ directional channels + optional derived LFE
→ channel ordering + multichannel output
→ optional stereo monitoring preview + visualisation

Smooth movement, not chunked movement: the current implementation does not cut the source into constant-gain chunks. Gain values are written to AmplitudeTiers and applied to the complete source, so movement interpolates continuously between control points.

Radius is a geometric limit, not a generic scale factor. For non-linear trajectories, Radius defines the greatest allowed distance from the map centre. The Square and Zigzag are constructed with half-side R/√2, so their corners land exactly at Radius without being bent by the safety clamp. The Linear trajectory ignores Radius and uses its explicit endpoints.

DBAP theory

Distance and raw gain

dᵢ = sqrt((x - xᵢ)² + (y - yᵢ)² + b²)
gᵢ = 1 / dᵢᵃ

(x,y) is the moving source position, (xᵢ,yᵢ) is speaker i, a is the distance exponent, and b is the spatial-blur term.

Spatial blur: rather than clamping distance to a hard minimum, the script uses d' = sqrt(d² + b²). This keeps the gain smooth when a trajectory passes directly through a speaker position and bounds the maximum raw gain at 1 / bᵃ.

Exponent units

The distance law can be entered either as the exponent a in 1/dᵃ or as dB per doubling of distance. Internally, dB-per-doubling is converted to an exponent.

a = R / (20 × log10(2))
20 × log10(2) ≈ 6.0206 dB

Normalised and unnormalised DBAP

With Normalize_gains enabled, the directional gains are normalised so that their squared sum is 1 before any optional listener-distance term:

gᵢ,norm = gᵢ / sqrt(Σ gᵢ²)
Σ gᵢ,norm² = 1

Normalisation controls distribution, not depth. Unit-power DBAP keeps the total directional energy constant even when the virtual source moves farther from the centre. If a depth cue is desired, enable Listener_distance_attenuation.

Optional listener-distance attenuation

distanceGain = d₀ / max(ρ, d₀)

ρ is the source distance from the map centre and d₀ is Reference_distance. The coordinates are abstract map units, not metres. If the path never exceeds the reference distance, this extra attenuation is intentionally inactive.

11 trajectories

Path_rate does not mean exactly the same thing for every trajectory. The script reports the relevant interpretation for the selected path.

1. Linear

One traversal between the explicit start and end coordinates. Path_rate is not used.

2. Circular

Full circular laps at the specified Radius. Path_rate = number of laps.

3. Figure-8

Gerono lemniscate: x = R sin(φ), y = 0.5R sin(2φ). Path_rate = full figure-8s.

4. Spiral In

Radius decreases from R to 0 during one radial pass. Path_rate = angular turns.

5. Spiral Out

Radius grows from 0 to R during one radial pass. Path_rate = angular turns.

6. Pendulum

One complete swing out and back per path cycle.

7. Zigzag

Straight-sided zigzag built within the Radius boundary. Path_rate controls x crossings while y rises once over the file.

8. Quasi-random Lissajous

Deterministic 2.75:1.947 Lissajous-like path. It is not random and has no single repeat period.

9. Ellipse

Elliptical laps with half-height vertical radius.

10. Square

Straight square circuit with half-side R/√2, placing the corners exactly at Radius.

11. Random walk

Seeded or unpredictable walk with momentum and boundary reflection. Path_rate controls waypoint density rather than cycles.

Random seed: a positive seed makes the Random walk reproducible. Seed 0 produces an unpredictable run. Negative values are treated as 0.

Speaker layouts

The script provides eight predefined 2D layouts. The directional speakers participate in the DBAP calculation; in 5.1 and 7.1 the LFE is handled separately.

Preset	Directional channels	LFE	Notes
Stereo	2	No	L, R
Triangle	3	No	BL, BR, F
Quad	4	No	Internal order: R, F, L, B
Pentagon	5	No	Five equally spaced positions
Hexagon	6	No	Six equally spaced positions
Surround 5.1	5	Yes	FL, FR, C, SL, SR + derived LFE
Surround 7.1	7	Yes	FL, FR, C, SL, SR, BL, BR + derived LFE
Octagon	8	No	Eight equally spaced positions

The LFE is not a spatial speaker. In the 5.1 and 7.1 presets it is a low-passed copy of the mono source at its own level. It is excluded from DBAP distance calculations and from directional gain normalisation, but it receives the same final global output gain as the main channels.

Channel order matters when exporting. For 5.1 and 7.1, Channel_order can keep the AudioTools internal layout with LFE last, or emit the standard WAV ordering FL FR C LFE SL SR [BL BR].

Quick start

In Praat, select exactly one Sound object.
Run script… → DBAP_with_Movement_Control.praat.
Choose one of the eleven Movement_type options.
For Linear, edit the four values in Linear_path. For the other paths, set Radius and Path_rate.
Choose the Speaker_preset. For 5.1/7.1, choose the desired Channel_order and edit the LFE low-pass/level values if necessary.
Set the DBAP exponent, spatial blur, normalisation, and optional listener-distance attenuation.
Choose Output_gain_handling and the desired Monitoring mode.
Leave Draw_visualization enabled if you want the diagnostic plot, then click OK.

Parameters

Name (GUI)	Type	Default	Description
Movement_type	option menu	Circular	Selects one of 11 movement trajectories.
Linear_path	sentence	`start_x=-1.0 start_y=0.0 end_x=1.0 end_y=0.0`	Explicit endpoints for the Linear trajectory. Keep the key names and edit only the numbers.
Radius	real	0.8	Maximum map radius for non-linear paths. Negative values are clamped to 0; Radius 0 gives a fixed source at the centre.
Channel_order	option menu	AudioTools internal	For 5.1/7.1, choose LFE-last internal ordering or standard WAV ordering with LFE fourth.
Path_rate	positive	1.0	Path-rate parameter whose meaning depends on the selected trajectory.
Random_seed	integer	0	Positive = reproducible Random walk; 0 = unpredictable.
Speaker_preset	option menu	Octagon (8)	Selects one of eight speaker layouts.
Lfe	sentence	`lowpass=100 level=0.4`	Low-pass cutoff and level for the derived LFE in 5.1/7.1. Cutoff is restricted below Nyquist and level is limited to 0–1.
Exponent_units	option menu	Distance exponent	Interpret Distance_exponent either as exponent `a` or as dB per doubling.
Distance_exponent	positive	1.0	Controls how rapidly raw DBAP gain falls with distance.
Spatial_blur	positive	0.10	Smooth distance regularisation `sqrt(d²+b²)`; minimum effective value is 0.001.
Reference_distance	positive	1.0	Reference radius for optional listener-distance attenuation.
Normalize_gains	boolean	1	Unit-power normalisation of the directional DBAP gain set before optional depth attenuation.
Listener_distance_attenuation	boolean	0	Adds a centre-distance gain term `d0/max(ρ,d0)`.
Control_time_step	positive	0.02 s	Requested maximum control step. The script raises the control rate when necessary to track fast trajectory components.
Output_gain_handling	option menu	Peak	Peak to target, attenuate only, or no global output scaling.
Peak_target	real	0.95	Target absolute peak for the first two gain-handling modes. Invalid values fall back to 0.95.
Monitoring	option menu	Stereo preview	Play the multichannel result directly, create/play a stereo preview folded by speaker x-position, or perform no playback.
Draw_visualization	boolean	1	Draws the spatial map and diagnostics after processing.

Adaptive control rate: the requested Control_time_step sets a minimum requested rate, but the script also targets 48 points per cycle of the fastest internal trajectory component. The control rate is capped at 4000 Hz and 200,000 points.

Monitoring & output

The processed object is named:

[SourceName]_DBAP_[Movement]_[SpeakerConfiguration]

The number of output channels follows the selected layout: 2–8 channels. Stereo input is converted to a mono working source before spatialisation.

Output gain handling

Peak (scale to target) — scales the final result to Peak_target, boosting or attenuating as necessary.
Attenuate only — reduces the result only when its peak exceeds the target.
None — leaves the calculated output level unchanged.

Stereo preview

The stereo preview is only a monitoring aid. Directional channels are folded left/right according to each speaker's x-position with an equal-power law; the LFE, when present, is sent equally to both sides. The multichannel result itself is not altered.

Direct playback of a 6- or 8-channel Sound depends on the connected audio interface and Praat's current playback routing. Use the stereo-preview option when you only need a quick audition.

Visualisation

When enabled, the visualisation is a five-part diagnostic display derived from the same trajectory and gain logic used for the audio.

Spatial map

Speaker positions, map axes, trajectory trace, start point in blue, end point in red, and an explicit LFE marker when applicable.

Directional gain envelopes

Applied DBAP gain curves for every directional speaker, including listener-distance attenuation when enabled and shown before global output gain.

Source spectrogram

Spectrogram of the mono working copy that was actually spatialised, with the display ceiling limited by Nyquist.

Output waveform

Channels 1 and 2 of the final multichannel result, shown as a compact structural reference.

Summary panel

Movement, path rate, radius where applicable, speaker layout, channel order, distance law, blur, normalisation, control rate, output-gain mode, and peak change.