Signatur
Beschreibung
Die Eigenschaft forwardZ gehört zum AudioListener, den jeder AudioContext über context.listener bereitstellt. Zusammen mit forwardX und forwardY bildet sie den Vorwärtsvektor – also die Richtung, in die der „Kopf“ des Zuhörers blickt. Mit dem Oben-Vektor (upX, upY, upZ) legt sie fest, wie Schallquellen mit einem PannerNode räumlich wahrgenommen werden.
Die Web Audio API verwendet ein rechtshändiges kartesisches Koordinatensystem: Standardmäßig blickt der Zuhörer in Richtung negative z-Achse (forwardZ = -1), während upY = 1 gilt. Ein Wert von forwardZ = 1 dreht den Zuhörer also um 180°, sodass er nach „hinten“ schaut.
Da forwardZ ein AudioParam ist, lässt sich der Wert nicht nur direkt über .value setzen, sondern auch sample-genau automatisieren, etwa mit setValueAtTime(), linearRampToValueAtTime() oder setTargetAtTime(). Genau das braucht man für flüssige Kopfdrehungen in Spielen, VR-Anwendungen oder interaktiven 3D-Klanglandschaften. Die Eigenschaft selbst ist schreibgeschützt: Man ersetzt nicht das AudioParam-Objekt, sondern ändert dessen Wert.
Rückgabewert
AudioParam vom Typ a-rate mit dem Standardwert -1. Der Wert kann über .value gelesen und gesetzt oder über die Automatisierungsmethoden zeitlich gesteuert werden.Beispiele
Standardausrichtung auslesen und Zuhörer umdrehen
const ctx = new AudioContext();
const { listener } = ctx;
console.log(listener.forwardZ.value); // Standard: Blick in Richtung -z
// Zuhörer blickt jetzt nach +z (um 180° gedreht)
listener.forwardZ.value = 1;
console.log(listener.forwardZ.value);Blickrichtung aus einem Drehwinkel (Yaw) berechnen
const ctx = new AudioContext();
const { listener } = ctx;
// Winkel in Grad: 0 = nach vorn (-z), 90 = nach rechts (+x)
const setYaw = (deg) => {
const rad = (deg * Math.PI) / 180;
const t = ctx.currentTime;
listener.forwardX.setValueAtTime(Math.sin(rad), t);
listener.forwardY.setValueAtTime(0, t);
listener.forwardZ.setValueAtTime(-Math.cos(rad), t);
};
setYaw(90);
// Die Werte werden erst nach der Planung durch den Audio-Thread übernommen
setTimeout(() => console.log(listener.forwardX.value.toFixed(2), listener.forwardZ.value.toFixed(2)), 100);Flüssige Kopfdrehung mit Panner-Quelle
const ctx = new AudioContext();
const osc = new OscillatorNode(ctx, { frequency: 440 });
const panner = new PannerNode(ctx, {
panningModel: 'HRTF',
positionX: 0,
positionY: 0,
positionZ: -3 // Quelle drei Einheiten vor dem Zuhörer
});
osc.connect(panner).connect(ctx.destination);
document.querySelector('#start').addEventListener('click', async () => {
await ctx.resume();
osc.start();
const t = ctx.currentTime;
const { listener } = ctx;
// Innerhalb von 2 Sekunden nach rechts drehen – Ton wandert ins linke Ohr
listener.forwardX.setValueAtTime(0, t);
listener.forwardZ.setValueAtTime(-1, t);
listener.forwardX.linearRampToValueAtTime(1, t + 2);
listener.forwardZ.linearRampToValueAtTime(0, t + 2);
});Fallback für ältere Browser ohne AudioParam-Eigenschaften
const ctx = new AudioContext();
const { listener } = ctx;
const setOrientation = (fx, fy, fz, ux = 0, uy = 1, uz = 0) => {
if (listener.forwardZ) {
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 Methode, z. B. ältere Firefox-Versionen
listener.setOrientation(fx, fy, fz, ux, uy, uz);
}
};
setOrientation(0, 0, 1);
console.log('Orientierung gesetzt');// Wichtig · Fallstricke
- Browser-Kompatibilität: Chrome, Edge und Safari unterstützen
forwardZschon lange. Firefox hat dieAudioParam-Eigenschaften desAudioListenererst spät eingeführt. Für ältere Versionen solltest du per Feature-Erkennung (if (listener.forwardZ)) auf die veraltete MethodesetOrientation()ausweichen. - Vektoren nicht parallel: Vorwärts- und Oben-Vektor dürfen nicht parallel oder null sein, sonst ist die Ausrichtung nicht definiert. Die Vektoren müssen nicht normalisiert sein, das übernimmt die Implementierung intern. Für die eigene Berechnung sind Einheitsvektoren trotzdem übersichtlicher.
- Koordinatensystem: Standardmäßig blickt der Zuhörer nach negativ z. Wer aus einem Spiel- oder 3D-Framework mit anderer Konvention (z. B. +z nach vorn) umrechnet, muss das Vorzeichen anpassen.
- Werte ändern: Wenn du
.valuedirekt setzt, während für denselben Parameter Automatisierungen geplant sind, kann es zu Konflikten kommen. Für Animationen solltest du einheitlichsetValueAtTime()und die Rampen-Methoden verwenden. - Der Effekt ist nur hörbar, wenn die Quellen über einen
PannerNodelaufen. EinStereoPannerNodeberücksichtigt den Zuhörer nicht. - Browser starten einen
AudioContextoft erst nach einer Nutzerinteraktion (Autoplay-Richtlinie). Rufe deshalbctx.resume()in einem Klick-Handler auf.