PannerNode.setPosition() — Methode · JavaScript-Referenz

Signatur

PannerNode.prototype.setPosition(x, y, z)

Beschreibung

Die Methode setPosition() eines PannerNode bestimmt, wo sich eine Schallquelle im rechtshändigen kartesischen Koordinatensystem der Web Audio API befindet. Der Hörer wird durch das AudioListener-Objekt unter BaseAudioContext.listener dargestellt. Aus der relativen Lage von Quelle und Hörer berechnet der Browser Panning (links/rechts), Abstandsdämpfung und – je nach coneInnerAngle/coneOuterAngle – Richtungseffekte.

Die Koordinaten haben keine feste Einheit; sie werden erst über refDistance, maxDistance und rolloffFactor sinnvoll interpretiert. Standardmäßig blickt der Hörer in Richtung der negativen Z-Achse, die positive X-Achse zeigt nach rechts, die positive Y-Achse nach oben. Die Standardposition ist (0, 0, 0).

Wichtig: Die Methode gilt als veraltet. Moderner Code setzt die Position über die AudioParam-Eigenschaften positionX, positionY und positionZ. Diese lassen sich zeitgenau automatisieren (z. B. mit linearRampToValueAtTime()), was mit setPosition() nicht möglich ist – ein Aufruf springt sofort auf den neuen Wert. Intern setzt setPosition() einfach die value-Werte dieser drei Parameter.

Parameter

Name	Typ	Beschreibung
$x Pflicht	number	X-Koordinate der Quelle (positiv = rechts vom Hörer bei Standardausrichtung).
$y Pflicht	number	Y-Koordinate der Quelle (positiv = oberhalb).
$z Pflicht	number	Z-Koordinate der Quelle (negativ = vor dem Hörer, positiv = hinter ihm).

Rückgabewert

Typ

undefined

Beschreibung

Kein Rückgabewert.

Beispiele

Oszillator rechts vor dem Hörer platzieren

const ctx = new AudioContext();
const osc = new OscillatorNode(ctx, { frequency: 440 });
const panner = new PannerNode(ctx, {
  panningModel: 'HRTF',
  distanceModel: 'inverse',
  refDistance: 1
});

// 2 Einheiten rechts, 3 Einheiten vor dem Hörer
panner.setPosition(2, 0, -3);

osc.connect(panner).connect(ctx.destination);
osc.start();
osc.stop(ctx.currentTime + 2);
console.log(panner.positionX.value, panner.positionZ.value);

2 -3

Moderne Alternative mit Fallback

const setPannerPosition = (panner, x, y, z) => {
  if (panner.positionX) {
    const t = panner.context.currentTime;
    panner.positionX.setValueAtTime(x, t);
    panner.positionY.setValueAtTime(y, t);
    panner.positionZ.setValueAtTime(z, t);
  } else {
    // Ältere Browser (z. B. alte Firefox-Versionen)
    panner.setPosition(x, y, z);
  }
};

const ctx = new AudioContext();
const panner = ctx.createPanner();
setPannerPosition(panner, -1, 0, 0);
console.log(panner.positionX.value);

-1

Quelle per Mausbewegung verschieben

const ctx = new AudioContext();
const panner = ctx.createPanner();
const osc = ctx.createOscillator();
osc.connect(panner).connect(ctx.destination);

document.addEventListener('click', () => {
  ctx.resume();
  osc.start();
}, { once: true });

document.addEventListener('mousemove', (e) => {
  // Bildschirm auf -5 … +5 abbilden
  const x = (e.clientX / innerWidth) * 10 - 5;
  const z = (e.clientY / innerHeight) * 10 - 5;
  panner.setPosition(x, 0, z);
});

// Wichtig · Fallstricke

Veraltet: Verwende positionX/positionY/positionZ. Die Methode wird in aktuellen Browsern noch unterstützt, kann aber künftig entfallen.
Keine Automatisierung: Häufige Aufrufe (z. B. im mousemove) erzeugen harte Sprünge und können Knackgeräusche verursachen. Für flüssige Bewegungen setTargetAtTime() oder linearRampToValueAtTime() auf den AudioParams nutzen.
Ein Aufruf setzt die value-Werte und kann bereits geplante Automationen auf den Positions-Parametern stören.
Befindet sich die Quelle exakt an der Hörerposition, ist die Richtung undefiniert – der Klang wirkt mittig.
Audio startet erst nach einer Nutzerinteraktion (Autoplay-Richtlinien); ggf. ctx.resume() aufrufen.
Ältere Firefox-Versionen kannten positionX usw. noch nicht – Feature-Erkennung wie im Beispiel verwenden.

Siehe auch

NamedNodeMap.setNamedItemNS() PannerNode.setOrientation() Selection.setPosition() AudioListener.setPosition() NamedNodeMap.item()