PannerNode.panningModel — Eigenschaft · JavaScript-Referenz

Signatur

PannerNode.panningModel

Beschreibung

Die Eigenschaft panningModel eines PannerNode bestimmt, mit welchem Verfahren die Web Audio API ein Signal anhand seiner Position relativ zum AudioListener auf die Ausgangskanäle verteilt. Sie ist lesbar und beschreibbar und nimmt einen der Aufzählungswerte "equalpower" oder "HRTF" an.

"equalpower" (Standardwert): ein einfaches Panning mit gleicher Leistung. Das Signal wird nach der Richtung zwischen linkem und rechtem Kanal verteilt. Das kostet wenig Rechenzeit, liefert aber kaum Informationen darüber, ob eine Quelle vorn, hinten, oben oder unten liegt.
"HRTF" (Head-Related Transfer Function): eine Faltung mit Impulsantworten, die an menschlichen Köpfen gemessen wurden. Damit lassen sich auch Quellen von vorn, hinten, oben und unten unterscheiden. Besonders über Kopfhörer wirkt das deutlich räumlicher, braucht aber spürbar mehr Rechenleistung.

Für Spiele, VR/AR-Anwendungen und immersive Audio-Erlebnisse, die mit Kopfhörern gehört werden, eignet sich "HRTF". Bei vielen gleichzeitigen Quellen, auf schwacher Hardware oder bei Wiedergabe über Lautsprecher ist "equalpower" meist die bessere Wahl.

Den Wert kannst du über die Eigenschaft, über die Option panningModel im Konstruktor new PannerNode(context, options) oder nach AudioContext.createPanner() setzen.

Parameter

Name	Typ	Default	Beschreibung
$value	"equalpower" \| "HRTF"	"equalpower"	Der gewünschte Algorithmus beim Setzen der Eigenschaft. Groß- und Kleinschreibung zählen: `"HRTF"` wird großgeschrieben, `"equalpower"` klein.

Beispiele

HRTF direkt im Konstruktor setzen

const ctx = new AudioContext();

const panner = new PannerNode(ctx, {
  panningModel: 'HRTF',
  distanceModel: 'inverse',
  positionX: 2,
  positionY: 0,
  positionZ: -1
});

const osc = new OscillatorNode(ctx, { frequency: 440 });
osc.connect(panner).connect(ctx.destination);
osc.start();

console.log(panner.panningModel);

HRTF

Modell nachträglich umschalten (z. B. Kopfhörer-Option)

const ctx = new AudioContext();
const panner = ctx.createPanner();
console.log(panner.panningModel); // Standardwert

const headphoneToggle = document.querySelector('#headphones');
headphoneToggle.addEventListener('change', (event) => {
  panner.panningModel = event.target.checked ? 'HRTF' : 'equalpower';
  console.log('Aktives Modell:', panner.panningModel);
});

equalpower Aktives Modell: HRTF

Ungültigen Wert abfangen

const ctx = new AudioContext();
const panner = ctx.createPanner();

panner.panningModel = 'hrtf'; // falsche Schreibweise
console.log(panner.panningModel); // bleibt unverändert

try {
  new PannerNode(ctx, { panningModel: 'surround' });
} catch (err) {
  console.log(err.name);
}

equalpower TypeError

Modell nach Anzahl der Quellen wählen

const ctx = new AudioContext();

const createSource = (buffer, x, z, totalSources) => {
  const source = new AudioBufferSourceNode(ctx, { buffer, loop: true });
  const panner = new PannerNode(ctx, {
    // Ab vielen Quellen auf das günstigere Modell wechseln
    panningModel: totalSources > 16 ? 'equalpower' : 'HRTF',
    positionX: x,
    positionZ: z
  });
  source.connect(panner).connect(ctx.destination);
  return { source, panner };
};

// Wichtig · Fallstricke

Ungültige Werte: Wenn du der Eigenschaft einen unbekannten String zuweist (z. B. "hrtf" in Kleinbuchstaben), wird er stillschweigend ignoriert, wie bei allen WebIDL-Aufzählungen. Im Konstruktor-Optionsobjekt löst derselbe Fehler dagegen einen TypeError aus.
Performance: "HRTF" arbeitet mit Faltung und braucht pro Quelle deutlich mehr Rechenzeit. Bei vielen gleichzeitigen Quellen oder auf Mobilgeräten kann das zu Aussetzern im Ton führen. Wenn es knackt, teste mit "equalpower".
Wiedergabe: Die Wirkung von HRTF kommt vor allem über Kopfhörer zur Geltung. Über Stereo-Lautsprecher klingt der Effekt oft verfärbt oder weniger überzeugend.
Latenz beim Umschalten: In manchen Browsern werden die HRTF-Datensätze erst beim ersten Einsatz geladen. Das Umschalten während der Wiedergabe kann deshalb kurz verzögert sein oder einen kleinen Klangsprung erzeugen.
Kompatibilität: Wird von allen modernen Browsern (Chrome, Edge, Firefox, Safari) unterstützt. Die genauen HRTF-Datensätze unterscheiden sich je nach Engine, daher klingt HRTF nicht in jedem Browser gleich. Für reines Stereo-Panning ohne 3D ist StereoPannerNode einfacher und günstiger.

Siehe auch

PannerNode.orientationY PannerNode.distanceModel PannerNode.maxDistance PannerNode.positionX PannerNode.positionY