AudioListener.positionY — Eigenschaft · JavaScript-Referenz

Signatur

AudioListener.positionY

Beschreibung

AudioListener.positionY liefert ein AudioParam-Objekt, das die vertikale Position (y-Achse) des virtuellen Hörers im rechtshändigen kartesischen Koordinatensystem der Web Audio API beschreibt. Der Standardwert ist 0. Zusammen mit positionX und positionZ bestimmt dieser Wert, wo sich der Hörer relativ zu den PannerNode-Quellen befindet. Daraus berechnet der Browser Richtung, Abstandsdämpfung und Raumwirkung.

Die Eigenschaft selbst ist schreibgeschützt. Du kannst also kein neues Objekt zuweisen, aber den Wert des AudioParam ändern: direkt über .value oder zeitgenau über Automationsmethoden wie setValueAtTime(), linearRampToValueAtTime() oder setTargetAtTime(). So lassen sich Bewegungen des Hörers, etwa Springen, Treppensteigen oder Fliegen in einem Spiel, ohne Knackser umsetzen.

Typische Einsatzfälle sind 3D-Spiele, WebXR-Anwendungen, virtuelle Räume und interaktive Klanginstallationen. Dort wird die Kameraposition bei jedem Frame auf den Listener übertragen. Beachte: Die y-Achse zeigt standardmäßig nach oben, denn der Standardwert von upY ist 1.

Rückgabewert

Typ

AudioParam

Beschreibung

Ein AudioParam mit dem Standardwert 0, dem Automationsmodus "a-rate" und einem Wertebereich von ungefähr ±3,4·10³⁸ (Grenzen von float32). Der Wert ist die y-Koordinate des Hörers.

Beispiele

Hörerhöhe direkt setzen und auslesen

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

// Hörer auf Augenhöhe (1,7 Einheiten) positionieren
listener.positionY.value = 1.7;

console.log(listener.positionY.value);
console.log(listener.positionY.defaultValue);

1.7000000476837158 0

Sprung des Spielers weich animieren

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

const jump = (height = 2, duration = 0.6) => {
  const now = ctx.currentTime;
  const y = listener.positionY;
  y.cancelScheduledValues(now);
  y.setValueAtTime(y.value, now);
  y.linearRampToValueAtTime(height, now + duration / 2); // hoch
  y.linearRampToValueAtTime(0, now + duration);          // runter
};

document.querySelector('#jump').addEventListener('click', async () => {
  await ctx.resume(); // Autoplay-Richtlinie beachten
  jump();
});

Kameraposition pro Frame übertragen (mit Fallback)

const ctx = new AudioContext();
const listener = ctx.listener;
const camera = { x: 0, y: 1.6, z: 5 };

const updateListener = () => {
  const t = ctx.currentTime;
  if (listener.positionY) {
    // Moderne API: sanft nachführen, verhindert Zipper-Rauschen
    listener.positionX.setTargetAtTime(camera.x, t, 0.02);
    listener.positionY.setTargetAtTime(camera.y, t, 0.02);
    listener.positionZ.setTargetAtTime(camera.z, t, 0.02);
  } else {
    // Veralteter Fallback (ältere Browser)
    listener.setPosition(camera.x, camera.y, camera.z);
  }
  requestAnimationFrame(updateListener);
};

requestAnimationFrame(updateListener);

// Wichtig · Fallstricke

Schreibgeschützt: listener.positionY = 5 hat keine Wirkung und wirft im Strict Mode einen TypeError. Richtig ist listener.positionY.value = 5.
Automation vs. .value: Wenn Automationsereignisse geplant sind, wird ein direkt über .value gesetzter Wert unter Umständen überschrieben. Rufe vorher cancelScheduledValues() auf.
Kompatibilität: Ältere Browser, vor allem Safari vor 14.1, kennen nur die veraltete Methode setPosition(x, y, z). Prüfe mit if (listener.positionY) und nutze sonst den Fallback. Mische nicht beide Wege.
Hörbarkeit: Eine Änderung der Position ist nur bei Quellen hörbar, die über einen PannerNode geleitet werden. Beim panningModel \"equalpower\" wirkt sich die Höhe kaum aus. Nutze für vertikale Ortung \"HRTF\".
Einheiten: Die Koordinaten haben keine feste Einheit. Sie müssen aber zu refDistance und maxDistance der Panner passen, zum Beispiel wenn 1 Einheit 1 Meter entspricht.
Autoplay: Ein AudioContext startet oft im Zustand \"suspended\". Rufe ctx.resume() nach einer Nutzeraktion auf.

Siehe auch

AudioListener AudioListener.positionX AudioListener.positionZ AudioListener.upY AudioListener.setPosition() AudioParam PannerNode BaseAudioContext.listener