PannerNode.coneOuterGain — Eigenschaft · JavaScript-Referenz

Signatur

PannerNode.coneOuterGain

Beschreibung

Mit coneOuterGain legst du fest, wie laut eine gerichtete Schallquelle klingt, wenn sich der Hörer (AudioListener) außerhalb ihres äußeren Abstrahlkegels befindet. Der Wert ist ein double im Bereich von 0 bis 1 und wird linear angegeben, also nicht in Dezibel. Der Standardwert ist 0: Außerhalb des äußeren Kegels ist die Quelle dann komplett stumm.

Die Abstrahlcharakteristik einer PannerNode ergibt sich aus drei Eigenschaften, die zusammenwirken:

innerhalb von coneInnerAngle: volle Lautstärke (Faktor 1),
zwischen coneInnerAngle und coneOuterAngle: ein linearer Übergang von 1 zu coneOuterGain,
außerhalb von coneOuterAngle: konstant coneOuterGain.

Welcher Winkel gilt, hängt von der Ausrichtung der Quelle (orientationX/Y/Z) und von der Position des Hörers relativ zur Quelle ab. Typische Einsatzfälle sind Lautsprecher, sprechende Figuren oder Megafone in Spielen und 3D-Szenen: Steht man hinter der Quelle, soll sie gedämpft klingen, aber nicht unbedingt ganz verstummen. Ein Wert wie 0.1 bis 0.3 ist dafür oft realistischer als der Standardwert 0.

Parameter

Name	Typ	Default	Beschreibung
$value	number	0	Wird beim Setzen zugewiesen: linearer Verstärkungsfaktor im Bereich `[0, 1]`. Werte außerhalb dieses Bereichs lösen eine Ausnahme aus.

Rückgabewert

Typ

number

Beschreibung

Der aktuelle lineare Verstärkungsfaktor außerhalb des äußeren Kegels (0 bis 1, Standardwert 0).

Beispiele

Gerichtete Schallquelle mit gedämpfter Rückseite

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

// Kegel definieren: voll hörbar in 60°, Übergang bis 180°
panner.coneInnerAngle = 60;
panner.coneOuterAngle = 180;
panner.coneOuterGain = 0.2; // hinter der Quelle noch 20 % Lautstärke

// Quelle zeigt vom Hörer weg (Hörer steht hinter ihr)
panner.positionZ.value = -2;
panner.orientationZ.value = -1;

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

console.log(panner.coneOuterGain);

0.2

Kegel direkt im Konstruktor konfigurieren

const ctx = new AudioContext();

const panner = new PannerNode(ctx, {
  panningModel: 'HRTF',
  coneInnerAngle: 90,
  coneOuterAngle: 220,
  coneOuterGain: 0.35,
  positionX: 3,
  orientationX: -1 // zeigt in Richtung Hörer
});

console.log(panner.coneInnerAngle, panner.coneOuterAngle, panner.coneOuterGain);

90 220 0.35

Wert per Schieberegler ändern und Fehler abfangen

const ctx = new AudioContext();
const panner = ctx.createPanner();
panner.coneInnerAngle = 45;
panner.coneOuterAngle = 160;

const setOuterGain = (value) => {
  try {
    panner.coneOuterGain = value;
    console.log('coneOuterGain =', panner.coneOuterGain);
  } catch (err) {
    console.warn(`Ungültiger Wert ${value}: ${err.name}`);
  }
};

setOuterGain(0.5);
setOuterGain(1.5); // außerhalb von [0, 1]

coneOuterGain = 0.5 Ungültiger Wert 1.5: InvalidStateError

// Wichtig · Fallstricke

Wertebereich: Laut Spezifikation löst ein Wert außerhalb von [0, 1] einen InvalidStateError aus. Ältere Browserversionen haben solche Werte teilweise stillschweigend übernommen. Prüfe Benutzereingaben deshalb am besten vorher selbst.
Keine Wirkung ohne Kegel: Der Standardwert von coneInnerAngle und coneOuterAngle ist jeweils 360. Damit ist die Quelle rundstrahlend und coneOuterGain wirkt sich nicht aus. Verkleinere zuerst die Winkel.
Linear, nicht in dB: 0.5 entspricht ungefähr −6 dB, nicht der halben wahrgenommenen Lautheit.
Keine AudioParam: Anders als positionX oder orientationX ist coneOuterGain eine einfache Zahl. Automatisierungen wie linearRampToValueAtTime() sind nicht möglich. Für weiche Übergänge brauchst du stattdessen eine nachgeschaltete GainNode.
Standardwert 0: Außerhalb des äußeren Kegels ist die Quelle standardmäßig stumm. Das überrascht oft, wenn man nur die Winkel setzt.
Die Eigenschaft wird in allen modernen Browsern unterstützt (Chrome, Edge, Firefox, Safari).

Siehe auch

PannerNode.coneInnerAngle PannerNode.coneOuterAngle PannerNode.orientationX PannerNode.orientationY PannerNode.orientationZ