PannerNode.orientationY — Eigenschaft · JavaScript-Referenz

Signatur

PannerNode.orientationY

Beschreibung

orientationY gehört zusammen mit orientationX und orientationZ zum Richtungsvektor einer PannerNode. Dieser Vektor gibt an, in welche Richtung die Schallquelle abstrahlt. Die Y-Achse ist die vertikale Achse: Positive Werte bedeuten „nach oben“, negative „nach unten“. Der Standardwert ist 0; der Vektor lautet also standardmäßig (1, 0, 0).

Die Eigenschaft selbst ist schreibgeschützt, sie liefert aber einen AudioParam. Den Wert ändert man über orientationY.value oder zeitgesteuert über Automatisierungsmethoden wie setValueAtTime() und linearRampToValueAtTime(). So lassen sich zum Beispiel Lautsprecher, die sich nach oben oder unten drehen, oder Figuren, die den Kopf heben, flüssig animieren.

Hörbar wird die Ausrichtung nur, wenn ein Schallkegel gesetzt ist, also coneInnerAngle und coneOuterAngle kleiner als 360° sind. Mit den Standardwerten (360°) strahlt die Quelle in alle Richtungen gleich ab, und orientationY hat keine Wirkung. Die Richtung wird mit der Position des Zuhörers (AudioListener) verglichen und daraus die Dämpfung über coneOuterGain berechnet.

Rückgabewert

Typ

AudioParam

Beschreibung

Ein AudioParam vom Typ a-rate. Standardwert 0, gültiger Wertebereich ungefähr ±3.4028235e38 (größter endlicher float-Wert).

Beispiele

Quelle nach oben ausrichten

const ctx = new AudioContext();
const osc = new OscillatorNode(ctx, { frequency: 440 });
const panner = new PannerNode(ctx, {
  panningModel: 'HRTF',
  coneInnerAngle: 60,
  coneOuterAngle: 120,
  coneOuterGain: 0.1
});

// Richtungsvektor (0, 1, 0): die Quelle strahlt senkrecht nach oben
panner.orientationX.value = 0;
panner.orientationY.value = 1;
panner.orientationZ.value = 0;

osc.connect(panner).connect(ctx.destination);
osc.start();
console.log(panner.orientationY.value);

1

Ausrichtung im Konstruktor und Standardwert

const ctx = new AudioContext();
const standard = new PannerNode(ctx);
console.log(standard.orientationY.defaultValue); // 0

const nachUnten = new PannerNode(ctx, { orientationX: 0, orientationY: -1, orientationZ: 0 });
console.log(nachUnten.orientationY.value);

0 -1

Neigung animieren (Quelle hebt sich über 2 Sekunden)

const ctx = new AudioContext();
const panner = new PannerNode(ctx, { coneInnerAngle: 40, coneOuterAngle: 90, coneOuterGain: 0.05 });
const now = ctx.currentTime;

// Von waagerecht nach vorn (0,0,-1) zu schräg nach oben
panner.orientationZ.setValueAtTime(-1, now);
panner.orientationY.setValueAtTime(0, now);
panner.orientationY.linearRampToValueAtTime(1, now + 2);
panner.orientationZ.linearRampToValueAtTime(0, now + 2);

Richtung aus einem Neigungswinkel berechnen

const setPitch = (panner, grad, ctx) => {
  const rad = (grad * Math.PI) / 180;
  const t = ctx.currentTime;
  // Blickrichtung nach vorn (-Z) mit Neigung um die X-Achse
  panner.orientationX.setValueAtTime(0, t);
  panner.orientationY.setValueAtTime(Math.sin(rad), t);
  panner.orientationZ.setValueAtTime(-Math.cos(rad), t);
};

const ctx = new AudioContext();
const panner = new PannerNode(ctx, { coneInnerAngle: 90, coneOuterAngle: 180 });
setPitch(panner, 30, ctx);
console.log(Math.sin(Math.PI / 6).toFixed(2));

0.50

// Wichtig · Fallstricke

Ohne Kegel keine Wirkung: Mit den Standardwerten coneInnerAngle = coneOuterAngle = 360 ist die Ausrichtung nicht hörbar.
Die Eigenschaft ist schreibgeschützt: panner.orientationY = 1 hat keine Wirkung (im Strict Mode gibt es einen TypeError). Richtig ist panner.orientationY.value = 1.
Der Vektor muss nicht normiert sein, weil nur die Richtung zählt. Ein Nullvektor (0, 0, 0) ist aber nicht sinnvoll, dann wird kein Kegel angewendet.
Die veraltete Methode setOrientation(x, y, z) sollte man nicht mehr nutzen. Besser sind die einzelnen AudioParams, die sich auch automatisieren lassen.
Kompatibilität: Chrome 52+, Edge 79+ und Safari 14.1+ unterstützen die Eigenschaft. Firefox hat sie erst spät bekommen. Für ältere Browser prüft man mit 'orientationY' in PannerNode.prototype und greift sonst auf setOrientation() zurück.
Browser starten einen AudioContext oft im Zustand suspended. Er muss nach einer Nutzeraktion mit ctx.resume() gestartet werden.

Siehe auch

PannerNode.orientationX PannerNode.orientationZ PannerNode.positionY PannerNode.positionX PannerNode.positionZ