AudioListener.setOrientation() — Methode · JavaScript-Referenz

Signatur

AudioListener.prototype.setOrientation(x, y, z, xUp, yUp, zUp)

Beschreibung

Mit setOrientation() bestimmen Sie, wohin der Zuhörer eines AudioContext blickt und wo für ihn „oben“ ist. Zusammen mit der Position des Zuhörers und der Position bzw. Ausrichtung jedes PannerNode berechnet der Browser daraus die räumliche Wiedergabe: Links-/Rechts-Verteilung, Abstandsdämpfung und Richtwirkung.

Die Methode erwartet zwei Vektoren mit je drei Komponenten: den Forward-Vektor (x, y, z) für die Blickrichtung und den Up-Vektor (xUp, yUp, zUp) für die Oben-Richtung (etwa die Richtung des Scheitels). Standardwerte sind Forward (0, 0, -1) und Up (0, 1, 0) – der Zuhörer blickt also in negative Z-Richtung im rechtshändigen Koordinatensystem. Beide Vektoren sollten linear unabhängig sein und werden intern normiert.

Typische Einsatzfälle sind Spiele, VR-/WebXR-Anwendungen und interaktive 3D-Szenen, in denen sich die Kamera dreht und der Ton mitdrehen soll. In modernem Code sollten Sie statt dieser Methode die AudioParam-Eigenschaften forwardX, forwardY, forwardZ, upX, upY und upZ verwenden – diese erlauben zeitgenaue Automatisierung (z. B. setTargetAtTime()) und damit knackfreie Drehungen.

Parameter

Name	Typ	Default	Beschreibung
$x Pflicht	number	0	X-Komponente des Forward-Vektors (Blickrichtung).
$y Pflicht	number	0	Y-Komponente des Forward-Vektors.
$z Pflicht	number	-1	Z-Komponente des Forward-Vektors.
$xUp Pflicht	number	0	X-Komponente des Up-Vektors (Oben-Richtung).
$yUp Pflicht	number	1	Y-Komponente des Up-Vektors.
$zUp Pflicht	number	0	Z-Komponente des Up-Vektors.

Rückgabewert

Typ

void

Beschreibung

Kein Rückgabewert (undefined).

Beispiele

Zuhörer nach rechts drehen

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

// Blick in +X-Richtung (nach rechts), Kopf aufrecht
listener.setOrientation(1, 0, 0, 0, 1, 0);

// Quelle vor dem ursprünglichen Blickfeld (-Z) platzieren
const panner = new PannerNode(ctx, { panningModel: 'HRTF', positionZ: -3 });
const osc = new OscillatorNode(ctx, { frequency: 440 });
osc.connect(panner).connect(ctx.destination);
osc.start();
// Der Ton erscheint nun links vom Zuhörer

Orientierung aus Kamera-Drehwinkel (Yaw) berechnen

const ctx = new AudioContext();

const updateListener = (yawRad) => {
  const fx = Math.sin(yawRad);
  const fz = -Math.cos(yawRad);
  ctx.listener.setOrientation(fx, 0, fz, 0, 1, 0);
  console.log(`Forward: (${fx.toFixed(2)}, 0, ${fz.toFixed(2)})`);
};

updateListener(Math.PI / 2); // 90° nach rechts

Forward: (1.00, 0, -0.00)

Moderne Variante mit Fallback

const ctx = new AudioContext();

const setListenerOrientation = (fwd, up) => {
  const l = ctx.listener;
  if (l.forwardX) {
    const t = ctx.currentTime;
    // Sanfte Übergänge ohne Knacksen
    l.forwardX.setTargetAtTime(fwd[0], t, 0.05);
    l.forwardY.setTargetAtTime(fwd[1], t, 0.05);
    l.forwardZ.setTargetAtTime(fwd[2], t, 0.05);
    l.upX.setTargetAtTime(up[0], t, 0.05);
    l.upY.setTargetAtTime(up[1], t, 0.05);
    l.upZ.setTargetAtTime(up[2], t, 0.05);
  } else {
    // Fallback für ältere Browser (z. B. älteres Firefox)
    l.setOrientation(...fwd, ...up);
  }
};

setListenerOrientation([0, 0, -1], [0, 1, 0]);

// Wichtig · Fallstricke

Veraltet: Die Methode ist als deprecated markiert, wird aber weiterhin von allen gängigen Browsern unterstützt. Firefox hat die AudioParam-Eigenschaften (forwardX usw.) lange nicht implementiert – eine Feature-Erkennung mit Fallback (siehe Beispiel) ist daher sinnvoll.
Änderungen über setOrientation() wirken sofort; häufige, sprunghafte Aufrufe (z. B. pro Frame bei schneller Mausbewegung) können hörbare Knackser erzeugen. Mit setTargetAtTime() auf den AudioParams lässt sich das glätten.
Forward- und Up-Vektor dürfen nicht parallel und nicht null sein, sonst ist die Ausrichtung undefiniert und die Spatialisierung verhält sich unerwartet.
Die Orientierung wirkt nur auf Quellen, die über einen PannerNode geleitet werden; StereoPannerNode ignoriert den Zuhörer.
Die Positionsangabe erfolgt separat über setPosition() bzw. positionX/Y/Z.

Siehe auch

AudioListener AudioListener.setPosition() AudioListener.forwardX AudioListener.upX PannerNode BaseAudioContext.listener AudioParam.setTargetAtTime()