Harmonic Spray / Partial Panner — User Guide

Spectral spatialisation by band: a selected Sound is reduced to mono, split into logarithmically spaced Hann-pass bands, and each band is distributed by frequency across stereo or an evenly spaced 4/6/8-channel speaker ring.

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

Contents:

What this does Quick start Spatial mapping Presets Parameters Processing pipeline Visualization Limits & interpretation

What this does

Partial Panner creates frequency-dependent spatial distribution. The input is first converted to a mono working source. The script then builds N logarithmically spaced spectral bands, assigns each band a frequency-dependent width, maps that width to a target azimuth, and accumulates the filtered band into the output channels.

Output formats: stereo, quad, 6-channel, or 8-channel.
Band layout: logarithmic centre frequencies between the user minimum and an effective maximum limited to 95% of Nyquist.
Band filtering: Praat Filter (pass Hann band) with bandwidth specified in octaves.
Spectral-to-space mapping: an S-shaped band-order curve multiplied by Pan_width and a frequency-dependent width scale.
Low-frequency width reduction: bands below LF_protection_Hz receive additional width reduction.
Dry/wet: wet multichannel spatialisation can be blended with a dry anchor before final peak normalization.

Input semantics: The script requires exactly one Sound. If that Sound has more than one channel, Praat's Convert to mono is used first. The original stereo or multichannel image is therefore not preserved; the output spatial field is synthesized from the mono working source.

Quick start

Select exactly one Sound in Praat.
Run Partial_Panner.praat.
Choose a preset. The form default is Standard Spread.
For Custom, choose 2, 4, 6, or 8 output channels, then set band count, width, bandwidth, spread arc, frequency range, LF protection, and dry/wet mix.
Run the script. The output is normalized to peak 0.99 and optionally visualized and played.

Output naming: source_spray_PresetName_Nch, for example voice_spray_Standard_2ch or field_spray_Quad360_4ch.

Spatial mapping

1. Spectral bands

Band centre i: f_i = f_min × (f_max / f_min)^((i - 0.5) / N) Effective maximum: f_max = min(Max_frequency_Hz, 0.95 × Nyquist) Bandwidth: multiplier = 2^(Bandwidth_octaves) low_i = f_i / sqrt(multiplier) high_i = f_i × sqrt(multiplier) smoothing = (high_i - low_i) / 6

The centres are logarithmically spaced. The filtered bands can overlap; this is a creative filter-bank reconstruction rather than a guaranteed unity-sum crossover.

2. Band order to effective width

Band-order position: normPos = (i - 1) / (N - 1) [0..1, or 0.5 when N=1] S-shaped mapping: s = tanh(2.5 × (2×normPos - 1)) Frequency scale: q = ln(f_i / f_min) / ln(f_max / f_min) freqScale = 0.3 + 0.7 × q^0.7 Below LF_protection_Hz: lfScale = (f_i / LF_protection_Hz)^2 freqScale *= 0.2 + 0.8 × lfScale Effective width: effectiveWidth = Pan_width × freqScale panNorm = s × effectiveWidth

The low-frequency rule is an explicit mapping choice in this tool: it keeps lower bands closer to the spatial centre than higher bands. It should not be read as a physical or psychoacoustic localization model.

3. Stereo output

For two channels, Spread_arc_degrees is internally forced to 180°. The actual audio gains use classic constant-power stereo panning:

panAngle = ((panNorm + 1) / 2) × pi/2 L = cos(panAngle) R = sin(panAngle)

Within the intended range Pan_width ∈ [-1,1], negative width reverses the low-to-high direction. The code does not clamp Pan_width; values outside this range extrapolate the panning law and can produce negative stereo gains.

4. 4/6/8-channel output

For multichannel output, speakers are placed on an evenly spaced ring beginning at Channel 1 = 0° front, increasing clockwise: 90° is right and 180° is back. The target azimuth is:

azimuth = panNorm × (Spread_arc_degrees / 2) then wrapped to [0°, 360°)

The target is routed only to the two adjacent ring speakers. If the target lies a fraction u between them, the gains are:

gain_low = cos(u × pi/2) gain_high = sin(u × pi/2)

This is adjacent-speaker constant-power interpolation. The implementation does not perform a full geometric VBAP matrix solve.

5. Dry anchor

Output	Dry signal routing
Stereo	The mono working source is copied identically to L and R, producing a centre image.
4/6/8 channel	The mono working source is placed only in Channel 1 (front 0°); all other dry channels are silent.

Dry_wet_mix is a linear amplitude interpolation: wet level = mix, dry level = 1 − mix. The combined result is then normalized to peak 0.99.

Preset configurations

The form contains 9 options including Custom. Presets override channel count, band count, pan width, bandwidth, and spread arc; they do not override LF protection, min/max frequency, dry/wet mix, visualization, or playback.

