new GainNode() — Methode · JavaScript-Referenz

Signatur

new GainNode(context, options)

Beschreibung

Der Konstruktor new GainNode() erzeugt einen GainNode, also einen AudioNode mit genau einem Eingang und einem Ausgang. Er multipliziert jedes eingehende Sample mit dem Wert seines AudioParam gain. Damit steuert man die Lautstärke, baut Ein- und Ausblendungen (Fades), Mischpulte oder Hüllkurven für Synthesizer.

Im Gegensatz zur älteren Fabrikmethode AudioContext.createGain() lassen sich beim Konstruktor gleich ein Startwert für gain und Kanal-Optionen übergeben. Beide Varianten liefern dasselbe Ergebnis. Der Konstruktor gilt als die modernere Form.

Der Wert von gain ist ein linearer Faktor: 1 lässt das Signal unverändert, 0.5 halbiert die Amplitude (ungefähr −6 dB), 0 schaltet stumm. Werte über 1 verstärken das Signal und können es übersteuern (Clipping). Negative Werte kehren die Phase um.

Parameter

Name	Typ	Default	Beschreibung
$context Pflicht	BaseAudioContext		Der `AudioContext` oder `OfflineAudioContext`, zu dem der Knoten gehören soll.
$options	GainOptions	{}	Optionales Objekt mit folgenden Eigenschaften: `gain` (`number`, Standard `1.0`): Startwert der Verstärkung `channelCount` (`number`) `channelCountMode` (`"max"\|"clamped-max"\|"explicit"`) `channelInterpretation` (`"speakers"\|"discrete"`)

Rückgabewert

Typ

GainNode

Beschreibung

Ein neues GainNode-Objekt. Seine Eigenschaft gain ist ein AudioParam vom Typ a-rate.

Beispiele

Oszillator mit halber Lautstärke abspielen

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

// Graph verbinden: Oszillator -> Gain -> Lautsprecher
osc.connect(gain).connect(ctx.destination);
osc.start();
osc.stop(ctx.currentTime + 1);

console.log(gain.gain.value);

0.5

Weiches Ausblenden (Fade-out) ohne Knacken

const ctx = new AudioContext();
const audio = document.querySelector('audio');
const source = new MediaElementAudioSourceNode(ctx, { mediaElement: audio });
const gain = new GainNode(ctx);
source.connect(gain).connect(ctx.destination);

const fadeOut = (seconds = 2) => {
  const now = ctx.currentTime;
  gain.gain.cancelScheduledValues(now);
  gain.gain.setValueAtTime(gain.gain.value, now);
  gain.gain.linearRampToValueAtTime(0, now + seconds);
};

document.querySelector('#fade').addEventListener('click', async () => {
  await ctx.resume();
  fadeOut(3);
});

Lautstärkeregler mit Dezibel-Umrechnung

const ctx = new AudioContext();
const master = new GainNode(ctx, { gain: 1 });
master.connect(ctx.destination);

// Dezibel in linearen Faktor umrechnen
const dbToGain = (db) => 10 ** (db / 20);

const slider = document.querySelector('#volume'); // <input type="range" min="-60" max="0">
slider.addEventListener('input', () => {
  const value = dbToGain(Number(slider.value));
  // setTargetAtTime glättet Sprünge
  master.gain.setTargetAtTime(value, ctx.currentTime, 0.02);
});

console.log(dbToGain(-6).toFixed(3));

0.501

// Wichtig · Fallstricke

Knacken vermeiden: Wenn man gain.value direkt setzt, springt der Wert sofort, und man hört oft ein Klicken. Für hörbare Änderungen besser setTargetAtTime(), linearRampToValueAtTime() oder exponentialRampToValueAtTime() verwenden. Achtung: Exponentielle Rampen dürfen nicht bei 0 beginnen oder enden. Stattdessen einen kleinen Wert wie 0.0001 nehmen.
Linear statt dB: gain ist ein Faktor und kein Dezibel-Wert. Das menschliche Gehör nimmt Lautstärke logarithmisch wahr. Deshalb sollten Regler in dB arbeiten und den Wert umrechnen.
Clipping: Werte über 1 können am Ausgang übersteuern. Bei Bedarf einen DynamicsCompressorNode nachschalten.
Autoplay-Richtlinien: Ein AudioContext startet in vielen Browsern im Zustand suspended. ctx.resume() muss dann nach einer Nutzeraktion aufgerufen werden.
Kompatibilität: Die Konstruktor-Form wird in allen aktuellen Browsern unterstützt. Sehr alte Versionen (z. B. Safari vor 14.1) kennen nur createGain(). Wenn solche Versionen unterstützt werden müssen, sollte man auf die Fabrikmethode zurückgreifen.
Ist context kein gültiger BaseAudioContext, wirft der Konstruktor einen TypeError.

Siehe auch

GainNode BaseAudioContext.createGain() AudioParam AudioNode.connect() AudioContext new CSSScale()