AudioListener.setPosition() — Methode · JavaScript-Referenz

Signatur

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

Beschreibung

Mit setPosition() legt man fest, wo sich der Hörer (AudioContext.listener) im 3D-Raum befindet. Zusammen mit PannerNode-Quellen berechnet die Web Audio API daraus Lautstärke, Stereo-Panning und (bei HRTF) räumliche Ortung. Das ist z. B. für Spiele, VR-Szenen oder interaktive Klanginstallationen nützlich, bei denen sich die Kamera bzw. Spielfigur bewegt.

Das Koordinatensystem ist rechtshändig: x zeigt nach rechts, y nach oben und z aus dem Bildschirm heraus zum Betrachter. Standardmäßig steht der Hörer im Ursprung (0, 0, 0). Die Einheiten sind frei wählbar, müssen aber zu den Werten der PannerNode-Eigenschaften wie refDistance und maxDistance passen.

Die Methode gilt als veraltet. Heute nutzt man stattdessen die AudioParam-Eigenschaften positionX, positionY und positionZ. Damit lassen sich Positionsänderungen genau planen und weich überblenden (z. B. mit setValueAtTime() oder linearRampToValueAtTime()). setPosition() dagegen ändert die Position sofort und ohne Zeitsteuerung.

Parameter

Name	Typ	Beschreibung
$x Pflicht	number	X-Koordinate (links/rechts) des Hörers.
$y Pflicht	number	Y-Koordinate (unten/oben) des Hörers.
$z Pflicht	number	Z-Koordinate (vorne/hinten) des Hörers. Positive Werte liegen in Richtung des Betrachters.

Rückgabewert

Typ

void

Beschreibung

Kein Rückgabewert (undefined).

Beispiele

Hörer positionieren und Quelle räumlich platzieren

const ctx = new AudioContext();
const listener = ctx.listener;

// Hörer etwas nach rechts versetzen
listener.setPosition(2, 0, 0);

const osc = new OscillatorNode(ctx, { frequency: 440 });
const panner = new PannerNode(ctx, {
  panningModel: 'HRTF',
  positionX: -2,
  positionY: 0,
  positionZ: -1
});

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

Moderne Alternative mit Fallback für ältere Browser

const setListenerPosition = (ctx, x, y, z) => {
  const l = ctx.listener;
  if (l.positionX) {
    // Bevorzugt: AudioParams mit exakter Zeitplanung
    const t = ctx.currentTime;
    l.positionX.setValueAtTime(x, t);
    l.positionY.setValueAtTime(y, t);
    l.positionZ.setValueAtTime(z, t);
  } else {
    // Fallback, z. B. ältere Firefox-Versionen
    l.setPosition(x, y, z);
  }
};

const ctx = new AudioContext();
setListenerPosition(ctx, 0, 1.7, 0); // Ohrhöhe ~1,7 m
console.log(ctx.listener.positionY?.value);

1.7

Hörer an eine Spielfigur koppeln

const ctx = new AudioContext();
const player = { x: 0, y: 0, z: 0 };

document.addEventListener('keydown', (e) => {
  if (e.key === 'ArrowLeft') player.x -= 0.5;
  if (e.key === 'ArrowRight') player.x += 0.5;
  if (e.key === 'ArrowUp') player.z -= 0.5;
  if (e.key === 'ArrowDown') player.z += 0.5;
  ctx.listener.setPosition(player.x, player.y, player.z);
  console.log(`Hörer bei ${player.x}, ${player.y}, ${player.z}`);
});

Hörer bei 0.5, 0, 0 (nach einmal Pfeil rechts)

// Wichtig · Fallstricke

Veraltet: Für neuen Code die AudioParam-Eigenschaften positionX/positionY/positionZ verwenden. Die ältere Methode ist trotzdem in Chrome, Edge, Safari und Firefox weiterhin vorhanden. Firefox hat die positionX-Parameter am Listener lange nicht unterstützt, deshalb ist eine Funktionsprüfung sinnvoll.
Wer setPosition() und die AudioParams gemischt nutzt, bekommt womöglich unerwartete Ergebnisse. Außerdem hebt ein direkter Aufruf eventuell geplante Automationen auf. Am besten nur einen der beiden Wege verwenden.
Positionsänderungen passieren sofort. Bei schnellen Sprüngen können hörbare Knackser entstehen. Für weiche Bewegungen besser linearRampToValueAtTime() oder setTargetAtTime() nutzen.
Die Position allein hat nur Wirkung, wenn die Quellen über einen PannerNode laufen. Für eine glaubwürdige Ortung sollte man zusätzlich die Blickrichtung mit setOrientation() setzen.
Browser starten einen AudioContext oft im Zustand suspended. Er muss nach einer Nutzerinteraktion mit ctx.resume() gestartet werden.

Siehe auch

AudioListener AudioListener.setOrientation() AudioListener.positionX PannerNode BaseAudioContext.listener AudioParam.setValueAtTime() MediaSession.setPositionState()