Preset	Output	Bands	Width	BW (oct)	Arc
Custom	User	User	User	User	User*
Subtle Widening	2ch	6	0.5	0.50	180°
Standard Spread default	2ch	8	0.8	0.50	180°
Extreme Spray	2ch	16	1.0	0.33	180°
Reverse (High→L, Low→R)	2ch	10	-0.9	0.50	180°
Dense Shimmer	2ch	20	0.7	0.33	180°
Coarse Texture	2ch	4	1.0	1.00	180°
Quad Surround (4ch)	4ch	12	1.0	0.50	360°
Octagon Spray (8ch)	8ch	16	1.0	0.33	360°

*In stereo, the arc is always forced to 180°. In 4/6/8-channel Custom mode it is clamped to 10°–360°. There is no dedicated 6-channel preset; choose 6ch in Custom.

Parameters & validation

Parameter	Form default	Enforced behaviour
Preset	Standard Spread	Preset values override the relevant custom fields.
Number_of_channels	2 (stereo)	Options are 2, 4, 6, 8. Non-Custom presets may override it.
Number_of_bands	8	At least 1.
Pan_width	0.8	Not clamped. Intended range is approximately −1…+1; negative reverses the mapping.
Bandwidth_octaves	0.5	Must be > 0 or the script exits.
Spread_arc_degrees	180	Stereo: forced to 180°. Multichannel: clamped to 10°–360°.
LF_protection_Hz	150	Positive form value; below-cutoff bands receive extra width reduction.
Min_frequency_Hz	80	Must remain below the effective maximum after Nyquist limiting.
Max_frequency_Hz	16000	Effective max = min(user max, 0.95 × Nyquist).
Dry_wet_mix	1.0	Clamped to 0…1.
Draw_visualization	yes	Draw the diagnostic figure after processing.
Play_result	yes	Play the resulting object in Praat.

Pan-width extrapolation: Unlike several other parameters, Pan_width is not validated or clamped. Values beyond ±1 are therefore not simply “more width”; in stereo they can push panAngle beyond the normal 0…π/2 panning interval and introduce negative gains.

Processing pipeline

1. Validate exactly one selected Sound. 2. Resolve preset and output channel count. 3. Clamp dry/wet and multichannel arc; force stereo arc to 180°. 4. Limit max frequency to 95% of Nyquist and validate min < max. 5. Convert the selected Sound to mono when needed. 6. Compute logarithmic band centres and octave-based pass bands. 7. For each band: a. compute S-shaped spectral position; b. apply frequency-dependent width and LF reduction; c. map to stereo pan or multichannel azimuth; d. Hann-band filter the mono source; e. add the filtered band to its destination channel(s). 8. Build the dry anchor if Dry_wet_mix < 1. 9. Mix wet and dry linearly. 10. Apply Scale peak: 0.99. 11. Draw the optional visualization and optionally play the result.

Normalization: Scale peak: 0.99 is unconditional. It is not a limiter or attenuation-only ceiling: it can also increase the level of a quiet result. Consequently, absolute level differences caused by dry/wet balance or filtering are not preserved at the final object peak.

Visualization

When enabled, v0.4.2 draws an 8-wide diagnostic figure:

Speaker / band layout: stereo uses a frequency-vs-pan plot; 4/6/8-channel output uses a ring diagram with numbered speakers and band markers at their target azimuths. In the ring plot, marker radius is a visual frequency cue, not an audio distance parameter.
Gain matrix: bands by output channel. Brighter cells indicate larger non-zero band gain.
Effective width: v0.4.2 plots the actual Pan_width × freqScale curve. Reverse presets therefore appear below zero, and smaller width settings no longer appear as full-scale width.
Output waveform: Channel 1 in blue and Channel 2 in orange. For 4/6/8-channel results, channels 3+ are not drawn in this waveform panel.
Summary: preset, source, channel count, bands, width, arc, bandwidth, frequency range, LF protection, dry/wet percentage, duration, and final peak.

Interpretation: The visualization reports the mapping and gains used by the script. It is not a room simulation, loudspeaker-response model, HRTF display, or prediction of perceived source location.

Limits & interpretation

Not a physical spatial model: no room acoustics, propagation delay, HRTF, head shadow, or loudspeaker calibration is modeled.
Not true partial tracking: “Partial” refers to filtered spectral regions; the script does not estimate sinusoidal partial trajectories or harmonic identities.
Input collapsed to mono: any pre-existing stereo/multichannel spatial information is removed before processing.
Filter-bank reconstruction is not unity-sum: overlapping Hann pass bands can change spectral balance; regions outside the combined pass bands may be attenuated.
LF protection reduces width only: it does not guarantee mono compatibility or prevent every possible coloration when channels are summed.
Multichannel panning is adjacent-speaker interpolation: it is not a full VBAP, ambisonic, or binaural encoder.
Final normalization changes absolute gain: audition the resulting balance rather than interpreting the output peak as a measure of processing level.

Practical uses

The tool is suited to experimental spectral distribution, mono-to-stereo texture creation, and preparation of frequency-dependent multichannel material. For mastering or archival work, use conservative settings and verify the result against the unprocessed source, because the filter bank and final normalization can alter timbre and level.