BaseAudioContext: createPeriodicWave() method

Baseline Widely available

This feature is well established and works across many devices and browser versions. It’s been available across browsers since ⁨April 2021⁩.

ThecreatePeriodicWave() method of theBaseAudioContext interface is used to create aPeriodicWave. This wave is used to define a periodic waveform that can be used to shape the output of anOscillatorNode.

Syntax

createPeriodicWave(real, imag)createPeriodicWave(real, imag, constraints)

Parameters

real: An array of cosine terms (traditionally the A terms).
imag: An array of sine terms (traditionally the B terms).

Thereal andimag arrays must have the same length, otherwise an error is thrown.

constraintsOptional

A dictionary object that specifies whether normalization should be disabled. If not specified, normalization is enabled by default. It takes one property:

disableNormalization: If set totrue, normalization is disabled for the periodic wave. The default isfalse.

Note:If normalized, the resulting wave will have a maximum absolute peak value of 1.

Return value

APeriodicWave.

Examples

The following example illustrates simple usage ofcreatePeriodicWave(), tocreate aPeriodicWave object containing a simple sine wave.

const real = new Float32Array(2);const imag = new Float32Array(2);const ac = new AudioContext();const osc = ac.createOscillator();real[0] = 0;imag[0] = 0;real[1] = 1;imag[1] = 0;const wave = ac.createPeriodicWave(real, imag, { disableNormalization: true });osc.setPeriodicWave(wave);osc.connect(ac.destination);osc.start();osc.stop(2);

This works because a sound that contains only a fundamental tone is by definition a sine wave.

Here, we create aPeriodicWave with two values. The first value is the DC offset, which is the value at which the oscillator starts. A value of0 is good here because it starts the curve at the middle of the[-1.0; 1.0] range. The second and subsequent values are sine and cosine components, similar to the result of a Fourier transform, which converts time domain values to frequency domain values. Here, withcreatePeriodicWave(), you specify the frequencies, and the browser performs an inverse Fourier transform to get a time domain buffer for the frequency of the oscillator. In this example, we set only one component at full volume (1.0) on the fundamental tone, so we get a sine wave. Bear in mind that the fundamental tone corresponds to the oscillator's frequency (which, by default, is440 Hz). Therefore, altering the oscillator's frequency effectively shifts the frequency of this periodic wave along with it.

The coefficients of the Fourier transform should be given inascending order (i.e., $(a + b i) e^{i}, (c + d i) e^{2 i}, (f + g i) e^{3 i} \left(a+bi\right)e^{i} , \left(c+di\right)e^{2i} ,\left(f+gi\right)e^{3i}$ etc.) and can be positive or negative. A simple way of manually obtaining such coefficients (though not the best) is to use a graphing calculator.