Signatur
Beschreibung
Die Eigenschaft orientationX eines PannerNode legt zusammen mit orientationY und orientationZ fest, in welche Richtung eine Schallquelle in einem rechtshändigen kartesischen Koordinatensystem zeigt. orientationX ist die horizontale Komponente dieses Vektors (positive Werte zeigen nach rechts). Der Standardvektor ist (1, 0, 0).
Die Ausrichtung ist nur dann hörbar, wenn die Quelle gerichtet abstrahlt, also wenn coneInnerAngle und coneOuterAngle kleiner als 360° sind. Dann bestimmt der Winkel zwischen Richtungsvektor und Hörerposition, wie stark das Signal abgeschwächt wird (über coneOuterGain). Bei den Standardwerten (360°) klingt die Quelle rundum gleich; eine Änderung von orientationX bewirkt dann nichts.
Weil orientationX ein AudioParam ist, ändert man nicht die Eigenschaft selbst. Man setzt entweder .value oder plant sanfte Änderungen über Automationsmethoden wie setValueAtTime() oder linearRampToValueAtTime(). Das eignet sich z. B. für Spiele, VR-Anwendungen oder Figuren, die sich im Raum drehen, etwa ein NPC, der sich zum Spieler hinwendet.
Der Vektor muss nicht normiert sein, denn nur seine Richtung zählt. Er sollte aber nicht (0, 0, 0) sein, weil sich daraus keine Richtung ergibt.
Rückgabewert
AudioParam vom Typ a-rate. Der Standardwert ist 1, der Wertebereich reicht praktisch von -3.4028235e38 bis 3.4028235e38. Die Referenz selbst ist schreibgeschützt; ändern lässt sich nur der Wert über .value oder die Automationsmethoden.Beispiele
Gerichtete Quelle erstellen und Ausrichtung setzen
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,
positionZ: -2 // Quelle 2 Einheiten vor dem Hörer
});
// Quelle zeigt zunächst nach rechts (vom Hörer weg gedreht)
panner.orientationX.value = 1;
panner.orientationY.value = 0;
panner.orientationZ.value = 0;
console.log(panner.orientationX.defaultValue);
osc.connect(panner).connect(ctx.destination);
osc.start();Quelle sanft zum Hörer drehen (Automation)
// Voraussetzung: ctx und panner aus dem vorigen Beispiel
const now = ctx.currentTime;
// Von (1, 0, 0) nach (0, 0, 1) – zeigt dann auf den Hörer im Ursprung
panner.orientationX.setValueAtTime(1, now);
panner.orientationZ.setValueAtTime(0, now);
panner.orientationX.linearRampToValueAtTime(0, now + 2);
panner.orientationZ.linearRampToValueAtTime(1, now + 2);Ausrichtung aus einem Drehwinkel (Yaw) berechnen
// Setzt die Blickrichtung einer Spielfigur in der X/Z-Ebene
const setYaw = (panner, ctx, degrees) => {
const rad = (degrees * Math.PI) / 180;
const t = ctx.currentTime;
// setTargetAtTime vermeidet Knackser bei häufigen Updates
panner.orientationX.setTargetAtTime(Math.sin(rad), t, 0.05);
panner.orientationY.setTargetAtTime(0, t, 0.05);
panner.orientationZ.setTargetAtTime(-Math.cos(rad), t, 0.05);
};
setYaw(panner, ctx, 90);
console.log(Math.sin(Math.PI / 2).toFixed(2));// Wichtig · Fallstricke
- Ohne Kegel keine Wirkung: Solange
coneInnerAngleundconeOuterAngleauf 360° stehen (Standard), hatorientationXkeinen hörbaren Effekt. - Nicht direkt zuweisen:
panner.orientationX = 0bewirkt nichts bzw. wirft im Strict Mode einen Fehler. Richtig istpanner.orientationX.value = 0. - Veraltete Methode:
PannerNode.setOrientation(x, y, z)gilt als veraltet. Nutzen Sie die dreiAudioParam-Eigenschaften, denn nur sie lassen sich automatisieren. - Nullvektor vermeiden: Stehen alle drei Komponenten auf
0, ist keine Richtung definiert und die Kegelberechnung liefert kein sinnvolles Ergebnis. - Knackser: Springt
.valueabrupt, kann es hörbar knacken. Für flüssige Drehungen eignen sichsetTargetAtTime()oder Rampen. - Kompatibilität: Wird von allen aktuellen Browsern unterstützt (Chrome, Edge, Firefox, Safari 14.1+). Ältere Safari-Versionen kennen nur
setOrientation(). Außerdem startet einAudioContextwegen der Autoplay-Richtlinien oft im Zustandsuspendedund muss nach einer Nutzeraktion mitctx.resume()gestartet werden.