Signatur
Beschreibung
Die Methode createGain() eines AudioContext oder OfflineAudioContext erzeugt einen neuen GainNode. Das Signal, das durch diesen Knoten läuft, wird mit dem Wert von gain multipliziert. Ein Wert von 1 lässt das Signal unverändert, 0 schaltet es stumm, 0.5 halbiert die Amplitude und Werte größer als 1 verstärken das Signal.
Man setzt einen GainNode typischerweise zwischen eine Quelle (z. B. AudioBufferSourceNode, OscillatorNode oder MediaElementAudioSourceNode) und das Ziel context.destination ein. Häufige Einsatzgebiete sind ein Master-Lautstärkeregler, Stummschalten, Überblendungen (Crossfades), Hüllkurven (ADSR) bei Synthesizern oder das Mischen mehrerer Spuren mit eigener Kanal-Lautstärke.
Die Eigenschaft gain ist ein AudioParam. Deshalb lässt sie sich nicht nur direkt über gain.value setzen, sondern auch zeitgenau über Methoden wie setValueAtTime(), linearRampToValueAtTime(), exponentialRampToValueAtTime() oder setTargetAtTime() automatisieren. So vermeidet man hörbare Knackser bei abrupten Lautstärkeänderungen.
Als moderne Alternative kann der Knoten auch direkt über den Konstruktor new GainNode(context, { gain: 0.5 }) erzeugt werden, was zusätzlich das Setzen von Startoptionen erlaubt.
Rückgabewert
GainNode mit einem Eingang und einem Ausgang; der Standardwert von gain.value ist 1.Beispiele
Einfacher Lautstärkeregler für einen Oszillator
const ctx = new AudioContext();
const osc = ctx.createOscillator();
const gainNode = ctx.createGain();
gainNode.gain.value = 0.2; // 20 % Lautstärke
osc.connect(gainNode).connect(ctx.destination);
osc.start();
osc.stop(ctx.currentTime + 1); // nach 1 Sekunde stoppen
console.log(gainNode.gain.value);Lautstärke-Slider für ein <audio>-Element
// HTML: <audio id="player" src="musik.mp3" controls></audio>
// <input id="volume" type="range" min="0" max="1" step="0.01" value="1">
const ctx = new AudioContext();
const audioEl = document.querySelector('#player');
const slider = document.querySelector('#volume');
const source = ctx.createMediaElementSource(audioEl);
const master = ctx.createGain();
source.connect(master).connect(ctx.destination);
// Autoplay-Richtlinie: Kontext erst nach Nutzerinteraktion fortsetzen
audioEl.addEventListener('play', () => ctx.resume());
slider.addEventListener('input', () => {
// sanfter Übergang ohne Knacken
master.gain.setTargetAtTime(Number(slider.value), ctx.currentTime, 0.02);
});Weiches Ein- und Ausblenden (Fade-In/Fade-Out)
const ctx = new AudioContext();
const playTone = (freq = 440, dauer = 2) => {
const osc = new OscillatorNode(ctx, { frequency: freq });
const env = ctx.createGain();
const t = ctx.currentTime;
env.gain.setValueAtTime(0.0001, t);
env.gain.exponentialRampToValueAtTime(0.5, t + 0.1); // Fade-In
env.gain.setValueAtTime(0.5, t + dauer - 0.3);
env.gain.exponentialRampToValueAtTime(0.0001, t + dauer); // Fade-Out
osc.connect(env).connect(ctx.destination);
osc.start(t);
osc.stop(t + dauer);
};
document.querySelector('button').addEventListener('click', async () => {
await ctx.resume();
playTone(330, 2);
});// Wichtig · Fallstricke
- Knackser vermeiden: Direktes Setzen von
gain.valuewährend der Wiedergabe kann hörbare Klicks erzeugen. BessersetTargetAtTime()oderlinearRampToValueAtTime()verwenden. - Exponentielle Rampen:
exponentialRampToValueAtTime()akzeptiert weder0als Ziel noch als Startwert (wirftRangeError) – stattdessen einen sehr kleinen Wert wie0.0001nutzen. - Übersteuerung: Werte über
1können zu Clipping (Verzerrung) am Ausgang führen, wenn die Summe der Signale den Bereich −1 bis 1 überschreitet. - Autoplay-Richtlinien: Browser starten einen
AudioContextmeist im Zustandsuspended; erst nach einer Nutzergeste mitctx.resume()ist etwas zu hören. - Kompatibilität: In allen modernen Browsern verfügbar. Sehr alte WebKit-Versionen kannten nur
webkitAudioContextund die veraltete MethodecreateGainNode(). Der Konstruktornew GainNode()wird in älteren Safari-Versionen (vor 14.1) nicht unterstützt –createGain()ist daher die sicherere Variante.