AudioListener.positionX — Eigenschaft · JavaScript-Referenz

Signatur

AudioListener.positionX

Beschreibung

AudioListener.positionX gibt die x-Koordinate der Hörerposition an, also sozusagen die Position der Ohren des Nutzers in der räumlichen Audioszene. Der Hörer kommt pro AudioContext genau einmal vor und wird über audioCtx.listener abgerufen. Zusammen mit positionY und positionZ legt diese Eigenschaft fest, wo der Hörer im Verhältnis zu den PannerNode-Quellen steht. Daraus berechnet der Browser Lautstärke, Stereo-Panning und (bei panningModel = "HRTF") den binauralen Raumklang.

Die Eigenschaft selbst ist schreibgeschützt. Das heißt aber nur, dass man ihr kein neues AudioParam-Objekt zuweisen kann. Den Wert ändert man über positionX.value oder über die Automatisierungsmethoden wie setValueAtTime(), linearRampToValueAtTime() oder setTargetAtTime(). Damit lassen sich Kamerafahrten in Spielen, VR-Szenen oder interaktive 3D-Audiovisualisierungen ohne Knackser umsetzen.

Der Parameter ist vom Typ a-rate, wird also für jedes einzelne Sample berechnet. Standardwert ist 0. Die Einheit ist beliebig, sie muss nur zu den Koordinaten der PannerNodes und zu deren refDistance/maxDistance passen. Das Koordinatensystem ist rechtshändig: +x zeigt nach rechts, +y nach oben und −z nach vorne (Standard-Blickrichtung des Hörers).

Rückgabewert

Typ

AudioParam

Beschreibung

Ein AudioParam mit der x-Koordinate des Hörers. Standardwert 0, Wertebereich von -3.4028235e38 bis 3.4028235e38 (größte bzw. kleinste 32-Bit-Gleitkommazahl), Automatisierungsrate "a-rate".

Beispiele

x-Position des Hörers lesen und setzen

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

console.log(listener.positionX.value);        // Standardwert
console.log(listener.positionX.defaultValue);

// Hörer 5 Einheiten nach rechts verschieben
listener.positionX.value = 5;
console.log(listener.positionX.value);

0 0 5

Hörer mit Fallback für ältere Browser positionieren

const setListenerPosition = (ctx, x, y, z) => {
  const l = ctx.listener;
  if (l.positionX) {
    // Moderne API: AudioParams mit sanftem Übergang
    const t = ctx.currentTime;
    l.positionX.setTargetAtTime(x, t, 0.05);
    l.positionY.setTargetAtTime(y, t, 0.05);
    l.positionZ.setTargetAtTime(z, t, 0.05);
  } else {
    // Veraltete Methode (z. B. ältere Firefox-Versionen)
    l.setPosition(x, y, z);
  }
};

const ctx = new AudioContext();
setListenerPosition(ctx, 2, 0, -1);

Spielfigur läuft an einer Schallquelle vorbei

const ctx = new AudioContext();

const osc = new OscillatorNode(ctx, { frequency: 220 });
const panner = new PannerNode(ctx, {
  panningModel: 'HRTF',
  distanceModel: 'inverse',
  positionX: 0,
  positionY: 0,
  positionZ: -2 // Quelle 2 Einheiten vor dem Hörer
});

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

document.querySelector('#start').addEventListener('click', async () => {
  await ctx.resume();
  osc.start();
  const now = ctx.currentTime;
  // Hörer bewegt sich in 4 Sekunden von links (-10) nach rechts (+10)
  ctx.listener.positionX.setValueAtTime(-10, now);
  ctx.listener.positionX.linearRampToValueAtTime(10, now + 4);
  osc.stop(now + 4);
});

// Wichtig · Fallstricke

Schreibgeschützt heißt nicht unveränderlich: listener.positionX = 3 hat keine Wirkung (im Strict Mode gibt es einen TypeError). Richtig ist listener.positionX.value = 3 oder eine Automatisierungsmethode.
Browser-Kompatibilität: Firefox unterstützt die AudioParam-Eigenschaften erst seit Version 103. Davor gab es nur die veraltete Methode AudioListener.setPosition(). Prüfen Sie für ältere Umgebungen mit if (listener.positionX), ob die Eigenschaft vorhanden ist.
Wenn Sie value direkt ändern, während Automatisierungsereignisse geplant sind, kann das zu unerwartetem Verhalten führen. Brechen Sie laufende Kurven vorher mit cancelScheduledValues() ab.
Sprunghafte Positionswechsel können hörbare Knackser erzeugen. Für flüssige Bewegungen eignen sich setTargetAtTime() oder linearRampToValueAtTime().
Die Position wirkt sich nur auf Signale aus, die durch einen PannerNode laufen. StereoPannerNode und direkte Verbindungen ignorieren den Hörer.
Browser starten einen AudioContext oft im Zustand "suspended", bis der Nutzer mit der Seite interagiert. Rufen Sie ctx.resume() deshalb in einem Klick-Handler auf.

Siehe auch

AudioListener AudioListener.positionY AudioListener.positionZ AudioListener.forwardX AudioListener.setPosition() AudioParam PannerNode BaseAudioContext.listener