PannerNode.orientationZ — Eigenschaft · JavaScript-Referenz

Signatur

PannerNode.orientationZ

Beschreibung

Die Eigenschaft orientationZ eines PannerNode gibt die Z-Komponente des Vektors an, in dessen Richtung die Schallquelle abstrahlt. Zusammen mit orientationX und orientationY bildet sie den Richtungsvektor der Quelle im rechtshändigen kartesischen Koordinatensystem der Web Audio API. Die positive Z-Achse zeigt dabei aus dem Bildschirm heraus zum Hörer hin, die negative in den Bildschirm hinein.

Die Ausrichtung spielt nur dann eine Rolle, wenn die Quelle gerichtet abstrahlt, also wenn coneInnerAngle und coneOuterAngle kleiner als 360° sind. Bei den Standardwerten (360°) strahlt die Quelle in alle Richtungen gleich und die Orientierung hat keinen hörbaren Effekt. Außerhalb des Kegels wird die Lautstärke auf coneOuterGain abgesenkt.

Weil die Eigenschaft ein AudioParam ist, setzt man den Wert über .value oder plant Änderungen zeitgenau mit Automatisierungsmethoden wie setValueAtTime() oder linearRampToValueAtTime(). So lässt sich z. B. eine Quelle weich drehen, ohne dass es knackt. Der Standardwert ist 0; der Standard-Richtungsvektor lautet (1, 0, 0).

Rückgabewert

Typ

AudioParam

Beschreibung

Ein AudioParam vom Typ a-rate mit Standardwert 0. Der eigentliche Zahlenwert steht in orientationZ.value (Gleitkommazahl, praktisch unbegrenzt).

Beispiele

Quelle mit Richtkegel zum Hörer ausrichten

const ctx = new AudioContext();
const osc = new OscillatorNode(ctx, { frequency: 440 });

const panner = new PannerNode(ctx, {
  panningModel: 'HRTF',
  positionZ: -3,        // Quelle steht 3 Einheiten vor dem Hörer
  coneInnerAngle: 60,
  coneOuterAngle: 120,
  coneOuterGain: 0.1
});

// Richtung: genau auf den Hörer (positive Z-Achse)
panner.orientationX.value = 0;
panner.orientationY.value = 0;
panner.orientationZ.value = 1;

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

1

Quelle über zwei Sekunden wegdrehen (Automatisierung)

const ctx = new AudioContext();
const panner = new PannerNode(ctx, {
  positionZ: -3,
  orientationX: 0,
  orientationZ: 1,
  coneInnerAngle: 40,
  coneOuterAngle: 90,
  coneOuterGain: 0.05
});

const now = ctx.currentTime;
// Von „zum Hörer“ zu „vom Hörer weg“ drehen
panner.orientationZ.setValueAtTime(1, now);
panner.orientationZ.linearRampToValueAtTime(-1, now + 2);
// X gleichzeitig ausschwenken, damit der Vektor nie (0,0,0) wird
panner.orientationX.setValueAtTime(0, now);
panner.orientationX.linearRampToValueAtTime(1, now + 1);
panner.orientationX.linearRampToValueAtTime(0, now + 2);

Richtung aus einem Winkel berechnen (Fallback für ältere Browser)

const setYaw = (panner, ctx, degrees) => {
  const rad = (degrees * Math.PI) / 180;
  const x = Math.sin(rad);
  const z = Math.cos(rad);
  if (panner.orientationZ) {
    panner.orientationX.setValueAtTime(x, ctx.currentTime);
    panner.orientationY.setValueAtTime(0, ctx.currentTime);
    panner.orientationZ.setValueAtTime(z, ctx.currentTime);
  } else {
    // veraltete API
    panner.setOrientation(x, 0, z);
  }
  return { x: x.toFixed(2), z: z.toFixed(2) };
};

const ctx = new AudioContext();
const panner = ctx.createPanner();
console.log(setYaw(panner, ctx, 90));

{ x: '1.00', z: '0.00' }

// Wichtig · Fallstricke

Ohne Kegel kein Effekt: Solange coneInnerAngle und coneOuterAngle auf 360° stehen (Standard), ändert orientationZ nichts am Klang.
Die Eigenschaft selbst ist schreibgeschützt: panner.orientationZ = 1 bewirkt nichts. Nutze panner.orientationZ.value = 1 oder die Automatisierungsmethoden.
Die Richtung wird intern normalisiert; nur die Richtung zählt, nicht die Länge. Ein Nullvektor (0, 0, 0) ist mehrdeutig und sollte bei Übergängen vermieden werden.
Direktes Setzen von .value während laufender Automatisierung kann ignoriert werden oder mit geplanten Ereignissen kollidieren; bei laufender Wiedergabe besser setValueAtTime() bzw. setTargetAtTime() verwenden, um Knacken zu vermeiden.
Kompatibilität: In allen modernen Browsern verfügbar. Sehr alte Implementierungen (älteres Safari/WebKit) kennen nur die veraltete Methode setOrientation(). Prüfe die Unterstützung daher per Feature-Detection.
Ein AudioContext startet in vielen Browsern erst nach einer Nutzerinteraktion (Autoplay-Richtlinie). Rufe gegebenenfalls ctx.resume() in einem Klick-Handler auf.

Siehe auch

PannerNode.orientationX PannerNode.orientationY PannerNode.positionZ PannerNode.positionX PannerNode.positionY