Signatur
Beschreibung
Die Eigenschaft positionX eines PannerNode legt fest, wo sich eine Schallquelle auf der horizontalen Achse (links–rechts) im rechtshändigen kartesischen Koordinatensystem der Web Audio API befindet. Positive Werte liegen rechts vom Hörer, negative links. Gemeinsam mit positionY (oben–unten) und positionZ (vorne–hinten) ergibt sich die vollständige Position der Quelle.
Die Eigenschaft selbst ist schreibgeschützt, sie liefert aber einen AudioParam. Der eigentliche Wert wird über positionX.value gesetzt oder mit den Automatisierungsmethoden wie setValueAtTime(), linearRampToValueAtTime() oder setTargetAtTime() sampelgenau zeitlich gesteuert. Es handelt sich um einen a-rate-Parameter; der Standardwert ist 0.
Einsatzgebiete sind Spiele, VR/AR-Anwendungen, interaktive Klanginstallationen oder alles, bei dem sich eine Schallquelle hörbar im Raum bewegen soll. Wie stark die Position wahrgenommen wird, hängt außerdem von panningModel ("equalpower" oder "HRTF"), dem Entfernungsmodell und der Position des AudioListener ab.
Rückgabewert
AudioParam, dessen value die X-Koordinate der Quelle angibt (Standard 0, Bereich praktisch unbegrenzt: ±3.4028234663852886e38).Beispiele
Oszillator links vom Hörer platzieren
const ctx = new AudioContext();
const osc = new OscillatorNode(ctx, { frequency: 440 });
const panner = new PannerNode(ctx, { panningModel: 'HRTF' });
// Quelle 3 Einheiten links vom Hörer
panner.positionX.value = -3;
osc.connect(panner).connect(ctx.destination);
osc.start();
osc.stop(ctx.currentTime + 2);
console.log(panner.positionX.value);Quelle von links nach rechts vorbeifliegen lassen
const ctx = new AudioContext();
const osc = new OscillatorNode(ctx, { type: 'sawtooth', frequency: 220 });
const panner = new PannerNode(ctx, {
panningModel: 'HRTF',
distanceModel: 'inverse',
positionZ: -1 // leicht vor dem Hörer
});
const now = ctx.currentTime;
// Sampelgenaue Automatisierung über 4 Sekunden
panner.positionX.setValueAtTime(-10, now);
panner.positionX.linearRampToValueAtTime(10, now + 4);
osc.connect(panner).connect(ctx.destination);
osc.start(now);
osc.stop(now + 4);Position an die Mausposition koppeln
const ctx = new AudioContext();
const panner = new PannerNode(ctx, { panningModel: 'HRTF' });
const osc = new OscillatorNode(ctx, { frequency: 330 });
osc.connect(panner).connect(ctx.destination);
document.addEventListener('click', async () => {
await ctx.resume(); // Autoplay-Richtlinie
osc.start();
}, { once: true });
document.addEventListener('mousemove', (e) => {
// Bildschirmbreite auf -5 … 5 abbilden
const x = (e.clientX / window.innerWidth) * 10 - 5;
// Weiches Nachführen verhindert Knackgeräusche
panner.positionX.setTargetAtTime(x, ctx.currentTime, 0.05);
});// Wichtig · Fallstricke
- Nicht direkt zuweisen:
panner.positionX = 5hat keine Wirkung (bzw. wirft im Strict Mode einen Fehler), da die Eigenschaft schreibgeschützt ist. ImmerpositionX.valueoder Automatisierungsmethoden verwenden. - Sprünge vermeiden: Häufige, abrupte Änderungen von
valuekönnen Knackser erzeugen. Für flüssige BewegungensetTargetAtTime()oderlinearRampToValueAtTime()nutzen. - Veraltete API: Früher wurde die Position über
PannerNode.setPosition(x, y, z)gesetzt. Diese Methode ist veraltet; ältere Safari-Versionen kanntenpositionXnoch nicht, daher ggf. per Feature-Erkennung (if (panner.positionX)) aufsetPosition()ausweichen. - Die Wirkung ist relativ zur Position des
AudioListener(ctx.listener.positionXusw.). Liegen Quelle und Hörer am selben Punkt, ist keine Richtung hörbar. - Für reines Stereo-Panning ohne 3D-Raum ist
StereoPannerNodeeinfacher und performanter;"HRTF"ist rechenintensiver als"equalpower". - Wegen der Autoplay-Richtlinien der Browser startet ein
AudioContextoft im Zustand"suspended"und muss nach einer Nutzerinteraktion mitresume()fortgesetzt werden.