new StereoPannerNode() — Methode · JavaScript-Referenz

Signatur

new StereoPannerNode(context, options)

Beschreibung

Der Konstruktor new StereoPannerNode() erzeugt einen AudioNode der Web Audio API. Er verteilt ein eingehendes Signal mit einem Panning-Verfahren gleicher Leistung (equal-power panning) auf die Stereokanäle. Anders als der PannerNode arbeitet er nicht räumlich in 3D, sondern nur auf einer Achse von links (-1) bis rechts (1). Dadurch ist er deutlich einfacher und verbraucht weniger Rechenleistung.

Der Konstruktor ist eine Alternative zur Fabrikmethode AudioContext.prototype.createStereoPanner(). Sein Vorteil: Du kannst den Startwert für pan und die Kanaleinstellungen direkt über das options-Objekt setzen. Er funktioniert sowohl mit AudioContext als auch mit OfflineAudioContext.

Typische Einsatzfälle sind Mischpulte und Balance-Regler, Spiele mit einfacher Links-rechts-Ortung von Geräuschen und automatisches Hin-und-her-Schwenken („Auto-Pan“). Den Schwenk steuerst du über den AudioParam pan. Diesen kannst du direkt setzen, zeitgesteuert automatisieren oder durch einen Oszillator modulieren.

Parameter

Name	Typ	Default	Beschreibung
$context Pflicht	BaseAudioContext		Der `AudioContext` oder `OfflineAudioContext`, zu dem der Knoten gehören soll.
$options	StereoPannerOptions	{}	Optionales Objekt mit Startwerten: `pan` (`number`, Standard `0`): Schwenkposition von `-1` (ganz links) bis `1` (ganz rechts). `channelCount` (`number`, Standard `2`): nur `1` oder `2` sind erlaubt. `channelCountMode` (`string`, Standard `"clamped-max"`): `"max"` ist nicht erlaubt. `channelInterpretation` (`string`, Standard `"speakers"`).

Rückgabewert

Typ

StereoPannerNode

Beschreibung

Ein neuer StereoPannerNode. Sein Ausgang liefert immer 2 Kanäle (Stereo).

Beispiele

Oszillator nach links schwenken

const ctx = new AudioContext();
const osc = new OscillatorNode(ctx, { frequency: 440 });

// Startwert direkt über options setzen
const panner = new StereoPannerNode(ctx, { pan: -0.8 });

osc.connect(panner).connect(ctx.destination);
osc.start();
osc.stop(ctx.currentTime + 1);

console.log(panner.pan.value);

-0.800000011920929

Balance-Regler mit einem Range-Input

// HTML: <audio id="player" src="musik.mp3" controls></audio>
//       <input id="balance" type="range" min="-1" max="1" step="0.01" value="0">
const ctx = new AudioContext();
const audio = document.querySelector('#player');
const source = new MediaElementAudioSourceNode(ctx, { mediaElement: audio });
const panner = new StereoPannerNode(ctx);

source.connect(panner).connect(ctx.destination);

document.querySelector('#balance').addEventListener('input', (e) => {
  // sanft überblenden statt harter Sprünge (verhindert Knacken)
  panner.pan.setTargetAtTime(Number(e.target.value), ctx.currentTime, 0.02);
});

// Autoplay-Richtlinien: AudioContext erst nach einer Nutzeraktion fortsetzen
audio.addEventListener('play', () => ctx.resume());

Auto-Pan per LFO modulieren

const ctx = new AudioContext();
const synth = new OscillatorNode(ctx, { type: 'sawtooth', frequency: 220 });
const panner = new StereoPannerNode(ctx, { pan: 0 });

// LFO mit 0,5 Hz schwenkt zwischen -1 und 1 hin und her
const lfo = new OscillatorNode(ctx, { frequency: 0.5 });
lfo.connect(panner.pan);

synth.connect(panner).connect(ctx.destination);
synth.start();
lfo.start();

// Wichtig · Fallstricke

Wertebereich: Werte von pan außerhalb von [-1, 1] werden bei der Verarbeitung auf diesen Bereich begrenzt. Das gilt auch für Modulationssignale.
Kanaleinstellungen: channelCount größer als 2 oder channelCountMode: \"max\" löst einen NotSupportedError aus. Das gilt für den Konstruktor und für eine spätere Zuweisung.
Mono vs. Stereo: Ein Mono-Eingang wird mit gleicher Leistung verteilt. Bei einem Stereo-Eingang verschiebt der Knoten dagegen nur die Balance: Ein Kanal wird in den anderen hineingemischt, die Kanäle werden nicht vertauscht.
Autoplay: Browser starten einen AudioContext oft im Zustand \"suspended\". Rufe ctx.resume() in einem Handler für eine Nutzeraktion auf.
Kompatibilität: Der Konstruktor wird in allen aktuellen Browsern unterstützt. Ältere Safari-Versionen (vor 14.1) kannten nur createStereoPanner() bzw. den Präfix webkitAudioContext. Für alte Browser ist die Fabrikmethode deshalb die sicherere Wahl.
Für 3D-Klang mit Entfernung und Richtung ist PannerNode das passende Werkzeug.

Siehe auch

StereoPannerNode StereoPannerNode.pan BaseAudioContext.createStereoPanner() PannerNode AudioParam AudioNode new DOMRectReadOnly()