Signatur
Beschreibung
Die Eigenschaft rolloffFactor eines PannerNode steuert, wie stark die Lautstärke einer Schallquelle mit zunehmender Entfernung vom AudioListener abnimmt. Mit Werten über 1 wird es schneller leise, mit Werten unter 1 langsamer. Bei 0 bleibt die Lautstärke unabhängig von der Entfernung gleich.
Wie sich der Wert auswirkt, hängt vom gewählten distanceModel ab. Dabei ist d die Entfernung, ref gleich refDistance und max gleich maxDistance:
"linear":1 - rolloffFactor * (d - ref) / (max - ref). Der Wert wird auf den Bereich[0, 1]begrenzt."inverse"(Standard):ref / (ref + rolloffFactor * (max(d, ref) - ref))"exponential":pow(max(d, ref) / ref, -rolloffFactor)
Einsatzgebiete sind 3D-Spiele, VR/WebXR-Anwendungen und räumliche Audio-Visualisierungen. So lassen sich etwa leise Umgebungsgeräusche weit hörbar machen (kleiner Faktor), während Schritte oder Stimmen schnell leiser werden (großer Faktor). Die Eigenschaft ist eine einfache Zahl und kein AudioParam. Man kann sie deshalb nicht mit setValueAtTime() o. Ä. zeitgesteuert verändern.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $value | number | 1 | Neuer Faktor beim Setzen. Er darf nicht negativ sein. Beim Modell "linear" ist er praktisch auf [0, 1] begrenzt, bei "inverse" und "exponential" gibt es keine Obergrenze. |
Rückgabewert
1).Beispiele
Faktor lesen und setzen
const ctx = new AudioContext();
const panner = new PannerNode(ctx, {
panningModel: 'HRTF',
distanceModel: 'inverse',
refDistance: 1,
maxDistance: 10000
});
console.log(panner.rolloffFactor); // Standardwert
// Quelle soll mit der Entfernung schneller leiser werden
panner.rolloffFactor = 2.5;
console.log(panner.rolloffFactor);Direkt im Konstruktor festlegen und Quelle anschließen
const ctx = new AudioContext();
const osc = new OscillatorNode(ctx, { frequency: 440 });
// Schwacher Abfall: Das Geräusch ist auch weit weg noch zu hören
const panner = new PannerNode(ctx, {
distanceModel: 'exponential',
rolloffFactor: 0.5,
positionX: 0,
positionY: 0,
positionZ: -20
});
osc.connect(panner).connect(ctx.destination);
document.querySelector('#play').addEventListener('click', async () => {
await ctx.resume();
osc.start();
osc.stop(ctx.currentTime + 2);
});Verstärkung abhängig von der Entfernung berechnen (Formeln der Spezifikation)
const distanceGain = ({ distanceModel, refDistance, maxDistance, rolloffFactor }, d) => {
switch (distanceModel) {
case 'linear': {
const r = Math.min(Math.max(rolloffFactor, 0), 1);
const dc = Math.min(Math.max(d, refDistance), maxDistance);
return 1 - r * (dc - refDistance) / (maxDistance - refDistance);
}
case 'inverse':
return refDistance / (refDistance + rolloffFactor * (Math.max(d, refDistance) - refDistance));
case 'exponential':
return Math.pow(Math.max(d, refDistance) / refDistance, -rolloffFactor);
}
};
const ctx = new AudioContext();
const panner = new PannerNode(ctx, { refDistance: 1, rolloffFactor: 2 });
for (const d of [1, 5, 10]) {
console.log(d, distanceGain(panner, d).toFixed(3));
}// Wichtig · Fallstricke
- Negative Werte lösen einen
RangeErroraus. Das gilt sowohl für die Zuweisung als auch für den Konstruktor. - Beim Modell
"linear"werden Werte über1auf1begrenzt. Ein höherer Faktor bewirkt dort also nichts mehr. rolloffFactorist keinAudioParam. Wer weiche Übergänge braucht, sollte zusätzlich einenGainNodeverwenden und dessengainautomatisieren.- Der Faktor wirkt erst ab
refDistance. Innerhalb dieses Abstands bleibt die Verstärkung bei1. - Kompatibilität: Die Eigenschaft wird von allen aktuellen Browsern unterstützt. Ältere Safari-Versionen benötigen
webkitAudioContext. Außerdem darf einAudioContexterst nach einer Nutzerinteraktion (z. B. einem Klick) Ton ausgeben.