StereoPannerNode.pan — Eigenschaft · JavaScript-Referenz

Signatur

StereoPannerNode.pan

Beschreibung

Die Eigenschaft pan eines StereoPannerNode ist ein AudioParam, der festlegt, wo ein Audiosignal im Stereobild liegt. Der Wertebereich reicht von -1 (ganz links) über 0 (Mitte, Standardwert) bis 1 (ganz rechts). Werte außerhalb dieses Bereichs werden auf die Grenzen begrenzt.

Die Eigenschaft selbst ist schreibgeschützt: Du ersetzt nicht das AudioParam-Objekt, sondern änderst dessen value oder planst Änderungen über die Automatisierungsmethoden wie setValueAtTime(), linearRampToValueAtTime() oder setTargetAtTime(). Weil es ein a-rate-Parameter ist, wird der Wert für jedes einzelne Sample berechnet. Dadurch gelingen weiche Kamerafahrten im Stereobild ohne Knacken, und du kannst sogar einen Oszillator (LFO) direkt mit pan verbinden, um ein Auto-Pan zu bauen.

Typische Einsatzfälle sind Mischpulte in Web-Anwendungen, räumliche Soundeffekte in Spielen (z. B. Gegner links oder rechts vom Spieler) und Effekte wie das Hin-und-Her-Wandern eines Tons. Für echtes 3D-Audio mit Entfernung und Richtung ist dagegen der PannerNode gedacht.

Rückgabewert

Typ

AudioParam

Beschreibung

Ein a-rate-AudioParam mit defaultValue 0, minValue -1 und maxValue 1. Über pan.value liest oder setzt du die aktuelle Position.

Beispiele

Oszillator nach links verschieben

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

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

// Ton deutlich nach links setzen
panner.pan.value = -0.8;
console.log(panner.pan.value);

osc.start();
osc.stop(ctx.currentTime + 2);

-0.800000011920929

Panning über einen Schieberegler steuern

// HTML: <input id="pan" type="range" min="-1" max="1" step="0.01" value="0">
// <audio id="track" src="musik.mp3" controls></audio>
const ctx = new AudioContext();
const audio = document.querySelector('#track');
const slider = document.querySelector('#pan');

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

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

slider.addEventListener('input', () => {
  // setTargetAtTime vermeidet Knackser bei schnellen Änderungen
  panner.pan.setTargetAtTime(Number(slider.value), ctx.currentTime, 0.02);
});

Sanfte Fahrt von links nach rechts

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

const now = ctx.currentTime;
panner.pan.setValueAtTime(-1, now);
panner.pan.linearRampToValueAtTime(1, now + 3);

osc.start(now);
osc.stop(now + 3);

Auto-Pan mit LFO

const ctx = new AudioContext();
const osc = new OscillatorNode(ctx, { frequency: 330 });
const panner = new StereoPannerNode(ctx, { pan: 0 });

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

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

// Wichtig · Fallstricke

Schreibgeschützt: panner.pan = 0.5 hat keine Wirkung (im Strict Mode TypeError). Richtig ist panner.pan.value = 0.5.
Wertebereich: Werte außerhalb von -1 bis 1 werden begrenzt. Bei Modulation per LFO addiert sich das Signal zum value. Ist value nicht 0, läuft das Ergebnis schnell in die Begrenzung.
Automatisierung: Nach dem Planen mit setValueAtTime() & Co. werden direkte Zuweisungen an value je nach Browser ignoriert oder überschrieben. Mit cancelScheduledValues() löschst du geplante Änderungen.
Weniger Knacken: Sprunghafte Änderungen von value können hörbare Knackser erzeugen. Bei Nutzereingaben ist setTargetAtTime() besser.
Mono vs. Stereo: Bei einer Mono-Quelle wird das Signal über ein Equal-Power-Verfahren auf die Kanäle verteilt. Bei einer Stereo-Quelle wird dagegen der eine Kanal leiser und der andere lauter. Es ist also kein echtes Verschieben beider Kanäle.
Autoplay: Ein AudioContext startet oft im Zustand suspended und muss nach einer Nutzeraktion mit resume() gestartet werden.
Kompatibilität: Wird von allen aktuellen Browsern unterstützt. Safari kann StereoPannerNode erst ab Version 14.1. Für ältere Safari-Versionen ist ein PannerNode mit panningModel: 'equalpower' ein Ersatz.

Siehe auch

BiquadFilterNode.gain GainNode.gain Attr.ownerElement BiquadFilterNode.Q Element.ariaRowSpan