AudioListener.upZ — Eigenschaft · JavaScript-Referenz

Signatur

AudioListener.upZ

Beschreibung

AudioListener.upZ liefert ein AudioParam, das die z-Komponente des Aufwärtsvektors des Hörers beschreibt. Zusammen mit upX und upY legt dieser Vektor fest, wo für den Hörer „oben“ ist, also wohin sein Scheitel zeigt. Die Blickrichtung selbst wird dagegen über forwardX, forwardY und forwardZ festgelegt. Anders als die MDN-Kurzbeschreibung vermuten lässt, geht es bei upZ also nicht um die Blickrichtung.

Blick- und Aufwärtsvektor ergeben gemeinsam die vollständige Ausrichtung des Kopfes. PannerNode-Quellen werden relativ dazu räumlich platziert. Den Aufwärtsvektor ändert man vor allem dann, wenn der Hörer den Kopf seitlich neigt (Rollen), zum Beispiel in Flugsimulationen, VR-Anwendungen oder Spielen mit frei drehbarer Kamera.

Die Eigenschaft selbst ist schreibgeschützt, man kann ihr also kein neues Objekt zuweisen. Den Wert des zurückgegebenen AudioParam ändert man dagegen ganz normal: direkt über .value oder zeitgenau über Automatisierungsmethoden wie setValueAtTime() oder linearRampToValueAtTime(). Standardwert ist 0, der Standard-Aufwärtsvektor lautet (0, 1, 0).

Rückgabewert

Typ

AudioParam

Beschreibung

Ein AudioParam vom Typ a-rate mit dem Standardwert 0. Der Wertebereich ist praktisch unbegrenzt (größte bzw. kleinste darstellbare 32-Bit-Gleitkommazahl).

Beispiele

Aufwärtsvektor auslesen und setzen

const ctx = new AudioContext();
const { listener } = ctx;

console.log(listener.upZ.value); // Standardwert

// Kopf leicht nach vorn geneigt: "oben" zeigt teilweise in -z
listener.upX.value = 0;
listener.upY.value = 0.8;
listener.upZ.value = -0.6;

console.log(listener.upZ.value.toFixed(1));

0 -0.6

Seitliches Neigen (Rollen) sanft automatisieren

const ctx = new AudioContext();
const { listener } = ctx;

// Hörer blickt entlang der x-Achse; beim Rollen dreht sich "oben" von +y nach +z
listener.forwardX.value = 1;
listener.forwardY.value = 0;
listener.forwardZ.value = 0;

const rollen = (winkelRad, dauer = 0.5) => {
  const t = ctx.currentTime;
  listener.upY.linearRampToValueAtTime(Math.cos(winkelRad), t + dauer);
  listener.upZ.linearRampToValueAtTime(Math.sin(winkelRad), t + dauer);
};

rollen(Math.PI / 6); // 30° Neigung innerhalb von 0,5 s

Browser-übergreifend mit Rückfall auf setOrientation()

const setzeAusrichtung = (listener, fwd, up) => {
  if (listener.upZ) {
    listener.forwardX.value = fwd[0];
    listener.forwardY.value = fwd[1];
    listener.forwardZ.value = fwd[2];
    listener.upX.value = up[0];
    listener.upY.value = up[1];
    listener.upZ.value = up[2];
  } else {
    // Firefox & ältere Browser
    listener.setOrientation(...fwd, ...up);
  }
};

const ctx = new AudioContext();
setzeAusrichtung(ctx.listener, [0, 0, -1], [0, 1, 0]);
console.log('Ausrichtung gesetzt');

Ausrichtung gesetzt

// Wichtig · Fallstricke

Kompatibilität: Firefox unterstützt die AudioParam-Eigenschaften forwardX…upZ nicht, dort ist listener.upZ undefined. Vor dem Zugriff also per Feature-Erkennung prüfen und bei Bedarf auf die als veraltet markierte Methode setOrientation() ausweichen.
Keine Zuweisung: listener.upZ = 1 bewirkt nichts (im Strict Mode gibt es einen TypeError). Richtig ist listener.upZ.value = 1.
Vektoren sinnvoll wählen: Aufwärts- und Blickvektor sollten nicht parallel sein, sonst ist die Ausrichtung nicht eindeutig und die räumliche Darstellung kann unerwartet klingen. Sie müssen nicht normiert sein, aber senkrecht zueinander stehende Einheitsvektoren machen die Berechnung nachvollziehbar.
Automatisierung: Wer einen Wert direkt über .value setzt, während Automatisierungsereignisse geplant sind, bekommt unter Umständen nicht das gewünschte Ergebnis. Bei laufenden Rampen vorher cancelScheduledValues() aufrufen.
Der Aufwärtsvektor wirkt sich nur auf Quellen aus, die über einen PannerNode laufen. Ein StereoPannerNode ignoriert den Hörer.

Siehe auch

AudioListener AudioListener.upX AudioListener.upY AudioListener.forwardZ AudioListener.setOrientation() AudioParam PannerNode