new WaveShaperNode() — Methode · JavaScript-Referenz

Signatur

new WaveShaperNode(context, options)

Beschreibung

Der Konstruktor WaveShaperNode() erzeugt einen Audioknoten, der jeden Abtastwert des Eingangssignals über eine Übertragungskurve abbildet. Damit lassen sich Effekte wie Übersteuerung, Verzerrung (Distortion), Fuzz, Sättigung oder weiches Begrenzen (Soft-Clipping) umsetzen.

Die Kurve ist ein Float32Array. Der Eingangswertebereich von -1 bis +1 wird gleichmäßig auf die Array-Indizes verteilt. Liegt ein Eingangswert zwischen zwei Stützstellen, wird linear interpoliert. Mit der Option oversample ('none', '2x', '4x') lassen sich Aliasing-Artefakte verringern, die durch die nichtlineare Verarbeitung entstehen.

Der Konstruktor ist eine Alternative zur Fabrikmethode BaseAudioContext.createWaveShaper(). Sein Vorteil: Kurve, Oversampling und Kanaloptionen lassen sich direkt beim Anlegen übergeben. Der Knoten hat einen Eingang und einen Ausgang und wird wie jeder AudioNode mit connect() in den Audiographen eingebunden.

Parameter

Name	Typ	Default	Beschreibung
$context Pflicht	BaseAudioContext		Der `AudioContext` oder `OfflineAudioContext`, zu dem der Knoten gehören soll.
$options	object	{}	Optionales Objekt mit Anfangswerten. Möglich sind: `curve` (`Float32Array \| number[]`, Standard `null`): Verzerrungskurve mit mindestens 2 Werten. `oversample` (`'none' \| '2x' \| '4x'`, Standard `'none'`): Stufe der Überabtastung. `channelCount`, `channelCountMode`, `channelInterpretation`: allgemeine `AudioNode`-Kanaloptionen.

Rückgabewert

Typ

WaveShaperNode

Beschreibung

Ein neues WaveShaperNode-Objekt, das an den angegebenen Kontext gebunden ist.

Beispiele

Einfacher Verzerrer mit Kurve und Oversampling

const ctx = new AudioContext();

// Klassische Distortion-Kurve erzeugen
const makeDistortionCurve = (amount = 50, samples = 44100) => {
  const curve = new Float32Array(samples);
  const deg = Math.PI / 180;
  for (let i = 0; i < samples; i++) {
    const x = (i * 2) / samples - 1;
    curve[i] = ((3 + amount) * x * 20 * deg) / (Math.PI + amount * Math.abs(x));
  }
  return curve;
};

const shaper = new WaveShaperNode(ctx, {
  curve: makeDistortionCurve(400),
  oversample: '4x'
});

const osc = new OscillatorNode(ctx, { type: 'sine', frequency: 220 });
osc.connect(shaper).connect(ctx.destination);
osc.start();
osc.stop(ctx.currentTime + 2);

console.log(shaper.oversample, shaper.curve.length);

4x 44100

Soft-Clipping mit tanh für eine Gitarre am Mikrofon

const ctx = new AudioContext();

const tanhCurve = (drive = 5, n = 2048) =>
  Float32Array.from({ length: n }, (_, i) => {
    const x = (i / (n - 1)) * 2 - 1;
    return Math.tanh(drive * x) / Math.tanh(drive);
  });

const start = async () => {
  await ctx.resume();
  const stream = await navigator.mediaDevices.getUserMedia({ audio: true });
  const input = new MediaStreamAudioSourceNode(ctx, { mediaStream: stream });
  const shaper = new WaveShaperNode(ctx, { curve: tanhCurve(8), oversample: '2x' });
  const volume = new GainNode(ctx, { gain: 0.5 });

  input.connect(shaper).connect(volume).connect(ctx.destination);
};

document.querySelector('#start').addEventListener('click', start);

Kurve zur Laufzeit ändern (Drive-Regler)

const ctx = new AudioContext();
const shaper = new WaveShaperNode(ctx); // curve ist zunächst null
console.log(shaper.curve);

const setDrive = (drive) => {
  const n = 1024;
  const curve = new Float32Array(n);
  for (let i = 0; i < n; i++) {
    const x = (i / (n - 1)) * 2 - 1;
    curve[i] = Math.tanh(drive * x);
  }
  shaper.curve = curve; // neues Array zuweisen
};

setDrive(3);
console.log(shaper.curve.length);

null 1024

// Wichtig · Fallstricke

Ist curve gleich null (Standard), reicht der Knoten das Signal unverändert durch.
Eine Kurve mit weniger als 2 Werten löst einen InvalidStateError aus. Ein ungültiger Wert für oversample erzeugt einen TypeError.
Die Kurve wird beim Zuweisen kopiert. Wer das ursprüngliche Float32Array nachträglich ändert, beeinflusst den Klang nicht. Für Änderungen muss man shaper.curve ein neues Array zuweisen.
Starke Verzerrung erzeugt Obertöne und damit Aliasing. '4x' klingt sauberer, braucht aber mehr Rechenleistung. Oft hilft zusätzlich ein Tiefpass (BiquadFilterNode) nach dem Verzerrer.
Verzerrung erhöht die Lautstärke deutlich. Setze deshalb einen GainNode dahinter, um Übersteuerung am Ausgang und Gehörschäden zu vermeiden.
Browser: Den Konstruktor unterstützen alle aktuellen Browser. Sehr alte Safari-Versionen kennen nur createWaveShaper() (teils mit Präfix webkitAudioContext). Ein AudioContext startet erst nach einer Nutzerinteraktion (Autoplay-Richtlinie).

Siehe auch

WaveShaperNode WaveShaperNode.curve WaveShaperNode.oversample BaseAudioContext.createWaveShaper() AudioNode GainNode BiquadFilterNode