AudioListener.forwardY — Eigenschaft · JavaScript-Referenz

Signatur

AudioListener.forwardY

Beschreibung

AudioListener.forwardY gehört zum räumlichen Audiomodell der Web Audio API. Zusammen mit forwardX und forwardZ bestimmt sie den Vorwärts-Vektor des Zuhörers, also die Richtung, in die er „schaut“. Die Up-Komponenten (upX, upY, upZ) legen fest, wo „oben“ ist. Beide Vektoren zusammen ergeben die Ausrichtung, mit der alle PannerNode-Quellen im Kontext räumlich berechnet werden.

Die Eigenschaft selbst ist schreibgeschützt: Das Objekt AudioParam kann man nicht austauschen. Seinen Wert setzt man über forwardY.value oder zeitgesteuert über Automationsmethoden wie setValueAtTime(), linearRampToValueAtTime() oder setTargetAtTime(). Der Standardwert ist 0. Die Standardausrichtung ist (0, 0, -1), der Zuhörer blickt also in die negative z-Richtung.

Ein positiver forwardY-Wert neigt den Blick nach oben, ein negativer nach unten. Das braucht man vor allem in 3D-Spielen, VR/WebXR-Anwendungen oder interaktiven Visualisierungen, in denen die Kamera auch nach oben und unten schwenkt. Der Parameter ist ein k-rate-Parameter: Er wird einmal pro Render-Block mit 128 Samples ausgewertet, nicht für jedes einzelne Sample.

Rückgabewert

Typ

AudioParam

Beschreibung

Ein AudioParam mit der y-Komponente des Vorwärts-Vektors. Standardwert 0, Wertebereich praktisch unbegrenzt (±3,4028235e38). Nur die Richtung zählt, der Vektor muss nicht normiert sein.

Beispiele

Blickrichtung leicht nach oben neigen

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

// Standard: Blick nach (0, 0, -1)
console.log(listener.forwardY.value);

// Zuhörer schaut schräg nach oben
listener.forwardX.value = 0;
listener.forwardY.value = 0.5;
listener.forwardZ.value = -1;

console.log(listener.forwardY.value);

0 0.5

Kamera-Neigung (Pitch) aus einem 3D-Spiel übernehmen

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

// Winkel in Radiant: yaw = Drehung links/rechts, pitch = Neigung oben/unten
const updateListenerOrientation = (yaw, pitch) => {
  const t = ctx.currentTime;
  const fx = Math.sin(yaw) * Math.cos(pitch);
  const fy = Math.sin(pitch);
  const fz = -Math.cos(yaw) * Math.cos(pitch);

  // setTargetAtTime glättet die Übergänge und verhindert Knacken
  listener.forwardX.setTargetAtTime(fx, t, 0.02);
  listener.forwardY.setTargetAtTime(fy, t, 0.02);
  listener.forwardZ.setTargetAtTime(fz, t, 0.02);
};

// 30° nach oben schauen
updateListenerOrientation(0, Math.PI / 6);

Fallback für ältere Browser mit setOrientation()

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

const setForward = (x, y, z) => {
  if (listener.forwardY) {
    listener.forwardX.value = x;
    listener.forwardY.value = y;
    listener.forwardZ.value = z;
  } else {
    // Veraltete API: Vorwärts- und Up-Vektor zusammen
    listener.setOrientation(x, y, z, 0, 1, 0);
  }
};

setForward(0, -0.3, -1); // leicht nach unten blicken
console.log('Ausrichtung gesetzt');

Ausrichtung gesetzt

// Wichtig · Fallstricke

Schreibgeschützt heißt nicht unveränderlich: listener.forwardY = 1 wirkt nicht (im Strict Mode gibt es einen TypeError). Richtig ist listener.forwardY.value = 1.
Vorwärts- und Up-Vektor dürfen nicht parallel sein, etwa forward = (0, 1, 0) zusammen mit up = (0, 1, 0). Dann ist die Ausrichtung nicht eindeutig und die räumliche Berechnung wird unvorhersehbar. Wer senkrecht nach oben schaut, muss auch den Up-Vektor anpassen.
Ein harter Sprung über .value während der Wiedergabe kann hörbare Artefakte erzeugen. Für flüssige Kamerabewegungen besser setTargetAtTime() oder linearRampToValueAtTime() nehmen.
Die Ausrichtung wirkt nur auf Quellen, die über einen PannerNode geleitet werden. Ein StereoPannerNode ignoriert den Listener.
Kompatibilität: Chrome, Edge und Safari unterstützen die AudioParam-Eigenschaften seit Langem. Firefox hat sie erst spät eingeführt; ältere Versionen kennen nur die veraltete Methode setOrientation(). Deshalb vor der Nutzung mit if (listener.forwardY) prüfen, ob die Eigenschaft vorhanden ist.

Siehe auch

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