PannerNode.setOrientation() — Methode · JavaScript-Referenz

Signatur

PannerNode.prototype.setOrientation(x, y, z)

Beschreibung

Die Methode setOrientation() setzt die Ausrichtung einer Schallquelle im dreidimensionalen Raum der Web Audio API. Sie übergibt einen Richtungsvektor im rechtshändigen kartesischen Koordinatensystem: x zeigt nach rechts, y nach oben und z aus dem Bildschirm heraus auf den Hörer zu. Die Standardausrichtung ist (1, 0, 0).

Die Ausrichtung wirkt sich nur hörbar aus, wenn die Quelle gerichtet abstrahlt, also wenn coneInnerAngle und coneOuterAngle kleiner als 360° sind. Außerhalb des inneren Kegels wird der Pegel bis zum Wert von coneOuterGain abgesenkt. Bei einer kugelförmigen Abstrahlung (Standard: 360°) ändert setOrientation() nichts am Klang.

Die Methode gilt als veraltet. Heute setzt man die Ausrichtung über die drei AudioParam-Eigenschaften orientationX, orientationY und orientationZ. Diese lassen sich zeitgenau automatisieren, zum Beispiel mit setValueAtTime() oder linearRampToValueAtTime(). Ein Aufruf von setOrientation() setzt intern genau diese drei Parameter.

Parameter

Name	Typ	Default	Beschreibung
$x Pflicht	number	1	x-Komponente des Richtungsvektors (positiv = nach rechts).
$y Pflicht	number	0	y-Komponente des Richtungsvektors (positiv = nach oben).
$z Pflicht	number	0	z-Komponente des Richtungsvektors (positiv = auf den Hörer zu, aus dem Bildschirm heraus).

Rückgabewert

Typ

void

Beschreibung

Kein Rückgabewert (undefined).

Beispiele

Gerichtete Quelle zum Hörer 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
});

panner.setPosition(0, 0, -3);   // Quelle 3 Einheiten vor dem Hörer
panner.setOrientation(0, 0, 1); // strahlt direkt auf den Hörer zu

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

console.log(panner.orientationX.value, panner.orientationY.value, panner.orientationZ.value);

0 0 1

Quelle vom Hörer wegdrehen (leiser durch Schallkegel)

const ctx = new AudioContext();
const panner = ctx.createPanner();
panner.coneInnerAngle = 45;
panner.coneOuterAngle = 90;
panner.coneOuterGain = 0;
panner.positionZ.value = -2;

const turnAway = () => panner.setOrientation(0, 0, -1); // weg vom Hörer
const turnToward = () => panner.setOrientation(0, 0, 1);

document.querySelector('#away')?.addEventListener('click', turnAway);
document.querySelector('#toward')?.addEventListener('click', turnToward);

Moderne Alternative mit Feature-Erkennung und Automatisierung

const ctx = new AudioContext();
const panner = new PannerNode(ctx, { coneInnerAngle: 90, coneOuterAngle: 180, coneOuterGain: 0.2 });

const orient = (x, y, z, time = ctx.currentTime) => {
  if (panner.orientationX) {
    // Empfohlen: AudioParams, zeitgenau planbar
    panner.orientationX.setValueAtTime(x, time);
    panner.orientationY.setValueAtTime(y, time);
    panner.orientationZ.setValueAtTime(z, time);
  } else {
    panner.setOrientation(x, y, z); // Fallback für alte Browser
  }
};

// Quelle über 2 Sekunden von rechts nach vorne drehen
orient(1, 0, 0);
panner.orientationX.linearRampToValueAtTime(0, ctx.currentTime + 2);
panner.orientationZ.linearRampToValueAtTime(1, ctx.currentTime + 2);

// Wichtig · Fallstricke

Veraltet: Für neuen Code sollten Sie orientationX, orientationY und orientationZ verwenden. Die Methode ist in den gängigen Browsern zwar noch vorhanden, kann aber irgendwann entfernt werden.
Wirkt nur bei gerichteter Quelle: Solange coneInnerAngle und coneOuterAngle auf 360° stehen (Standard), hat die Ausrichtung keinen hörbaren Effekt.
Der Vektor muss nicht normiert sein, nur seine Richtung zählt. Ein Nullvektor (0, 0, 0) ergibt keine sinnvolle Richtung.
setOrientation() ist nicht zeitgesteuert, der Wert gilt sofort. Plötzliche Richtungswechsel können deshalb Knackser verursachen. Weiche Übergänge erreichen Sie über die Automatisierung der AudioParams.
Nicht verwechseln mit AudioListener.setOrientation(): Diese Methode erwartet sechs Werte (Blick- und Oben-Vektor) und ist ebenfalls veraltet.
Browser starten einen AudioContext wegen der Autoplay-Regeln oft im Zustand suspended. Rufen Sie nach einer Nutzerinteraktion ctx.resume() auf.

Siehe auch

NamedNodeMap.setNamedItemNS() PannerNode.setPosition() AudioListener.setOrientation() Screen.lockOrientation() Screen.unlockOrientation()