ShepardToneGenerator

Overview

Generates a continuously ascending or descending Shepard tone using multiple octave-spaced oscillators with envelope shaping.

Discussion

The Shepard Tone Generator module creates the auditory illusion of a tone that continually ascends or descends in pitch, yet effectively remains constant. Often described as a "sonic barber pole", this effect is achieved by superimposing multiple sine waves separated by octaves and moving them in parallel while applying a spectral envelope.

This specific implementation offers advanced polyphony, allowing the generation of multiple distinct Shepard tones simultaneously (each with its own center frequency) and supporting customizable waveforms beyond standard sine waves.

The module operates by generating a bank of oscillators for each defined tone. These oscillators are spaced exactly one octave apart. As the base frequency rises (or falls), the oscillators move up the frequency spectrum.

To maintain the illusion of continuity a Gaussian (bell-shaped) envelope is applied across the frequency range. Tones fade in from silence at the bottom of the spectrum, reach maximum amplitude at the center frequency, and fade out at the top.

The module provides flexibility in shaping the illusion through several key parameters:

Polyphony: Supports multiple simultaneous Shepard tones. The center frequencies for these tones are provided via the second input pin.

Layer Density: The depth of the illusion is configurable via the numOctaves argument (typically 4-8 layers), balancing effect smoothness against CPU usage.

Envelope Control: The envelopeWidth parameter defines the spectral window. A wider envelope creates a smoother, more ambiguous pitch, while a narrower envelope creates a more distinct, resolving tone.

Direction & Speed: The rate of pitch change is controlled dynamically in octaves per second. Positive values create an ascending scale; negative values create a descending scale.

Timbre Selection: While the classic Shepard tone uses sine waves, this module supports Triangle, Sawtooth, and Square waveforms for richer harmonic content.

The module output behavior changes based on the monoDownmix argument:

Multi-Channel Mode (monoDownmix = 0): The output pin will have the same number of channels as the centerFreq input pin. Each channel contains the Shepard tone generated for that specific center frequency.

Mono Sum Mode (monoDownmix = 1): All generated tones are summed together into a single mono output channel.

Module Pack

awe-mod-dspc-snd

ClassID

classID = 41841

Type Definition

typedef struct _ModuleShepardToneGenerator
{
ModuleInstanceDescriptor instance;            // Common Audio Weaver module instance structure
INT32 waveForm;                               // Type of wave form to be generated
FLOAT32 amplitude;                            // Amplitude in linear units.
INT32 envelope;                               // Envelope curve type (0=Bell, 1=Custom)
FLOAT32 envelopeWidth;                        // Gaussian envelope for amplitude control (width in octaves)
INT32 smoothingTime;                          // Time constant of the pitch smoothing process
INT32 numOctaves;                             // Number of octave layers to generate per tone
INT32 blockSize;                              // Block size
FLOAT32 sampleRate;                           // Sample rate
INT32 oscTableSize;                           // Wave table size in samples
INT32 envTableSize;                           // Envelope table size in samples
INT32 monoDownmix;                            // All generated tones are summed together into a single mono output channel.
INT32 numTones;                               // Number of tones to generate (multiple center frequencies)
FLOAT32 smoothingCoeff;                       // Smoothing coefficient (pitch & phase)
FLOAT32 scaleFRatio;                          // Scale factor for playback rate
FLOAT32 minX;                                 // X value corresponding to the first table entry.
FLOAT32 maxX;                                 // X value corresponding to the last table entry.
FLOAT32 globalPhase;                          // Instantanteous phase and also starting phase.
FLOAT32 numOctavesInv;                        // Inverse value of numOctaves
INT32 stateHeap;                              // Heap in which to allocate memory
INT32 NCOFracBits;                            // Number of least-significant bits for the *fractional* part of the NCO word (word size: 32)
INT32 NCOIntBits;                             // Number of most-significant bits for the *integer* part of the NCO word (word size: 32). By default: 16 bits
FLOAT32 formatF;                              // Integer value of left-shift by NCOFracBits. Determines the precision of the linear interpolation.
FLOAT32 formatI;                              // Integer value of left-shift by NCOIntBits. Determines the maximum playback rate and the maximum size of a wave file in samples.
INT32 oscTableSizeF;                          // Wave table size in samples (16.16 format)
FLOAT32 divisor;                              // Precomputed constant = (L-1)/(maxX-minX) to eliminate division on the target.
FLOAT32 sampleRateInv;                        // Precomputed 1/sampleRate to avoid division in real-time
INT32 firstFrame;                             // Detect first frame to set the current FRatio to target ratio right away
INT32 updateActive;                           // Specifies whether the table is updating (=1) or fixed (=0)
FLOAT32* oscTable;                            // Wave sample buffer table
FLOAT32* envTable;                            // Envelope sample buffer table
INT32* phaseOffset;                           // Phase offset per oscillator
INT32* fIndex;                                // Current sample index in the wave table
FLOAT32* currentFRatio;                       // Current (smoothed) rate at which audio is read from the input buffer
INT32* oscTablePkd;                           // Packed 16 bit sample buffer table
} ModuleShepardToneGeneratorClass;

