PannerNode.refDistance — Eigenschaft · JavaScript-Referenz

Signatur

PannerNode.refDistance

Beschreibung

Die Eigenschaft refDistance eines PannerNode ist eine Gleitkommazahl (double). Sie legt die Referenzdistanz fest, die das Distanzmodell (distanceModel) für die Lautstärkedämpfung verwendet. Ist die Quelle näher am Zuhörer als dieser Wert oder genau so weit entfernt, wird die Lautstärke nicht abgesenkt (Verstärkungsfaktor 1). Erst jenseits von refDistance wird die Lautstärke gemäß Modell und rolloffFactor reduziert.

Der Standardwert ist 1. Die Einheit ist beliebig, muss aber zu den Koordinaten passen, die du für positionX/Y/Z des Panners und des AudioListener verwendest (z. B. Meter in einer 3D-Szene).

Die Formeln der drei Distanzmodelle, mit d = auf mindestens refDistance begrenzte Distanz:

"inverse" (Standard): ref / (ref + rolloff * (d - ref))
"linear": 1 - rolloff * (d - ref) / (maxDistance - ref), wobei d zusätzlich auf maxDistance begrenzt wird
"exponential": (d / ref) ^ -rolloff

Mit einem größeren refDistance bleibt eine Quelle über eine größere Strecke in voller Lautstärke. Das eignet sich für laute oder großflächige Klangquellen wie Wasserfälle oder Maschinen. Kleine Werte passen zu leisen, punktförmigen Quellen.

Parameter

Name	Typ	Default	Beschreibung
$value	number	1	Beim Setzen: nicht-negative Referenzdistanz in der Einheit des Koordinatensystems. Negative Werte lösen einen `RangeError` aus.

Rückgabewert

Typ

number

Beschreibung

Die aktuelle Referenzdistanz als Gleitkommazahl (Standard 1).

Beispiele

Referenzdistanz lesen und setzen

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

console.log(panner.refDistance); // Standardwert

panner.refDistance = 5;
console.log(panner.refDistance);

1 5

Laute Klangquelle in einer 3D-Szene platzieren

const ctx = new AudioContext();

const panner = new PannerNode(ctx, {
  panningModel: 'HRTF',
  distanceModel: 'inverse',
  refDistance: 10,   // bis 10 m in voller Lautstärke
  rolloffFactor: 1,
  maxDistance: 500,
  positionX: 0,
  positionY: 0,
  positionZ: -30
});

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

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

Dämpfung für verschiedene refDistance-Werte berechnen (Modell inverse)

const inverseGain = (d, ref, rolloff = 1) => {
  const dist = Math.max(d, ref);
  return ref / (ref + rolloff * (dist - ref));
};

for (const ref of [1, 5, 10]) {
  console.log(`ref=${ref}:`, inverseGain(20, ref).toFixed(3));
}

ref=1: 0.050 ref=5: 0.250 ref=10: 0.500

Ungültige Werte abfangen

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

try {
  panner.refDistance = -2;
} catch (err) {
  console.log(err.name);
}
console.log(panner.refDistance);

RangeError 1

// Wichtig · Fallstricke

Negative Werte lösen einen RangeError aus, der bisherige Wert bleibt erhalten. Ältere Browser haben negative Werte teilweise stillschweigend übernommen.
Beim Modell "exponential" bewirkt refDistance = 0 eine Division durch null. Nutze dort immer einen positiven Wert. Beim Modell "linear" muss refDistance kleiner als maxDistance sein, sonst gibt es keine sinnvolle Dämpfung.
refDistance ist anders als positionX kein AudioParam. Eine Automatisierung mit setValueAtTime() o. Ä. ist nicht möglich. Änderungen greifen sofort.
Die Einheit muss zu den Positionswerten von Panner und AudioListener passen. Wenn die Skalierung nicht stimmt, klingen Quellen oft unerwartet leise oder laut.
Browserunterstützung: in allen modernen Browsern verfügbar. Der AudioContext startet wegen der Autoplay-Richtlinien meist erst nach einer Nutzerinteraktion (ctx.resume()).

Siehe auch

PannerNode PannerNode.maxDistance PannerNode.rolloffFactor PannerNode.distanceModel AudioListener BaseAudioContext.createPanner() PannerNode.orientationX