PannerNode.positionY — Eigenschaft · JavaScript-Referenz

Signatur

PannerNode.positionY

Beschreibung

Die schreibgeschützte Eigenschaft positionY einer PannerNode gibt ein AudioParam-Objekt zurück. Es bestimmt die vertikale Position der Schallquelle relativ zum Hörer (AudioListener). Positive Werte liegen über dem Hörer, negative Werte darunter. Der Standardwert ist 0.

Zusammen mit positionX und positionZ legt sie die Position der Quelle fest. Weil es sich um einen AudioParam handelt (a-rate), kann der Wert nicht nur direkt über .value gesetzt, sondern auch zeitgenau automatisiert werden, etwa mit setValueAtTime(), linearRampToValueAtTime() oder setTargetAtTime(). So lassen sich sich vertikal bewegende Quellen wie Flugzeuge, Vögel oder Schritte auf einer Treppe ruckelfrei nachbilden.

Wie deutlich man die vertikale Position hört, hängt stark vom panningModel ab: Mit "HRTF" werden Höhenunterschiede über kopfbezogene Übertragungsfunktionen hörbar gemacht. Mit "equalpower" wirkt sich die Y-Koordinate im Wesentlichen nur über die Entfernung (Distanzdämpfung) und den Azimut aus, nicht über eine echte Höhenwahrnehmung.

Rückgabewert

Typ

AudioParam

Beschreibung

Ein AudioParam mit dem Standardwert 0. Die Eigenschaft selbst ist schreibgeschützt, ihr Wert lässt sich aber über positionY.value oder die Automatisierungsmethoden ändern. Es gibt praktisch keinen Wertebereich (±größter float-Wert).

Beispiele

Quelle über dem Hörer platzieren

const ctx = new AudioContext();
const osc = new OscillatorNode(ctx, { frequency: 440 });
const panner = new PannerNode(ctx, {
  panningModel: 'HRTF',
  distanceModel: 'inverse'
});

// Quelle 3 Einheiten über dem Hörer
panner.positionY.value = 3;

osc.connect(panner).connect(ctx.destination);
osc.start();
osc.stop(ctx.currentTime + 2);

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

3 0

Vorbeifliegendes Objekt: Höhe animieren

const ctx = new AudioContext();
const noise = ctx.createBufferSource();
const buffer = ctx.createBuffer(1, ctx.sampleRate * 4, ctx.sampleRate);
const data = buffer.getChannelData(0);
for (let i = 0; i < data.length; i++) data[i] = Math.random() * 2 - 1;
noise.buffer = buffer;

const panner = new PannerNode(ctx, { panningModel: 'HRTF', positionZ: -2 });
const t = ctx.currentTime;

// Von unten (-10) nach oben (+10) innerhalb von 4 Sekunden
panner.positionY.setValueAtTime(-10, t);
panner.positionY.linearRampToValueAtTime(10, t + 4);

noise.connect(panner).connect(ctx.destination);
noise.start(t);
noise.stop(t + 4);

Höhe per Schieberegler steuern (mit Fallback)

// <input type="range" id="hoehe" min="-10" max="10" step="0.1">
const ctx = new AudioContext();
const panner = ctx.createPanner();
const slider = document.querySelector('#hoehe');

const setHoehe = (y) => {
  if (panner.positionY) {
    // Weiche Annäherung vermeidet Knackser
    panner.positionY.setTargetAtTime(y, ctx.currentTime, 0.05);
  } else {
    // Alte Browser: veraltete setPosition()-Methode
    panner.setPosition(0, y, 0);
  }
};

slider.addEventListener('input', (e) => setHoehe(Number(e.target.value)));

// Wichtig · Fallstricke

Koordinatensystem: Die Web Audio API verwendet ein rechtshändiges System: X = rechts, Y = oben, Z = zum Hörer hin (nach hinten). Standardmäßig blickt der Hörer in Richtung −Z, und sein „Oben“-Vektor ist (0, 1, 0). Wer AudioListener.upX/upY/upZ ändert, ändert auch, was „oben“ bedeutet.
Nicht direkt zuweisen: panner.positionY = 5 hat keine Wirkung (bzw. löst im strikten Modus einen Fehler aus). Richtig ist panner.positionY.value = 5.
Automatisierung vs. .value: Wenn Automatisierungsereignisse geplant sind, kann ein Setzen von .value ignoriert werden oder unerwartet wirken. Vorher gegebenenfalls cancelScheduledValues() aufrufen.
Höhenwahrnehmung: Nur mit panningModel = "HRTF" und Kopfhörern wirklich überzeugend. Liegen Quelle und Hörer an derselben Position, gibt es keine Richtungsinformation.
Kompatibilität: Ältere Browser (z. B. Safari vor 14.1) kennen nur die veraltete Methode PannerNode.setPosition(x, y, z). Mit 'positionY' in panner prüfen und bei Bedarf darauf zurückfallen.
Autoplay: Ein AudioContext startet in vielen Browsern im Zustand suspended und muss nach einer Nutzerinteraktion mit ctx.resume() fortgesetzt werden.

Siehe auch

PannerNode.positionX PannerNode.positionZ PannerNode.orientationY PannerNode.orientationX PannerNode.orientationZ