AudioListener.positionZ — Eigenschaft · JavaScript-Referenz

Signatur

AudioListener.positionZ

Beschreibung

AudioListener.positionZ gehört zum AudioListener eines BaseAudioContext (erreichbar über audioCtx.listener). Die Eigenschaft liefert ein AudioParam, das die z-Koordinate der Position des Zuhörers beschreibt. Zusammen mit positionX und positionY legt sie fest, von wo aus räumlich positionierte Klangquellen (PannerNode) wahrgenommen werden.

Die Eigenschaft selbst ist schreibgeschützt – du kannst ihr kein neues Objekt zuweisen. Den Wert änderst du über das AudioParam: direkt per positionZ.value oder zeitgesteuert per setValueAtTime(), linearRampToValueAtTime(), setTargetAtTime() usw. So lassen sich Kamerafahrten in Spielen oder 3D-Szenen sample-genau mit dem Klang synchronisieren.

Im rechtshändigen Koordinatensystem der Web Audio API zeigt die positive z-Achse standardmäßig zum Zuhörer hin (der Zuhörer blickt per Voreinstellung in Richtung −z, siehe forwardZ = −1). Eine Bewegung „nach vorn“ bedeutet also, positionZ zu verringern. Der Standardwert ist 0; der Wertebereich ist praktisch unbegrenzt (±3,4028235e38).

Rückgabewert

Typ

AudioParam

Beschreibung

Ein AudioParam vom Typ a-rate mit defaultValue 0, das die z-Koordinate des Zuhörers repräsentiert.

Beispiele

Zuhörer-Position direkt setzen

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

// Zuhörer 5 Einheiten nach "hinten" versetzen
listener.positionZ.value = 5;

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

5 0

Sanfte Kamerafahrt nach vorn mit linearRampToValueAtTime

const audioCtx = new AudioContext();
const osc = new OscillatorNode(audioCtx, { frequency: 440 });
const panner = new PannerNode(audioCtx, {
  panningModel: 'HRTF',
  positionZ: -10 // Quelle 10 Einheiten vor dem Zuhörer
});

osc.connect(panner).connect(audioCtx.destination);

document.querySelector('#start').addEventListener('click', async () => {
  await audioCtx.resume();
  osc.start();

  const now = audioCtx.currentTime;
  const posZ = audioCtx.listener.positionZ;
  posZ.setValueAtTime(0, now);
  // In 4 Sekunden auf die Quelle zubewegen
  posZ.linearRampToValueAtTime(-9, now + 4);
});

Fallback für ältere Browser ohne positionZ

const setListenerPosition = (ctx, x, y, z) => {
  const { listener } = ctx;
  if (listener.positionZ) {
    listener.positionX.setValueAtTime(x, ctx.currentTime);
    listener.positionY.setValueAtTime(y, ctx.currentTime);
    listener.positionZ.setValueAtTime(z, ctx.currentTime);
  } else {
    // Veraltete Methode (z. B. ältere Safari-Versionen)
    listener.setPosition(x, y, z);
  }
};

const ctx = new AudioContext();
setListenerPosition(ctx, 0, 1.7, 3);

// Wichtig · Fallstricke

Schreibgeschützt: listener.positionZ = 3 tut nichts (im Strict Mode gibt es einen TypeError). Richtig ist listener.positionZ.value = 3 oder eine Automationsmethode.
Automation vs. value: Sind Automationsereignisse geplant, wird eine direkte Zuweisung an value je nach Browser überschrieben oder ignoriert. Bei laufenden Rampen besser cancelScheduledValues() und danach setValueAtTime() verwenden.
Koordinatensystem: Der Zuhörer blickt standardmäßig in Richtung −z. Wer Werte aus einer 3D-Engine übernimmt (z. B. Three.js, ebenfalls rechtshändig), muss meist nichts umrechnen; bei linkshändigen Systemen (z. B. Unity) muss z invertiert werden.
Kompatibilität: Ältere Browser (Safari vor 14.1) kennen nur die veraltete Methode AudioListener.setPosition(). Vor der Nutzung per Feature-Detection prüfen.
Hörbar wirkt sich die Position nur auf Quellen aus, die über einen PannerNode geleitet werden; ein StereoPannerNode ignoriert den Listener.
Autoplay-Richtlinien: Ein AudioContext startet oft im Zustand suspended und muss nach einer Nutzerinteraktion per resume() gestartet werden.

Siehe auch

AudioListener.positionX AudioListener.positionY AudioListener.forwardZ AudioListener.forwardX AudioListener.forwardY