Signatur
Beschreibung
AudioListener.forwardX gehört zur räumlichen Audio-Verarbeitung der Web Audio API. Die Ausrichtung des Zuhörers wird durch zwei Vektoren beschrieben: den Vorwärtsvektor (forwardX, forwardY, forwardZ) für die Blickrichtung und den Aufwärtsvektor (upX, upY, upZ) für die Richtung „oben“. Zusammen legen sie fest, wie ein PannerNode Schallquellen relativ zum Zuhörer im Raum verteilt.
Die Eigenschaft selbst ist schreibgeschützt. Sie liefert aber ein AudioParam-Objekt, dessen value du ändern kannst. Du kannst auch Automatisierungsmethoden wie setValueAtTime(), linearRampToValueAtTime() oder setTargetAtTime() nutzen. So lassen sich Kopfdrehungen, etwa in Spielen oder VR-Anwendungen, zeitgenau und ohne Knackgeräusche umsetzen.
Standardmäßig zeigt der Vorwärtsvektor auf (0, 0, -1), der Zuhörer blickt also in die negative z-Richtung. forwardX hat deshalb den Standardwert 0. Ist der Wert positiv, dreht sich die Blickrichtung nach rechts (positive x-Achse), ist er negativ, nach links. Der Vektor muss nicht normiert sein, darf aber nicht die Länge null haben und nicht parallel zum Aufwärtsvektor stehen.
Rückgabewert
AudioParam mit der Automatisierungsrate "a-rate", dem Standardwert 0 und praktisch unbegrenztem Wertebereich (größte bzw. kleinste darstellbare Gleitkommazahl). Über .value liest oder setzt man den aktuellen Wert.Beispiele
Aktuelle Blickrichtung auslesen und ändern
const ctx = new AudioContext();
const listener = ctx.listener;
console.log(listener.forwardX.value, listener.forwardY.value, listener.forwardZ.value);
// Zuhörer nach rechts (positive x-Achse) blicken lassen
listener.forwardX.value = 1;
listener.forwardZ.value = 0;
console.log(listener.forwardX.value);Kopfdrehung aus einem Winkel berechnen (z. B. Spielfigur)
const ctx = new AudioContext();
const { listener } = ctx;
// Winkel in Grad: 0 = geradeaus (-z), 90 = rechts (+x)
const setHeading = (degrees) => {
const rad = (degrees * Math.PI) / 180;
const t = ctx.currentTime;
// setTargetAtTime vermeidet hörbare Sprünge
listener.forwardX.setTargetAtTime(Math.sin(rad), t, 0.05);
listener.forwardZ.setTargetAtTime(-Math.cos(rad), t, 0.05);
};
document.addEventListener('keydown', (e) => {
if (e.key === 'ArrowRight') setHeading(90);
if (e.key === 'ArrowLeft') setHeading(-90);
if (e.key === 'ArrowUp') setHeading(0);
});Fallback für ältere Browser ohne AudioParam-Orientierung
const ctx = new AudioContext();
const listener = ctx.listener;
const setOrientation = (fx, fy, fz, ux = 0, uy = 1, uz = 0) => {
if (listener.forwardX) {
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. in älteren Firefox-Versionen
listener.setOrientation(fx, fy, fz, ux, uy, uz);
}
};
setOrientation(1, 0, 0);
console.log('Orientierung gesetzt');// Wichtig · Fallstricke
- Browser-Kompatibilität: In Chrome, Edge und Safari wird die Eigenschaft seit Langem unterstützt. Firefox bietet sie erst seit Version 138 an. In älteren Versionen gibt es nur die veraltete Methode
AudioListener.setOrientation(). Prüfe deshalb vorher mitif (listener.forwardX), ob die Eigenschaft vorhanden ist. - Die Zuweisung
listener.forwardX = 1schlägt fehl, weil die Eigenschaft selbst schreibgeschützt ist. Richtig istlistener.forwardX.value = 1. - Der Vorwärtsvektor darf nicht parallel zum Aufwärtsvektor stehen (Standard:
(0, 1, 0)), sonst ist die Ausrichtung nicht definiert. - Ob sich
forwardXhörbar auswirkt, hängt davon ab, dass Schallquellen über einenPannerNodegeleitet werden. Einfache Stereo-Signale bleiben unverändert. - Setzt du
.valuedirekt, während Automatisierungsereignisse geplant sind, kann das je nach Browser ignoriert oder überschrieben werden. Brich geplante Ereignisse deshalb vorher mitcancelScheduledValues()ab.