Spectral Swirl Effect — User Guide

Whole-sound FFT-bin remapping: a sinusoidal frequency-axis map bends, duplicates and can fold complex spectral bins, with optional wet-only stereo widening.

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

What this does

Spectral Swirl performs a static whole-sound FFT bin remapping. For every output frequency bin, it looks up a source bin whose index is displaced by a sinusoidal function. The same exact mapping ledger is then used to copy both real and imaginary Spectrum components, so each destination bin receives the complete complex value of the selected source bin.

The result is a warped spectrum containing local stretches, compressions, duplicates and, at stronger settings, non-monotonic folds. It is not a time-varying vibrato or frequency shifter: the “swirl” exists along the frequency axis.

What is spectral warping? Spectral warping changes the mapping between input and output frequencies. Here the mapping is performed directly on FFT-bin indices. It is not an all-pass frequency-warping filter and does not estimate partial tracks; it simply asks each output bin which source bin it should read.

The exact mapping law

shiftBins = Maximum_shift_hz / FFT_bin_width sourceBin(c) = round( clamp(1, N, c + shiftBins * sin(2*pi*number_of_cycles*c/N) ) ) outputSpectrum[row,c] = sourceSpectrum[row, sourceBin(c)]

Maximum_shift_hz is converted to bins, then rounded and clamped. The realized shift can therefore differ slightly from the requested number of hertz. At strong settings, adjacent output bins may read the same source bin (duplicates), or the mapping can move backward (reverse steps), creating true spectral folds.

number_of_cycles controls how many sinusoidal deviations occur across the FFT-bin index range. It is a legacy index-domain law, not “cycles per octave” or “cycles per second.”

Quick start

  1. Select exactly one mono or stereo Sound.
  2. Run Spectral_swirl_effect.praat.
  3. Start with Gentle Wobble or Liquid Metal.
  4. Increase Maximum_shift_hz for deeper spectral displacement.
  5. Increase number_of_cycles for denser alternating regions of compression and expansion.
  6. If a mono source should become stereo, leave stereo_output on and set the wet-only right-channel delay with Stereo_delay_ms.

Presets

Presets override only cycle count and maximum shift; Wet/Dry, stereo, fade, target peak and output switches remain user-controlled.

PresetCyclesMax shiftCharacter
CustomUserUserNo override.
Gentle Wobble210 HzShallow broad warp.
Liquid Metal625 HzDenser metallic remapping.
Alien Voice850 HzStrong formant/spectral deformation.
Underwater Warble320 HzModerate broad warp.
Extreme Mangle12100 HzDense non-monotonic folding is likely.

Controls

ControlDefaultMeaning
number_of_cycles4Number of sinusoidal deviations across the FFT-bin index range.
Maximum_shift_hz35 HzRequested maximum frequency-axis displacement, converted to an equivalent bin offset and quantized by FFT resolution.
wet_dry_percent100%Dry/wet blend, clamped to 0…100.
stereo_outputOnPreserves stereo input. For mono input, creates stereo wet output with a delayed right channel. When off, stereo input is converted to mono before processing.
Stereo_delay_ms12 msLiteral right-channel sample delay used only for mono-input wet widening.
scale_peak0.95When Wet > 0, final mix is target-normalized to this peak before the final fade.
Fade_out_ms50 msTotal final fade region. Implemented as a raised-cosine ramp plus the final silence hold.
End_silence_ms5 msTrue digital silence held at the very end, inside the requested fade region.
draw_visualizationOnDraws the exact mapping ledger and measured source/wet/final QC.
play_after_processingOnPlays the final output.

Processing pipeline

  1. Prepare one source channel, or two independent channels when stereo is preserved.
  2. Build a reference Spectrum and an exact Matrix ledger containing the source-bin index for every output bin.
  3. Copy complex Spectrum bins according to that ledger. Stereo channels use the same mapping law.
  4. Inverse-transform and trim to the original duration.
  5. Build the requested output channel layout: preserve stereo; optionally create wet-only Haas-style width for mono; or fold stereo to mono when stereo output is disabled.
  6. Mix wet and dry.
  7. If Wet > 0, target-normalize to scale_peak.
  8. Finally apply the raised-cosine fade and exact end silence. This final amplitude operation happens after normalization.

Channels, bypass, duration and level

Visualization

The script plots and measures the actual mapping ledger used by the DSP. QC values include realized maximum shift, edge-clamped bins, duplicate steps and reverse steps. It also tracks the strongest non-DC source component and identifies the nearest output bin that reads from it, alongside measured wet/final RMS and the realized fade/silence durations.

Technological context

Frequency warping has a long history in signal processing, especially in representations designed to redistribute spectral resolution. This script uses a much more direct compositional version of the idea: it remaps FFT-bin addresses with a sinusoidal index law. Because the mapping can become non-monotonic, the result can move beyond smooth “warping” into spectral folding, duplication and reversal.

That distinction matters musically: the processor does not model a physical Doppler shift, formant trajectory or continuously varying filter. It treats the spectrum itself as a coordinate field that can be bent and folded.