Variables

Properties

Name	Type	Usage	isHidden	Default Value	Range	Units
waveForm	int	parameter	0	0	0:4
amplitude	float	parameter	0	1	0:2	linear
envelope	int	parameter	0	0	0:1
envelopeWidth	float	parameter	0	2	2:2	octaves
smoothingTime	int	parameter	0	10	0:1000	msec
numOctaves	int	const	0	2	Unrestricted
blockSize	int	const	0	48	Unrestricted
sampleRate	float	const	0	48000	Unrestricted
oscTableSize	int	const	0	256	Unrestricted
envTableSize	int	const	0	32	Unrestricted
monoDownmix	int	const	0	0	0:1:1
numTones	int	derived	0	1	Unrestricted
smoothingCoeff	float	derived	0	0.09516	Unrestricted
scaleFRatio	float	derived	0	0.005333	Unrestricted
minX	float	derived	0	-1	Unrestricted
maxX	float	derived	0	1	Unrestricted
globalPhase	float	state	0	0	Unrestricted	radians
numOctavesInv	float	const	1	0.5	Unrestricted
stateHeap	int	const	1	561	Unrestricted
NCOFracBits	int	const	1	16	Unrestricted
NCOIntBits	int	const	1	16	Unrestricted
formatF	float	const	1	65540	Unrestricted
formatI	float	const	1	32770	Unrestricted
oscTableSizeF	int	const	1	16777216	Unrestricted
divisor	float	derived	1	15.5	Unrestricted
sampleRateInv	float	derived	1	2.083e-05	Unrestricted
firstFrame	int	state	1	1	Unrestricted
updateActive	int	state	1	0	0:1
oscTable	float*	parameter	0	[256 x 1]	Unrestricted
envTable	float*	parameter	0	[32 x 1]	Unrestricted
phaseOffset	int*	parameter	0	[2 x 1]	0:359
fIndex	int*	state	1	[2 x 1]	Unrestricted
currentFRatio	float*	state	1	[2 x 1]	Unrestricted
oscTablePkd	int*	state	1	[129 x 1]	Unrestricted

Pins

Input Pins

Name	speed
Description	Control Speed
Data type	float
Channel range	1
Block size range	1
Sample rate range	Unrestricted
Complex support	Real

Name	centerFreq
Description	Center Frequencies (Hz)
Data type	float
Channel range	Unrestricted
Block size range	1
Sample rate range	Unrestricted
Complex support	Real

Output Pins

Name	out
Description	Output audio data
Data Type	float

Scratch Pins

Channel Count	1
Block size	48
Sample rate	48000

Matlab Usage

File Name: shepard_tone_generator_module.m 
 M = shepard_tone_generator_module(NAME, NUMOCT, BLOCKSIZE, SR, OSCTABLESIZE, ENVTABLESIZE, MONODOWNMIX, MEMHEAP) 
 Generates a continuously ascending or descending Shepard tone using multiple octave-spaced oscillators with envelope shaping. 

 Arguments: 
    NAME           - name of the module. 
    NUMOCT         - number of octave layers to generate. 
    BLOCKSIZE      - number of samples per output channel.   
    SR             - sample rate of the output signal, in Hz.   
    OSCTABLESIZE   - number of samples in wave table. By default, OSCTABLESIZE = 256. 
    ENVTABLESIZE   - number of samples in envelope table. By default, ENVTABLESIZE = 32; 
    MONODOWNMIX    - all generated tones are summed together into a single mono output channel. 
    MEMHEAP        - specifies the memory heap to use to allocate the main 
                     state buffer. This is a string and follows the memory allocation 
                     enumeration in Framework.h. Allowable values are: 
                     'AWE_HEAP_FAST' - always use internal DM memory. 
                     'AWE_HEAP_FASTB' - always use internal PM memory. 
                     'AWE_HEAP_SLOW' - always use external memory. 
                     'AWE_HEAP_FAST2SLOW' - use internal memory. If this fails 
                     then use external memory (the default). 
                     'AWE_HEAP_FASTB2SLOW' - use internal memory. If this fails 
                     then use external memory. 

 Copyright 2026.  DSP Concepts, Inc.  All Rights Reserved. 

 AudioWeaverModule [This tag makes it appear under awe_help] 

Copyright (c) 2026 DSP Concepts, Inc.