new PannerNode() — Methode · JavaScript-Referenz

Signatur

new PannerNode(context, options)

Beschreibung

Der Konstruktor new PannerNode() erzeugt einen Audioknoten für die räumliche Wiedergabe in der Web Audio API. Ein PannerNode legt fest, wo sich eine Schallquelle im 3D-Raum befindet, in welche Richtung sie abstrahlt und wie ihre Lautstärke mit der Entfernung abnimmt. Wie die Quelle klingt, hängt immer von ihrer Lage relativ zum AudioListener des Kontexts ab (context.listener).

Anders als bei der älteren Fabrikmethode AudioContext.createPanner() lassen sich alle Einstellungen gleich beim Erzeugen über ein options-Objekt übergeben, etwa Panning-Modell, Distanzmodell, Position, Ausrichtung und Abstrahlkegel. Das macht den Code kürzer und besser lesbar.

Typische Einsatzgebiete sind Spiele, VR/WebXR-Anwendungen, interaktive Klanginstallationen und Konferenz-Apps, in denen Sprecher räumlich verteilt werden sollen. Wenn du nur Stereo links/rechts brauchst, ist der deutlich leichtere StereoPannerNode meist die bessere Wahl.

Position und Ausrichtung sind AudioParam-Objekte (positionX, positionY, positionZ, orientationX …). Deshalb lassen sich Bewegungen sample-genau automatisieren, zum Beispiel mit linearRampToValueAtTime().

Parameter

Name	Typ	Default	Beschreibung
$context Pflicht	BaseAudioContext		Der `AudioContext` oder `OfflineAudioContext`, zu dem der Knoten gehören soll.
$options	PannerOptions	{}	Optionales Objekt mit Anfangswerten: `panningModel` (`"equalpower"` \| `"HRTF"`, Standard `"equalpower"`), `distanceModel` (`"linear"` \| `"inverse"` \| `"exponential"`, Standard `"inverse"`), `positionX/Y/Z` (Standard `0`), `orientationX/Y/Z` (Standard `1, 0, 0`), `refDistance` (`1`), `maxDistance` (`10000`), `rolloffFactor` (`1`), `coneInnerAngle` (`360`), `coneOuterAngle` (`360`), `coneOuterGain` (`0`). Außerdem die allgemeinen Optionen `channelCount`, `channelCountMode` und `channelInterpretation`.

Rückgabewert

Typ

PannerNode

Beschreibung

Ein neuer PannerNode, der mit den angegebenen Optionen eingerichtet ist und noch mit Quelle und Ziel verbunden werden muss.

Beispiele

Oszillator im Raum rechts vom Hörer platzieren

const ctx = new AudioContext();

const osc = new OscillatorNode(ctx, { frequency: 440 });
const panner = new PannerNode(ctx, {
  panningModel: 'HRTF',
  distanceModel: 'inverse',
  positionX: 3,   // 3 Einheiten nach rechts
  positionY: 0,
  positionZ: -1   // leicht vor dem Hörer
});

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

document.querySelector('#play').addEventListener('click', async () => {
  await ctx.resume(); // Autoplay-Sperre aufheben
  osc.start();
  osc.stop(ctx.currentTime + 2);
});

console.log(panner.panningModel, panner.positionX.value);

HRTF 3

Schallquelle von links nach rechts bewegen

const ctx = new AudioContext();
const audio = document.querySelector('audio');
const source = new MediaElementAudioSourceNode(ctx, { mediaElement: audio });

const panner = new PannerNode(ctx, { panningModel: 'HRTF', positionX: -5 });
source.connect(panner).connect(ctx.destination);

const flyBy = (dauer = 4) => {
  const t = ctx.currentTime;
  panner.positionX.setValueAtTime(-5, t);
  panner.positionX.linearRampToValueAtTime(5, t + dauer);
};

audio.addEventListener('play', async () => {
  await ctx.resume();
  flyBy();
});

Gerichtete Quelle mit Abstrahlkegel und linearer Dämpfung

const ctx = new AudioContext();

const lautsprecher = new PannerNode(ctx, {
  distanceModel: 'linear',
  refDistance: 1,
  maxDistance: 20,
  rolloffFactor: 1,
  coneInnerAngle: 60,   // volle Lautstärke im 60°-Kegel
  coneOuterAngle: 180,
  coneOuterGain: 0.1,   // außerhalb nur 10 %
  positionZ: -4,
  orientationX: 0,
  orientationY: 0,
  orientationZ: 1       // zeigt zum Hörer
});

// Hörer an den Ursprung setzen und nach vorne (-Z) blicken lassen
const { listener } = ctx;
if (listener.positionX) {
  listener.positionX.value = 0;
  listener.forwardZ.value = -1;
}

console.log(lautsprecher.coneInnerAngle, lautsprecher.distanceModel);

60 linear

// Wichtig · Fallstricke

Kompatibilität: Der Konstruktor funktioniert in allen aktuellen Browsern. Ältere Safari-Versionen (vor 14.1) kennen nur ctx.createPanner(). Dort gibt es auch keine positionX-AudioParams, nur die veraltete Methode setPosition(). Prüfe das bei Bedarf mit 'positionX' in PannerNode.prototype.
Autoplay: Ein AudioContext startet oft im Zustand \"suspended\". Rufe ctx.resume() in einem Handler für eine Nutzeraktion auf.
Leistung: \"HRTF\" klingt über Kopfhörer deutlich realistischer, braucht aber spürbar mehr Rechenleistung als \"equalpower\". Bei vielen gleichzeitigen Quellen solltest du sparsam damit umgehen.
Ungültige Werte: Ein negativer Wert für refDistance oder rolloffFactor löst einen RangeError aus. Dasselbe gilt für maxDistance ≤ 0 und für coneOuterGain außerhalb von 0–1.
Kanäle: channelCount darf höchstens 2 sein, channelCountMode nicht \"max\". Sonst wird ein NotSupportedError geworfen.
Beim Modell \"linear\" wird die Quelle ab maxDistance nicht leiser. Bei \"inverse\" und \"exponential\" wird sie nie ganz stumm.

Siehe auch

new BiquadFilterNode() new GainNode() new AnalyserNode() new ConvolverNode() new DelayNode()