BaseAudioContext.createStereoPanner() — Methode · JavaScript-Referenz

Signatur

BaseAudioContext.prototype.createStereoPanner()

Beschreibung

Die Methode createStereoPanner() eines AudioContext oder OfflineAudioContext liefert einen neuen StereoPannerNode. Dieser Knoten verschiebt ein Signal mit gleicher Lautstärke (Equal-Power-Panning) zwischen dem linken und dem rechten Kanal. Die Position steuert der AudioParam pan. Sein Wertebereich reicht von -1 (ganz links) über 0 (Mitte) bis 1 (ganz rechts).

Nutzen Sie den Knoten immer dann, wenn Sie nur eine einfache Links-rechts-Verteilung brauchen, etwa für Balance-Regler, Mischpulte, Spiele mit 2D-Soundeffekten oder Audio-Visualisierungen. Im Vergleich zum PannerNode ist er deutlich einfacher und rechensparender, weil er ohne 3D-Positionen, Hörerobjekt und HRTF-Berechnung auskommt.

Weil pan ein AudioParam ist, lässt sich der Wert mit Methoden wie setValueAtTime(), linearRampToValueAtTime() oder setTargetAtTime() sample-genau automatisieren. Sie können den Parameter auch von einem Oszillator modulieren lassen, zum Beispiel für ein Auto-Pan-Effekt. Alternativ zur Fabrikmethode gibt es den Konstruktor new StereoPannerNode(context, { pan }).

Rückgabewert

Typ

StereoPannerNode

Beschreibung

Ein neuer StereoPannerNode mit pan.value === 0 (Mitte), der an den aufrufenden Kontext gebunden ist.

Beispiele

Oszillator nach links verschieben

const ctx = new AudioContext();
const osc = ctx.createOscillator();
const panner = ctx.createStereoPanner();

panner.pan.value = -0.8; // fast ganz links

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

console.log(panner.pan.value);

-0.800000011920929

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

// 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 audioEl = document.querySelector('#player');
const slider = document.querySelector('#balance');

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

// Autoplay-Richtlinie: Kontext erst nach Nutzeraktion fortsetzen
audioEl.addEventListener('play', () => ctx.resume());

slider.addEventListener('input', () => {
  // sanft nachführen, um Knackser zu vermeiden
  panner.pan.setTargetAtTime(Number(slider.value), ctx.currentTime, 0.02);
});

Auto-Pan: Klang wandert per LFO hin und her

const ctx = new AudioContext();
const osc = ctx.createOscillator();
osc.frequency.value = 330;

const panner = ctx.createStereoPanner();

// LFO mit 0,5 Hz moduliert den pan-Parameter zwischen -1 und 1
const lfo = ctx.createOscillator();
lfo.frequency.value = 0.5;
lfo.connect(panner.pan);

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

setTimeout(() => {
  osc.stop();
  lfo.stop();
  ctx.close();
}, 4000);

// Wichtig · Fallstricke

Wertebereich: pan wird auf -1 bis 1 begrenzt. Größere Werte führen nicht zu einem Fehler, der Wert wird einfach abgeschnitten.
Kanäle: Der Knoten gibt immer Stereo aus. Monosignale werden verteilt. Bei Stereoeingang wirkt pan wie ein Balance-Regler, der den jeweils anderen Kanal einmischt, also nicht wie eine reine Pegelabsenkung. channelCount darf höchstens 2 sein und channelCountMode nicht "max", sonst wird ein NotSupportedError ausgelöst.
Knackser: Setzen Sie pan.value nicht sprunghaft, während Ton läuft. Verwenden Sie besser setTargetAtTime() oder eine Rampe.
Autoplay: Ein AudioContext startet oft im Zustand "suspended". Rufen Sie ctx.resume() nach einer Nutzeraktion auf.
Kompatibilität: Alle aktuellen Browser unterstützen die Methode. Safari kennt sie erst ab Version 14.1. Für sehr alte Umgebungen kann man stattdessen createPanner() mit panningModel = "equalpower" verwenden.

Siehe auch

StereoPannerNode BaseAudioContext.createPanner() BaseAudioContext.createGain() AudioParam AudioContext BaseAudioContext