BaseAudioContext.createPeriodicWave() — Methode · JavaScript-Referenz

Signatur

BaseAudioContext.prototype.createPeriodicWave(real, imag, constraints)

Beschreibung

createPeriodicWave() erzeugt ein PeriodicWave-Objekt, also eine eigene periodische Wellenform. Sie wird über zwei Arrays mit Fourier-Koeffizienten beschrieben: real enthält die Kosinus-Anteile, imag die Sinus-Anteile der einzelnen Obertöne (Harmonischen). Index 0 steht für den Gleichanteil (DC-Offset) und wird ignoriert, Index 1 für die Grundfrequenz, Index 2 für den ersten Oberton usw.

Die erzeugte Welle weist du einem OscillatorNode mit oscillator.setPeriodicWave(wave) zu. Der Oszillator spielt die Form dann mit seiner eingestellten frequency ab. So lassen sich Klangfarben jenseits der eingebauten Typen sine, square, sawtooth und triangle bauen, etwa Orgelregister, Wavetable-Synthese oder bandbegrenzte Nachbildungen analoger Wellenformen.

Standardmäßig normalisiert der Browser die Welle, sodass ihr Spitzenwert bei 1 liegt. Mit { disableNormalization: true } bleiben die angegebenen Amplituden unverändert. Das ist wichtig, wenn mehrere Wellen genau gleich laut sein oder absolute Pegel behalten sollen.

Alternativ gibt es den Konstruktor new PeriodicWave(context, { real, imag, disableNormalization }), der das Gleiche leistet und in neuem Code oft lesbarer ist.

Parameter

Name	Typ	Default	Beschreibung
$real Pflicht	Float32Array \| number[]		Kosinus-Koeffizienten der Fourier-Reihe. `real[0]` (Gleichanteil) wird ignoriert.
$imag Pflicht	Float32Array \| number[]		Sinus-Koeffizienten der Fourier-Reihe. Muss genauso lang sein wie `real`. `imag[0]` wird ignoriert.
$constraints	{ disableNormalization?: boolean }	{ disableNormalization: false }	Optionen. Bei `disableNormalization: true` wird die Welle nicht auf den Spitzenwert 1 normalisiert.

Rückgabewert

Typ

PeriodicWave

Beschreibung

Ein neues PeriodicWave-Objekt, das du mit OscillatorNode.setPeriodicWave() zuweisen kannst.

Beispiele

Einfache eigene Wellenform (Grundton + Oberton)

const ctx = new AudioContext();

// Index 0 = Gleichanteil (ignoriert), 1 = Grundton, 2 = erster Oberton
const real = new Float32Array([0, 0, 0]);
const imag = new Float32Array([0, 1, 0.5]);

const wave = ctx.createPeriodicWave(real, imag);

const osc = ctx.createOscillator();
osc.setPeriodicWave(wave);
osc.frequency.value = 220;
osc.connect(ctx.destination);

// Browser starten Audio nur nach einer Nutzeraktion
document.querySelector('#play').addEventListener('click', async () => {
  await ctx.resume();
  osc.start();
  osc.stop(ctx.currentTime + 1);
});

Bandbegrenzte Sägezahnwelle aus Harmonischen

const ctx = new AudioContext();
const harmonics = 32;
const real = new Float32Array(harmonics);
const imag = new Float32Array(harmonics);

// Sägezahn: Amplitude der n-ten Harmonischen = 1/n, abwechselndes Vorzeichen
for (let n = 1; n < harmonics; n++) {
  imag[n] = ((n % 2 === 0 ? -1 : 1) * 2) / (Math.PI * n);
}

const saw = ctx.createPeriodicWave(real, imag);
const osc = ctx.createOscillator();
osc.setPeriodicWave(saw);
osc.frequency.value = 110;
osc.connect(ctx.destination);
console.log(saw instanceof PeriodicWave);

true

Orgelklang ohne Normalisierung

const ctx = new AudioContext();

// Zugriegel-Prinzip: Grundton, Oktave, Quinte über der Oktave
const imag = new Float32Array([0, 0.6, 0.3, 0.2, 0.1]);
const real = new Float32Array(imag.length);

const organ = ctx.createPeriodicWave(real, imag, {
  disableNormalization: true
});

const gain = new GainNode(ctx, { gain: 0.5 });
const osc = new OscillatorNode(ctx, { frequency: 261.63 });
osc.setPeriodicWave(organ);
osc.connect(gain).connect(ctx.destination);

const playNote = async (duration = 0.8) => {
  await ctx.resume();
  osc.start();
  osc.stop(ctx.currentTime + duration);
};

// Wichtig · Fallstricke

real und imag müssen gleich lang sein und mindestens 2 Einträge haben. Sonst wird ein IndexSizeError geworfen.
Index 0 (Gleichanteil) wird immer ignoriert. Wer einen Grundton will, muss mindestens Index 1 belegen.
Ohne disableNormalization wird die Welle auf den Spitzenwert 1 normalisiert. Die absoluten Werte der Koeffizienten spielen dann keine Rolle, nur ihr Verhältnis zueinander.
Sehr viele Harmonische kosten Rechenzeit. Der Browser rechnet die Welle bandbegrenzt nach, damit keine Aliasing-Effekte entstehen; Obertöne oberhalb der Nyquist-Frequenz werden also nicht wiedergegeben.
Ein PeriodicWave lässt sich für mehrere Oszillatoren wiederverwenden. Eine neue Welle pro Note zu erzeugen ist unnötig.
Wird ein AudioContext ohne Nutzeraktion erstellt, startet er wegen der Autoplay-Regeln der Browser im Zustand suspended. Deshalb vorher ctx.resume() aufrufen.
Kompatibilität: Die Methode funktioniert in allen modernen Browsern. Ganz alte WebKit-Versionen hatten sie nur mit Präfix (webkitAudioContext) und ohne constraints-Parameter.

Siehe auch

BaseAudioContext.createBufferSource() BaseAudioContext.createConvolver() BaseAudioContext.createDelay() BaseAudioContext.createIIRFilter() BaseAudioContext.createStereoPanner()