GainNode.gain — Eigenschaft · JavaScript-Referenz

Signatur

GainNode.gain

Beschreibung

Die Eigenschaft gain eines GainNode gibt ein AudioParam-Objekt zurück, das den linearen Verstärkungsfaktor steuert. Jedes Sample des Eingangssignals wird mit diesem Wert multipliziert: 1 lässt das Signal unverändert, 0.5 halbiert die Amplitude (ca. −6 dB), 0 schaltet stumm und negative Werte invertieren die Phase.

Da es sich um einen a-rate-Parameter handelt, wird der Wert für jedes einzelne Sample neu berechnet. Deshalb eignet er sich ideal für sanfte Ein- und Ausblendungen, Hüllkurven (ADSR), Tremolo-Effekte oder Crossfades zwischen Quellen. Änderungen plant man am besten mit den Automatisierungsmethoden wie setValueAtTime(), linearRampToValueAtTime(), exponentialRampToValueAtTime() oder setTargetAtTime().

Die Eigenschaft selbst ist schreibgeschützt – man ersetzt also nicht das AudioParam, sondern setzt dessen value oder plant Automationen. Außerdem kann ein anderer AudioNode (z. B. ein OscillatorNode als LFO) direkt mit gain verbunden werden, um den Wert zu modulieren.

Rückgabewert

Typ

AudioParam

Beschreibung

Ein a-rate AudioParam mit defaultValue 1, minValue ≈ -3.4028235e38 und maxValue ≈ 3.4028235e38 (größter Float32-Wert).

Beispiele

Lautstärke direkt setzen

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

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

console.log(gainNode.gain.value);        // 0.25
console.log(gainNode.gain.defaultValue); // 1

// Lautstärke zur Laufzeit ändern
gainNode.gain.value = 0.5;

0.25 1

Knackfreies Ein- und Ausblenden (Fade)

const ctx = new AudioContext();
const osc = ctx.createOscillator();
const gainNode = ctx.createGain();
osc.connect(gainNode).connect(ctx.destination);

const now = ctx.currentTime;
gainNode.gain.setValueAtTime(0, now);
gainNode.gain.linearRampToValueAtTime(0.8, now + 0.5); // Einblenden
gainNode.gain.setValueAtTime(0.8, now + 2);
gainNode.gain.linearRampToValueAtTime(0, now + 3);     // Ausblenden

osc.start(now);
osc.stop(now + 3);

Lautstärkeregler mit Slider und Dezibel-Umrechnung

const ctx = new AudioContext();
const audio = document.querySelector('audio');
const source = ctx.createMediaElementSource(audio);
const gainNode = new GainNode(ctx);
source.connect(gainNode).connect(ctx.destination);

const dbToGain = (db) => 10 ** (db / 20);

document.querySelector('#volume').addEventListener('input', (e) => {
  const db = Number(e.target.value); // z. B. -60 … 0
  // setTargetAtTime glättet Sprünge und verhindert Knacken
  gainNode.gain.setTargetAtTime(dbToGain(db), ctx.currentTime, 0.02);
  console.log(`${db} dB -> Faktor ${dbToGain(db).toFixed(3)}`);
});

-6 dB -> Faktor 0.501

Tremolo: Oszillator moduliert gain

const ctx = new AudioContext();
const carrier = new OscillatorNode(ctx, { frequency: 330 });
const amp = new GainNode(ctx, { gain: 0.5 });
const lfo = new OscillatorNode(ctx, { frequency: 5 });
const lfoDepth = new GainNode(ctx, { gain: 0.3 });

// LFO-Signal wird zum Grundwert 0.5 addiert: 0.2 … 0.8
lfo.connect(lfoDepth).connect(amp.gain);
carrier.connect(amp).connect(ctx.destination);

carrier.start();
lfo.start();

// Wichtig · Fallstricke

Linear, nicht logarithmisch: gain ist ein Amplitudenfaktor. Für gehörrichtige Regler Dezibel mit 10 ** (db / 20) umrechnen.
Knacken vermeiden: Abrupte Änderungen über gain.value = … erzeugen hörbare Klicks. Besser setTargetAtTime() oder Rampen verwenden.
Automation und value: Während Automationsereignisse geplant sind, wird ein Setzen von value ggf. ignoriert bzw. überschrieben. Vorher cancelScheduledValues() aufrufen.
exponentialRampToValueAtTime() darf nicht mit 0 als Ziel oder Startwert arbeiten (wirft RangeError) – stattdessen z. B. 0.0001 verwenden.
Übersteuerung: Werte deutlich über 1 können am Ausgang zu Clipping führen.
Autoplay: Browser starten einen AudioContext oft im Zustand suspended; erst nach Nutzerinteraktion mit ctx.resume() ist etwas hörbar.
Die Web Audio API wird von allen modernen Browsern unterstützt; der Konstruktor new GainNode() fehlt nur in sehr alten Versionen (dort ctx.createGain() nutzen).

Siehe auch

GPUShaderModule.label Gamepad.hand Gamepad.id Window.name Client.id