PannerNode.positionZ — Eigenschaft · JavaScript-Referenz

Signatur

PannerNode.positionZ

Beschreibung

positionZ gehört zu PannerNode und legt zusammen mit positionX und positionY die Position einer Schallquelle in einem rechtshändigen kartesischen Koordinatensystem fest. Die Z-Achse ist die Tiefenachse. In der Standardausrichtung des AudioListener schaut der Zuhörer in Richtung -Z (forwardZ = -1). Negative Z-Werte liegen deshalb vor dem Zuhörer, positive hinter ihm.

Die Eigenschaft selbst ist schreibgeschützt, gibt aber ein AudioParam-Objekt zurück. Den eigentlichen Wert änderst du über positionZ.value oder zeitgenau mit den Automationsmethoden wie setValueAtTime(), linearRampToValueAtTime() oder setTargetAtTime(). Du kannst den Parameter auch direkt mit einem anderen Audioknoten verbinden, etwa einem OscillatorNode, und ihn so modulieren.

Der Parameter ist a-rate, wird also für jedes Sample einzeln berechnet. Der Standardwert ist 0. Wie stark sich die Entfernung auf die Lautstärke auswirkt, hängt von distanceModel, refDistance, maxDistance und rolloffFactor ab. Der Parameter eignet sich zum Beispiel für Spiele, VR/WebXR-Szenen, räumliche Sonifikation oder Effekte wie „Quelle nähert sich von vorn und entfernt sich nach hinten“.

Rückgabewert

Typ

AudioParam

Beschreibung

Ein AudioParam (a-rate) für die Z-Koordinate. Standardwert 0, erlaubter Bereich etwa -3.4028235e38 bis 3.4028235e38. Der aktuelle Wert steht in .value.

Beispiele

Quelle vor dem Zuhörer platzieren

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

// 3 Einheiten vor dem Zuhörer (Blickrichtung ist -Z)
panner.positionZ.value = -3;

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

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

-3 0

Vorbeiflug von vorn nach hinten automatisieren

const ctx = new AudioContext();
const osc = new OscillatorNode(ctx, { type: 'sawtooth', frequency: 110 });
const panner = new PannerNode(ctx, { panningModel: 'HRTF' });

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

const now = ctx.currentTime;
panner.positionX.value = 1; // leicht rechts versetzt
// Von 20 Einheiten vorn in 4 Sekunden auf 20 Einheiten hinten
panner.positionZ.setValueAtTime(-20, now);
panner.positionZ.linearRampToValueAtTime(20, now + 4);

osc.start(now);
osc.stop(now + 4);

Tiefe per LFO modulieren (Quelle pendelt vor und zurück)

const ctx = new AudioContext();
const source = new OscillatorNode(ctx, { frequency: 330 });
const panner = new PannerNode(ctx, { panningModel: 'HRTF' });

// LFO mit 0,25 Hz, Amplitude 5 → Z schwankt zwischen -7 und 3
const lfo = new OscillatorNode(ctx, { frequency: 0.25 });
const depth = new GainNode(ctx, { gain: 5 });

panner.positionZ.value = -2; // Basiswert, der LFO-Wert wird addiert
lfo.connect(depth).connect(panner.positionZ);

source.connect(panner).connect(ctx.destination);
source.start();
lfo.start();

Position aus einer Spielschleife nachführen

const ctx = new AudioContext();
const panner = new PannerNode(ctx, { panningModel: 'HRTF' });
const enemy = { x: 0, y: 0, z: -10 };

const update = () => {
  enemy.z += 0.05; // Gegner kommt näher
  const t = ctx.currentTime;
  // setTargetAtTime glättet die Werte und vermeidet Knackser
  panner.positionX.setTargetAtTime(enemy.x, t, 0.05);
  panner.positionY.setTargetAtTime(enemy.y, t, 0.05);
  panner.positionZ.setTargetAtTime(enemy.z, t, 0.05);
  requestAnimationFrame(update);
};
requestAnimationFrame(update);

// Wichtig · Fallstricke

Nicht direkt zuweisen: panner.positionZ = 5 hat keine Wirkung, weil die Eigenschaft schreibgeschützt ist. Richtig ist panner.positionZ.value = 5.
Vorzeichen: Bei der Standardausrichtung des Zuhörers liegt -Z vor ihm. Wenn du die Orientierung über AudioListener.forwardZ änderst, verschiebt sich die Bedeutung entsprechend.
Ruckelfreie Bewegung: Wenn du .value sehr oft pro Frame direkt setzt, kann es zu Knacksern kommen. Nutze besser setTargetAtTime() oder linearRampToValueAtTime().
Wenn ein Wert scheinbar ignoriert wird: Sobald Automationsereignisse geplant sind, wird ein direktes Setzen von .value unter Umständen überschrieben. Vorher mit cancelScheduledValues() aufräumen.
Veraltete Alternative: PannerNode.setPosition(x, y, z) gilt als veraltet, ist aber als Rückfallebene für sehr alte Browser (z. B. Safari vor 14.1) nützlich: if (panner.positionZ) { … } else { panner.setPosition(x, y, z); }.
Autoplay-Regeln: Ein AudioContext startet in vielen Browsern im Zustand suspended. Rufe ctx.resume() nach einer Nutzerinteraktion auf.
Leistung: Das Panning-Modell 'HRTF' klingt realistischer, braucht aber deutlich mehr Rechenleistung als 'equalpower'.

Siehe auch

PannerNode.positionX PannerNode.positionY PannerNode.orientationZ PannerNode.orientationX PannerNode.orientationY