AudioListener.upX — Eigenschaft · JavaScript-Referenz

Signatur

AudioListener.upX

Beschreibung

AudioListener.upX ist ein schreibgeschützter AudioParam. Er enthält die x-Komponente des Aufwärtsvektors des Zuhörers in einer räumlichen Audioszene der Web Audio API. Zusammen mit upY und upZ bildet er einen Vektor, der angibt, wo sich der „Scheitel“ des Zuhörers befindet. Die Blickrichtung wird dagegen über forwardX, forwardY und forwardZ festgelegt.

Beide Vektoren zusammen bestimmen die Ausrichtung des Kopfes im Raum. Ein PannerNode berechnet daraus, ob eine Schallquelle links, rechts, oben oder unten zu hören ist. Den Aufwärtsvektor ändert man vor allem, wenn der Zuhörer den Kopf seitlich neigt (Rollen), etwa in Flugsimulationen, VR-Anwendungen oder bei einer 3D-Kamera mit Neigung.

Der Standardwert von upX ist 0; der vollständige Standardvektor ist (0, 1, 0), zeigt also entlang der positiven y-Achse. Weil die Eigenschaft ein AudioParam ist, setzt man ihren Wert über .value oder plant Änderungen über Automatisierungsmethoden wie setValueAtTime() oder linearRampToValueAtTime(). Das ergibt fließende Übergänge ohne Knackser. Die Eigenschaft selbst kann man nicht neu zuweisen.

Rückgabewert

Typ

AudioParam

Beschreibung

Ein AudioParam vom Typ a-rate, dessen value die x-Komponente des Aufwärtsvektors enthält (Standardwert 0, als 32-Bit-Gleitkommazahl gespeichert).

Beispiele

Standardwert auslesen

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

console.log(listener.upX.value, listener.upY.value, listener.upZ.value);
console.log(listener.upX.defaultValue);

0 1 0 0

Kopf um 90° nach rechts neigen (mit Fallback)

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

// Up-Vektor zeigt nun entlang der positiven x-Achse
if (listener.upX) {
  listener.upX.value = 1;
  listener.upY.value = 0;
  listener.upZ.value = 0;
} else {
  // Fallback für ältere Browser (z. B. Firefox)
  listener.setOrientation(0, 0, -1, 1, 0, 0);
}

Weiche Rollbewegung in einer 3D-Szene

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

const osc = new OscillatorNode(ctx, { frequency: 440 });
const panner = new PannerNode(ctx, {
  panningModel: 'HRTF',
  positionX: 2, positionY: 0, positionZ: -2
});
osc.connect(panner).connect(ctx.destination);
osc.start();

// Rollwinkel über 2 Sekunden von 0° auf 45° ändern
const roll = (deg) => (deg * Math.PI) / 180;
const now = ctx.currentTime;
const angle = roll(45);

listener.upX.setValueAtTime(0, now);
listener.upY.setValueAtTime(1, now);
listener.upX.linearRampToValueAtTime(Math.sin(angle), now + 2);
listener.upY.linearRampToValueAtTime(Math.cos(angle), now + 2);

Up-Vektor an eine Kamera-Rotation koppeln

const ctx = new AudioContext();

// z. B. bei jedem Frame aus einer 3D-Engine aufrufen
const syncListener = (up, forward) => {
  const t = ctx.currentTime;
  const l = ctx.listener;
  l.upX.setTargetAtTime(up.x, t, 0.02);
  l.upY.setTargetAtTime(up.y, t, 0.02);
  l.upZ.setTargetAtTime(up.z, t, 0.02);
  l.forwardX.setTargetAtTime(forward.x, t, 0.02);
  l.forwardY.setTargetAtTime(forward.y, t, 0.02);
  l.forwardZ.setTargetAtTime(forward.z, t, 0.02);
};

syncListener({ x: 0, y: 1, z: 0 }, { x: 0, y: 0, z: -1 });

// Wichtig · Fallstricke

Schreibgeschützt: listener.upX = 1 hat keine Wirkung. Setzen Sie stattdessen listener.upX.value oder verwenden Sie Automatisierungsmethoden.
Orthogonalität: Aufwärts- und Blickrichtungsvektor sollten senkrecht zueinander stehen und nicht parallel sein. Sonst ist die Ausrichtung nicht eindeutig und das Panning kann sich unerwartet verhalten. Die Länge der Vektoren spielt keine Rolle, sie werden intern normalisiert.
Browser-Kompatibilität: Firefox unterstützt upX/upY/upZ bislang nicht; dort ist listener.upX undefined. Prüfen Sie die Unterstützung per Feature-Erkennung und greifen Sie auf das veraltete setOrientation() zurück.
Direktes Setzen von .value, während Automatisierungsereignisse geplant sind, kann ignoriert werden. Vorher cancelScheduledValues() aufrufen.
Der Wert wirkt sich nur auf PannerNode-Knoten im selben AudioContext aus. Ohne PannerNode hat er keinen hörbaren Effekt.
Browser starten einen AudioContext oft angehalten (Autoplay-Richtlinie). Rufen Sie ctx.resume() nach einer Nutzerinteraktion auf.

Siehe auch

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