Signatur
Beschreibung
AudioListener.upY gehört zu den sechs Orientierungsparametern des AudioListener einer Web-Audio-API-Anwendung. Zusammen mit upX und upZ bildet es den Aufwärtsvektor, der beschreibt, wo sich für den Zuhörer „oben“ befindet – bildlich die Richtung vom Kinn zum Scheitel. Der Vorwärtsvektor (forwardX/Y/Z) legt die Blickrichtung fest. Beide Vektoren zusammen bestimmen, wie PannerNode-Quellen räumlich wahrgenommen werden.
Die Eigenschaft selbst ist schreibgeschützt: Das AudioParam-Objekt lässt sich nicht ersetzen, wohl aber sein value. Weil es ein vollwertiger AudioParam ist, kannst du den Wert auch zeitgenau mit setValueAtTime(), linearRampToValueAtTime() oder setTargetAtTime() automatisieren. So lassen sich etwa das Neigen oder Rollen des Kopfes in Spielen oder VR-Szenen flüssig darstellen.
Der Standardwert ist 1, der Aufwärtsvektor zeigt also standardmäßig entlang der positiven y-Achse ((0, 1, 0)). Der Parameter ist vom Typ a-rate, der Wertebereich reicht von der kleinsten bis zur größten 32-Bit-Gleitkommazahl. Aufwärts- und Vorwärtsvektor sollten linear unabhängig sein (am besten senkrecht zueinander), sonst ist die Ausrichtung nicht eindeutig definiert.
Rückgabewert
AudioParam, dessen value die y-Komponente des Aufwärtsvektors enthält. Standardwert 1, a-rate.Beispiele
Aktuellen Wert auslesen und setzen
const ctx = new AudioContext();
const { listener } = ctx;
console.log(listener.upY.value); // Standardwert
// Zuhörer auf den Kopf stellen: oben = negative y-Achse
listener.upY.value = -1;
console.log(listener.upY.value);Kopfneigung (Rollen) flüssig animieren
const ctx = new AudioContext();
const { listener } = ctx;
// Kopf um 45° zur Seite neigen, Übergang über 0,5 Sekunden
const winkel = Math.PI / 4;
const t = ctx.currentTime;
listener.upX.setValueAtTime(listener.upX.value, t);
listener.upY.setValueAtTime(listener.upY.value, t);
listener.upX.linearRampToValueAtTime(Math.sin(winkel), t + 0.5);
listener.upY.linearRampToValueAtTime(Math.cos(winkel), t + 0.5);
console.log(Math.cos(winkel).toFixed(3));Mit Fallback für ältere Browser (setOrientation)
const ctx = new AudioContext();
const { listener } = ctx;
const setzeOrientierung = (fx, fy, fz, ux, uy, uz) => {
if (listener.upY) {
listener.forwardX.value = fx;
listener.forwardY.value = fy;
listener.forwardZ.value = fz;
listener.upX.value = ux;
listener.upY.value = uy;
listener.upZ.value = uz;
} else {
// veraltete API, z. B. ältere Firefox-Versionen
listener.setOrientation(fx, fy, fz, ux, uy, uz);
}
};
// Blick nach -z, oben = +y (Standardorientierung)
setzeOrientierung(0, 0, -1, 0, 1, 0);
// Zusammen mit einer räumlichen Quelle
const osc = new OscillatorNode(ctx, { frequency: 440 });
const panner = new PannerNode(ctx, { panningModel: 'HRTF', positionX: 2 });
osc.connect(panner).connect(ctx.destination);
// osc.start(); // nach einer Nutzerinteraktion starten// Wichtig · Fallstricke
- Schreibgeschützt heißt nicht unveränderlich:
listener.upY = 0.5hat keine Wirkung (im Strict ModeTypeError). Richtig istlistener.upY.value = 0.5. - Direkte Zuweisungen an
valuekönnen mit bereits geplanten Automationen kollidieren. Bei laufenden Rampen bessercancelScheduledValues()undsetValueAtTime()verwenden. - Aufwärts- und Vorwärtsvektor dürfen nicht parallel sein, sonst ist die Orientierung undefiniert. Nicht normierte Vektoren werden intern normiert.
- Die Orientierung wirkt nur auf Quellen, die über einen
PannerNodelaufen.StereoPannerNodeignoriert den Listener. - Kompatibilität: Chrome, Edge und Safari unterstützen die
AudioParam-Eigenschaften schon lange. Firefox bot lange nur die veraltete MethodesetOrientation()an. Deshalb vor dem Zugriff prüfen, ob die Eigenschaft existiert (siehe Beispiel 3). - Browser erlauben einen
AudioContextmeist erst nach einer Nutzerinteraktion (Autoplay-Richtlinie). Gegebenenfallsctx.resume()aufrufen.