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.
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.
The exact mapping law
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
- Select exactly one mono or stereo Sound.
- Run
Spectral_swirl_effect.praat. - Start with Gentle Wobble or Liquid Metal.
- Increase Maximum_shift_hz for deeper spectral displacement.
- Increase number_of_cycles for denser alternating regions of compression and expansion.
- 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.
| Preset | Cycles | Max shift | Character |
|---|---|---|---|
| Custom | User | User | No override. |
| Gentle Wobble | 2 | 10 Hz | Shallow broad warp. |
| Liquid Metal | 6 | 25 Hz | Denser metallic remapping. |
| Alien Voice | 8 | 50 Hz | Strong formant/spectral deformation. |
| Underwater Warble | 3 | 20 Hz | Moderate broad warp. |
| Extreme Mangle | 12 | 100 Hz | Dense non-monotonic folding is likely. |
Controls
| Control | Default | Meaning |
|---|---|---|
| number_of_cycles | 4 | Number of sinusoidal deviations across the FFT-bin index range. |
| Maximum_shift_hz | 35 Hz | Requested maximum frequency-axis displacement, converted to an equivalent bin offset and quantized by FFT resolution. |
| wet_dry_percent | 100% | Dry/wet blend, clamped to 0…100. |
| stereo_output | On | Preserves 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_ms | 12 ms | Literal right-channel sample delay used only for mono-input wet widening. |
| scale_peak | 0.95 | When Wet > 0, final mix is target-normalized to this peak before the final fade. |
| Fade_out_ms | 50 ms | Total final fade region. Implemented as a raised-cosine ramp plus the final silence hold. |
| End_silence_ms | 5 ms | True digital silence held at the very end, inside the requested fade region. |
| draw_visualization | On | Draws the exact mapping ledger and measured source/wet/final QC. |
| play_after_processing | On | Plays the final output. |
Processing pipeline
- Prepare one source channel, or two independent channels when stereo is preserved.
- Build a reference Spectrum and an exact Matrix ledger containing the source-bin index for every output bin.
- Copy complex Spectrum bins according to that ledger. Stereo channels use the same mapping law.
- Inverse-transform and trim to the original duration.
- 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.
- Mix wet and dry.
- If Wet > 0, target-normalize to
scale_peak. - Finally apply the raised-cosine fade and exact end silence. This final amplitude operation happens after normalization.
Channels, bypass, duration and level
- Input: mono or stereo only.
- Stereo output + stereo source: original left/right structure is preserved; both channels use the same spectral map.
- Stereo output + mono source: dry is duplicated to both channels; only the wet right channel receives the requested sample delay.
- Mono output + stereo source: source is converted to mono before both dry and spectral processing.
- Duration: unchanged.
- Randomness: none.
- Wet = 0: no peak normalization is applied, but the final fade/end-silence stage still runs. Channel format also follows
stereo_output. Therefore Wet = 0 is not a bit-faithful bypass. - Output name:
<source>_swirl_<preset>.
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.