OscillatorNode.setPeriodicWave() — Methode · JavaScript-Referenz

Signatur

OscillatorNode.prototype.setPeriodicWave(wave)

Beschreibung

Mit setPeriodicWave() ersetzt du die eingebauten Wellenformen eines Oszillators ("sine", "square", "sawtooth", "triangle") durch eine selbst definierte. Die Wellenform beschreibst du vorher mit AudioContext.createPeriodicWave() oder dem Konstruktor new PeriodicWave(). Dafür gibst du Fourier-Koeffizienten an: zwei Arrays mit Kosinus-Anteilen (real) und Sinus-Anteilen (imag) für die Grundfrequenz und ihre Obertöne.

Nach dem Aufruf hat die Eigenschaft type des Oszillators automatisch den Wert "custom". Die Frequenz wird weiter über frequency und detune gesteuert. Die PeriodicWave legt nur die Klangfarbe fest, also die Verteilung der Obertöne, nicht die Tonhöhe.

Typische Einsatzfälle sind Synthesizer mit eigenen Klangfarben, das Nachbilden von Orgelregistern über additive Synthese oder Wavetables, die per Web Audio gemessen oder berechnet wurden. Du kannst die Methode auch aufrufen, während der Oszillator schon läuft. Der Klang wechselt dann sofort.

Parameter

Name	Typ	Default	Beschreibung
$wave Pflicht	PeriodicWave		Die Wellenform, die der Oszillator erzeugen soll. Du erstellst sie mit `audioCtx.createPeriodicWave(real, imag)` oder mit `new PeriodicWave(ctx, { real, imag })`.

Rückgabewert

Typ

undefined

Beschreibung

Die Methode hat keinen Rückgabewert. Als Nebeneffekt wird oscillator.type auf "custom" gesetzt.

Beispiele

Eigene Wellenform aus Obertönen

const ctx = new AudioContext();

// Index 0 = Gleichanteil (wird ignoriert), 1 = Grundton, 2.. = Obertöne
const real = new Float32Array([0, 0, 0, 0, 0]);
const imag = new Float32Array([0, 1, 0.5, 0.25, 0.125]);

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

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

console.log(osc.type);
osc.start();
osc.stop(ctx.currentTime + 1);

custom

Orgelklang per Knopfdruck (Autoplay-Richtlinie beachten)

const button = document.querySelector('#play');

button.addEventListener('click', async () => {
  const ctx = new AudioContext();
  await ctx.resume();

  // Zugriegel-Orgel: Grundton + Oktave + Quinte darüber
  const imag = new Float32Array([0, 1, 0.8, 0.6, 0.3]);
  const real = new Float32Array(imag.length);
  const organ = new PeriodicWave(ctx, { real, imag });

  const osc = new OscillatorNode(ctx, { frequency: 261.63 });
  osc.setPeriodicWave(organ);

  const gain = new GainNode(ctx, { gain: 0.2 });
  osc.connect(gain).connect(ctx.destination);
  osc.start();
  osc.stop(ctx.currentTime + 2);
});

Wellenform während der Wiedergabe wechseln

const ctx = new AudioContext();
const makeWave = (harmonics) => {
  const imag = new Float32Array([0, ...harmonics]);
  return ctx.createPeriodicWave(new Float32Array(imag.length), imag);
};

const soft = makeWave([1, 0.1]);
const bright = makeWave([1, 0.7, 0.5, 0.4, 0.3, 0.2]);

const osc = ctx.createOscillator();
osc.setPeriodicWave(soft);
osc.connect(ctx.destination);
osc.start();

// Nach 1 Sekunde auf eine hellere Klangfarbe umschalten
setTimeout(() => osc.setPeriodicWave(bright), 1000);
setTimeout(() => osc.stop(), 2000);

// Wichtig · Fallstricke

Nicht über type einschalten: Wenn du osc.type = "custom" direkt setzt, wirft der Browser einen InvalidStateError. Eine eigene Wellenform aktivierst du nur mit setPeriodicWave() oder mit der Option periodicWave im Konstruktor OscillatorNode.
Umgekehrt: Wenn du type später auf eine eingebaute Form setzt (z. B. "sine"), wird die eigene Wellenform verworfen.
real und imag müssen gleich lang sein und mindestens 2 Einträge haben, sonst gibt es einen IndexSizeError. Der Wert an Index 0 (Gleichanteil) wird ignoriert.
Die Wellenform wird standardmäßig normalisiert. Mit { disableNormalization: true } in createPeriodicWave() bleiben die absoluten Amplituden erhalten. Achte dann auf die Lautstärke, sonst kann das Signal übersteuern.
Autoplay-Richtlinien: Ein AudioContext startet oft im Zustand "suspended". Er lässt sich erst nach einer Nutzeraktion mit resume() starten.
Kompatibilität: Die Methode wird in allen modernen Browsern unterstützt. Sehr alte WebKit-Versionen brauchten das Präfix webkitAudioContext.

Siehe auch

new PeriodicWave() BaseAudioContext.createPeriodicWave() Navigator.getUserMedia() PannerNode.setPosition() DataTransfer.setDragImage()