PannerNode.distanceModel — Eigenschaft · JavaScript-Referenz

Signatur

PannerNode.distanceModel

Beschreibung

Die Eigenschaft distanceModel eines PannerNode bestimmt, wie stark eine Audioquelle leiser wird, wenn sie sich im 3D-Raum vom AudioListener entfernt. Sie ist lesbar und beschreibbar und akzeptiert einen von drei Zeichenketten-Werten. Der Standardwert ist "inverse".

"linear": Verstärkung = 1 - rolloffFactor * (d - refDistance) / (maxDistance - refDistance), wobei d auf den Bereich refDistance … maxDistance begrenzt wird. Ab maxDistance ist die Quelle (bei rolloffFactor = 1) stumm – ideal für Spiele mit klarer Hörweite.
"inverse": Verstärkung = refDistance / (refDistance + rolloffFactor * (max(d, refDistance) - refDistance)). Entspricht annähernd dem natürlichen Abfall und wird nie ganz still.
"exponential": Verstärkung = pow(max(d, refDistance) / refDistance, -rolloffFactor). Erlaubt über rolloffFactor einen sehr steilen oder sehr flachen Abfall.

Das Modell wirkt immer zusammen mit refDistance, maxDistance und rolloffFactor. Innerhalb von refDistance bleibt die Lautstärke bei allen Modellen unverändert (Verstärkung 1). Das Umschalten ist jederzeit während der Wiedergabe möglich.

Parameter

Name	Typ	Default	Beschreibung
$value	"linear" \| "inverse" \| "exponential"	"inverse"	Beim Setzen: der gewünschte Abschwächungs-Algorithmus (Enum `DistanceModelType`).

Rückgabewert

Typ

string

Beschreibung

Der aktuell gesetzte Algorithmus: "linear", "inverse" oder "exponential".

Beispiele

Standardwert auslesen und Modell setzen

const ctx = new AudioContext();
const panner = new PannerNode(ctx);

console.log(panner.distanceModel); // Standard

panner.distanceModel = 'linear';
panner.refDistance = 1;
panner.maxDistance = 50;
panner.rolloffFactor = 1;
console.log(panner.distanceModel);

inverse linear

Direkt im Konstruktor festlegen (Spiel mit fester Hörweite)

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

const panner = new PannerNode(ctx, {
  panningModel: 'HRTF',
  distanceModel: 'linear',
  refDistance: 2,
  maxDistance: 30,
  rolloffFactor: 1,
  positionX: 10,
  positionY: 0,
  positionZ: -5
});

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

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

Verstärkung der drei Modelle berechnen und vergleichen

// Nachbildung der Formeln aus der Web-Audio-Spezifikation
const gain = (model, d, { ref = 1, max = 10000, rolloff = 1 } = {}) => {
  switch (model) {
    case 'linear': {
      const dc = Math.min(Math.max(d, ref), max);
      return 1 - Math.min(rolloff, 1) * (dc - ref) / (max - ref);
    }
    case 'inverse':
      return ref / (ref + rolloff * (Math.max(d, ref) - ref));
    case 'exponential':
      return Math.pow(Math.max(d, ref) / ref, -rolloff);
  }
};

for (const model of ['linear', 'inverse', 'exponential']) {
  console.log(model, gain(model, 5, { max: 20 }).toFixed(3));
}

linear 0.789 inverse 0.200 exponential 0.200

Modell zur Laufzeit per Auswahlfeld umschalten

const ctx = new AudioContext();
const panner = new PannerNode(ctx, { positionZ: -8 });
const select = document.querySelector('#distance-model');

select.addEventListener('change', (event) => {
  panner.distanceModel = event.target.value;
  console.log('Neues Modell:', panner.distanceModel);
});

Neues Modell: exponential

// Wichtig · Fallstricke

Ungültige Werte: Wird ein Wert außerhalb des Enums gesetzt (z. B. "quadratic"), wird die Zuweisung ignoriert – ohne Fehlermeldung. Im Konstruktor-Options-Objekt führt ein ungültiger Wert dagegen zu einem TypeError.
Linear und rolloffFactor: Beim Modell "linear" wird rolloffFactor auf den Bereich 0–1 begrenzt; Werte größer als 1 haben keine zusätzliche Wirkung.
refDistance = 0: Bei "inverse" und "exponential" führt das zu Division durch Null bzw. zu Stille; refDistance sollte daher immer positiv sein.
Die Entfernungsdämpfung gilt unabhängig von panningModel ("equalpower" oder "HRTF").
Kompatibilität: In allen aktuellen Browsern unterstützt. Ältere Safari-Versionen brauchen ggf. webkitAudioContext. Der AudioContext startet erst nach einer Nutzerinteraktion (Autoplay-Richtlinie) – deshalb vorher ctx.resume() aufrufen.

Siehe auch

PannerNode PannerNode.refDistance PannerNode.maxDistance PannerNode.rolloffFactor PannerNode.panningModel AudioListener PannerNode.orientationX