Spectral Panning Mapper — User Guide
Spectral-driven dynamic spatial panning for 2–8 output channels. Spectral flatness controls orbit radius; frame-to-frame spectral flux controls orbit speed; a 2D DBAP stage converts the moving source position into per-channel gain envelopes.
What this does
The script converts the selected Sound to a mono analysis/rendering source, measures two spectral descriptors in the 80–8000 Hz band, and uses them to drive a moving point in a two-dimensional loudspeaker space.
- Spectral flatness controls the orbit radius: higher flatness pushes the source farther from the centre.
- Spectral flux controls angular speed: stronger frame-to-frame spectral change makes the orbit rotate faster.
- DBAP converts the moving source position into one gain per active loudspeaker, with power normalization across those gains.
- The result is a genuine N-channel Sound (2–8 channels), not a stereo fold-down.
v1.1.4 correction: spectral flux is now a true frame-to-frame descriptor. The script compares consecutive L2-normalized magnitude spectra rather than measuring variation between neighbouring frequency bins inside one spectrum. Per-channel DBAP gains are also applied without independent channel normalization, so the spatial gain ratios survive rendering.
Quick start
- Select exactly one Sound in Praat. Minimum duration is 0.3 s.
- Run
Spectral_Panning_Mapper.praat. - Choose a named preset, or use Custom/Custom Multi for the form values and a regular-ring layout.
- For Custom operation, set Num_channels (2–8), the analysis/update controls, orbit controls, DBAP rolloff, and wet/dry mix.
- Keep Draw_visualization enabled if you want the feature/orbit/gain diagnostic.
- Click OK. The result is named
source_SPM_presetand remains selected; it is played if Play_result is enabled.
Preset behaviour: named presets overwrite channel count, speaker positions, radius/speed controls and DBAP rolloff. Analysis_windows, Panning_update_rate_Hz, Mix_percent, visualization and playback remain global form controls.
Spectral features
Spectral flatness (Wiener entropy)
flatness = geometric_mean(power) / arithmetic_mean(power)
power[k] = magnitude[k]^2
analysis band = 80–8000 Hz
output is clamped to [0, 1]
Each analysis frame is extracted with a Hamming window. Flatness approaches 0 when energy is concentrated in relatively few bins and approaches 1 when power is distributed more evenly across the analysed band. The script maps this value to orbit radius.
Frame-to-frame spectral flux
For each frame:
m = magnitude vector in 80–8000 Hz
m_norm = m / ||m||₂
For frames t-1 and t:
flux = sqrt( Σ (m_norm[t,k] - m_norm[t-1,k])² / 2 )
flux is clamped to [0, 1]
first analysis frame = 0
Because each magnitude vector is L2-normalized before comparison, this descriptor primarily reflects spectral-shape change rather than a simple change in overall level. The factor of 2 normalizes the maximum squared distance of non-negative unit vectors to a 0–1 scale.
Analysis timing: the default is 10 analysis windows. The half-window starts at 100 ms, is reduced when necessary relative to file duration/window count, and is never allowed below 20 ms. Feature values measured at those analysis times are linearly interpolated onto the panning update grid.
Orbit & DBAP mapping
Orbit model
Moving source position
orbitRadius = Base_orbit_radius + flatness × Flatness_radius_influence
orbitRadius = min(orbitRadius, 0.95)
orbitSpeed = Base_orbit_speed_Hz + flux × Flux_speed_influence
angle += 2π × orbitSpeed × Δt
srcX = orbitRadius × cos(angle)
srcY = orbitRadius × sin(angle)
Flatness therefore changes how far the source travels from the centre, while flux changes how quickly the angular trajectory advances.
DBAP gain calculation
Distance-based gains
distance_i = sqrt((srcX - speakerX_i)^2 + (srcY - speakerY_i)^2)
distance_i = max(distance_i, 0.01)
rawGain_i = 1 / distance_i ^ Rolloff_exponent
norm = sqrt(Σ rawGain_i²)
gain_i = rawGain_i / norm
The normalization makes Σ gaini² = 1 across the active full-range channels at each control point. This is a gain-law property; it should not be interpreted as a guarantee of constant perceived loudness in an arbitrary room or loudspeaker array.
Gains are stored in IntensityTiers in dB with a numerical floor of −120 dB. They are then multiplied into channel copies with Multiply: "no", explicitly avoiding Praat's per-result rescaling so that the DBAP ratios are preserved.
Presets & speaker layouts
The menu contains 12 named spatial presets plus Custom and Custom Multi. The two Custom choices are functionally equivalent in v1.1.4: both use the form values and create a regular ring with Num_channels speakers.
| Preset | Channels / layout | Radius | Speed | Rolloff |
|---|---|---|---|---|
| Stereo Sweep | 2, L/R at (−1,0)/(+1,0) | 0.50 + flatness×0.50 | 0.50 + flux×3.0 Hz | 1.0 |
| Stereo Drift | 2, L/R | 0.20 + flatness×0.30 | 0.15 + flux×1.0 Hz | 1.0 |
| Triangle Orbit | 3, regular triangle | 0.40 + flatness×0.50 | 0.30 + flux×2.0 Hz | 1.0 |
| Quad Spiral | 4, square rotated 45° | 0.30 + flatness×0.60 | 0.40 + flux×3.0 Hz | 1.0 |
| Quad Corners | 4, square rotated 45° | 0.10 + flatness×0.85 | 0.20 + flux×1.5 Hz | 1.2 |
| Hex Ring | 6, regular hexagon | 0.30 + flatness×0.55 | 0.35 + flux×2.5 Hz | 1.0 |
| Surround 5.1 | 6: L/R ±30°, C 0°, LFE Ch4, surrounds nominally ±110° | 0.00 + flatness×0.60 | 0.30 + flux×2.0 Hz | 1.0 |
| Octagon Orbit | 8, regular ring | 0.35 + flatness×0.55 | 0.30 + flux×2.0 Hz | 1.0 |
| Octagon Front Arc | 8, front semicircle at radius 0.9 | 0.40 + flatness×0.40 | 0.25 + flux×2.5 Hz | 1.0 |
| Diffuse Field | 8, regular ring | 0.05 + flatness×0.90 | 0.10 + flux×0.5 Hz | 0.8 |
| Hyperactive | 4, square rotated 45° | 0.20 + flatness×0.70 | 1.20 + flux×8.0 Hz | 1.0 |
| Slow Evolution | 6, regular hexagon | 0.25 + flatness×0.40 | 0.08 + flux×0.4 Hz | 1.0 |
5.1 LFE policy: Channel 4 is reserved as LFE but remains silent. It is excluded from DBAP power normalization, wet rendering, dry distribution and the heatmap's active-gain calculation. The script deliberately does not invent a crossover or bass-management stage.
Parameters & controls
| Control | Default | Behaviour |
|---|---|---|
| Preset | Stereo Drift | Chooses one of 12 named presets or either Custom entry. |
| Num_channels | 4 | Custom only. Clamped to 2–8 before the regular-ring speaker coordinates are built. |
| Analysis_windows | 10 | Integer number of spectral analysis frames. Must be at least 2; otherwise the script exits. |
| Panning_update_rate_Hz | 100 | Control-grid update rate used for interpolated features, orbit position and gain tiers. |
| Base_orbit_radius | 0.3 | Custom baseline radius; named presets override it. |
| Flatness_radius_influence | 0.6 | Custom scaling from flatness to radius; named presets override it. |
| Base_orbit_speed_Hz | 0.4 | Custom baseline angular speed; named presets override it. |
| Flux_speed_influence | 3.0 | Custom scaling from frame-to-frame flux to angular speed; named presets override it. |
| Rolloff_exponent | 1.0 | Exponent in the inverse-distance DBAP weight; named presets may override it. |
| Mix_percent | 100 | Linear wet/dry mix, clamped to 0–100. |
| Draw_visualization | On | Draws the 6 data panels plus title/subtitle and summary. |
| Play_result | On | Plays the selected multichannel result after processing. |
Processing pipeline
- Input validation: exactly one Sound, duration ≥0.3 s; Custom channels are clamped to 2–8 and analysis windows must be ≥2.
- Mono working source: multichannel input is downmixed to mono; mono input is copied.
- Spectral analysis: Hamming-windowed spectra are measured in 80–8000 Hz. Flatness is calculated from power; flux compares the current normalized magnitude spectrum with the preceding one.
- Interpolation: the sparse feature values are linearly interpolated to the update-rate grid.
- Orbit: interpolated flatness sets radius and interpolated flux sets angular speed.
- DBAP: distance weights are calculated for each active speaker and normalized so their squared gains sum to 1. In the 5.1 preset, LFE is excluded.
- Per-channel render: dB IntensityTiers are applied with no independent result normalization; LFE is explicitly zeroed.
- Multichannel assembly: all rendered channels are combined into one N-channel Sound.
- Wet/dry: when dry is present, the mono working source is distributed equally in power across all active full-range output channels using gain
1/sqrt(Nactive); LFE remains silent. Wet and dry are then mixed linearly. - Final peak scaling: every non-silent result is scaled to a peak of 0.95. This can attenuate or amplify the mix and therefore changes absolute level.
- Output: result is named
source_SPM_preset, selected and optionally played.
Dry is not the original channel image. Because the spatial engine is point-source based and begins from a mono working signal, the dry component is also a centred mono bed distributed across the active output channels. At 0% wet, the output is therefore this multichannel mono bed, followed by the same peak-to-0.95 scaling.
Visualization & analysis
When enabled, v1.1.4 draws six data panels, plus title/subtitle and a compact summary:
- Source waveform — original selected Sound, using a shared display amplitude based on the input peak.
- Spectral features — orange flatness and teal frame-to-frame flux, with vertical markers at the analysis times.
- Speaker layout + orbit — 2D speaker geometry, unit-circle reference, listener, source start point and orbit trace. In 5.1, Ch4 is labelled as reserved/silent rather than drawn as an active speaker.
- Orbit X/Y over time — horizontal components of the moving source position.
- Gain per channel over time — 50-column heatmap recomputed with the same DBAP and LFE-exclusion rules as the audio renderer.
- Output waveform — the final N-channel result after wet/dry mixing and peak scaling.
The summary reports source, preset, channel count, number of analysis windows, orbit mapping values, rolloff, update rate, mix, grid-point count and output name.
Notes & limitations
- 2D model: speaker positions and orbit are two-dimensional. There is no elevation or distance-delay model.
- DBAP here is amplitude panning: speaker distance is a control-space distance used to derive gains; it is not a physical propagation simulation.
- Custom layout: the form exposes channel count, but not arbitrary X/Y coordinates. Both Custom menu entries generate a regular ring. Truly irregular layouts require editing the
spkX[]/spkY[]definitions in the script. - 5.1: the channel order is L, R, C, LFE, Ls, Rs. LFE is intentionally silent because the tool does not implement crossover/bass management.
- Final peak scaling: the unconditional peak-to-0.95 step means preset-to-preset absolute level differences are not preserved.
- Input spatial image: stereo or multichannel sources are downmixed to mono before analysis and spatial rendering.