StereoPannerNode — Schnittstelle · JavaScript-Referenz

Signatur

interface StereoPannerNode extends AudioNode

Beschreibung

StereoPannerNode ist ein AudioNode mit genau einem Eingang und einem Ausgang. Er verschiebt ein Audiosignal im Stereobild. Die Position steuert die Eigenschaft pan, ein AudioParam im Bereich von -1 (ganz links) über 0 (Mitte) bis 1 (ganz rechts). Der Knoten nutzt einen Algorithmus mit gleicher Leistung (Equal Power), damit die wahrgenommene Lautstärke beim Schwenken gleich bleibt.

Der Ausgang ist immer stereo. Ein Mono-Eingang wird auf beide Kanäle verteilt. Bei einem Stereo-Eingang wird der Pegel zwischen den Kanälen verschoben, die Kanäle werden also nicht einfach vertauscht. channelCount ist auf höchstens 2 begrenzt. channelCountMode darf nicht "max" sein.

Nimm StereoPannerNode für einfaches Links-Rechts-Panning, zum Beispiel für Mischpult-Kanäle, UI-Sounds oder Spiele mit 2D-Perspektive. Brauchst du echte 3D-Positionierung mit Entfernung, Richtwirkung oder HRTF, ist PannerNode die richtige Wahl.

Du erzeugst den Knoten mit new StereoPannerNode(context, options) oder mit der Fabrikmethode context.createStereoPanner(). Weil pan ein a-rate-AudioParam ist, lässt er sich sampelgenau automatisieren, zum Beispiel mit setValueAtTime() oder linearRampToValueAtTime(), oder über einen OscillatorNode modulieren (Auto-Pan).

Parameter

Name	Typ	Default	Beschreibung
$context Pflicht	BaseAudioContext		Der `AudioContext` oder `OfflineAudioContext`, zu dem der Knoten gehört.
$options	StereoPannerOptions	{}	Optionales Objekt mit `pan` (number, Standard `0`) sowie den allgemeinen `AudioNodeOptions` `channelCount`, `channelCountMode` und `channelInterpretation`.
$pan	AudioParam (schreibgeschützte Referenz)	0	Eigenschaft des Knotens: Pan-Position von `-1` (links) bis `1` (rechts). Den Wert setzt du über `pan.value` oder über die Automatisierungsmethoden.

Rückgabewert

Typ

StereoPannerNode

Beschreibung

Der Konstruktor gibt eine neue StereoPannerNode-Instanz zurück. Ihr pan-Parameter hat den übergebenen oder den Standardwert.

Beispiele

Oszillator mit Konstruktor nach links schwenken

const ctx = new AudioContext();
const osc = new OscillatorNode(ctx, { frequency: 440 });
const panner = new StereoPannerNode(ctx, { pan: -0.8 });

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

document.querySelector('#play').addEventListener('click', async () => {
  await ctx.resume(); // Autoplay-Richtlinie: erst nach Nutzerinteraktion
  osc.start();
  osc.stop(ctx.currentTime + 1);
  console.log(panner.pan.value);
});

-0.800000011920929

Pan-Regler für ein <audio>-Element

const ctx = new AudioContext();
const audio = document.querySelector('audio');
const slider = document.querySelector('#pan'); // <input type="range" min="-1" max="1" step="0.01">

const source = ctx.createMediaElementSource(audio);
const panner = ctx.createStereoPanner();
source.connect(panner).connect(ctx.destination);

slider.addEventListener('input', () => {
  // Weich überblenden statt hart springen (vermeidet Knackser)
  panner.pan.setTargetAtTime(Number(slider.value), ctx.currentTime, 0.02);
});

audio.addEventListener('play', () => ctx.resume());

Auto-Pan mit LFO

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

// LFO mit 0,5 Hz; Ausgabe -1..1 wird zum pan-Wert addiert
const lfo = new OscillatorNode(ctx, { frequency: 0.5 });
lfo.connect(panner.pan);

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

Zeitgesteuerter Schwenk von links nach rechts

const ctx = new AudioContext();
const osc = new OscillatorNode(ctx);
const panner = new StereoPannerNode(ctx, { pan: -1 });
osc.connect(panner).connect(ctx.destination);

const t = ctx.currentTime;
panner.pan.setValueAtTime(-1, t);
panner.pan.linearRampToValueAtTime(1, t + 3);
osc.start(t);
osc.stop(t + 3);

// Wichtig · Fallstricke

Wertebereich: Werte außerhalb von -1 bis 1 werden intern begrenzt (geclamped). Ein LFO plus Grundwert kann den Bereich überschreiten. Dann bleibt das Signal einfach am Rand stehen.
Kanal-Einschränkungen: Setzt du channelCount auf einen Wert größer 2, wirft das einen NotSupportedError. Dasselbe gilt für channelCountMode = "max".
Stereo-Eingang: Beim Panning eines Stereosignals wird der Anteil des einen Kanals in den anderen gemischt. Das ist keine reine Balance-Regelung.
Knackser vermeiden: Wenn du pan.value direkt setzt, kann es hörbar klicken. Besser sind setTargetAtTime() oder Rampen.
Autoplay: Browser starten einen AudioContext oft im Zustand "suspended". Rufe ctx.resume() nach einer Nutzerinteraktion auf.
Kompatibilität: Chrome, Edge, Firefox und Safari ab 14.1 unterstützen den Knoten. Ältere Safari-Versionen haben kein createStereoPanner(). Als Ersatz dient dort PannerNode mit panningModel = "equalpower". Der Konstruktor new StereoPannerNode() ist etwas neuer als die Fabrikmethode.

Siehe auch

AudioNode AudioParam PannerNode AudioContext BaseAudioContext.createStereoPanner() GainNode ChannelSplitterNode