DynamicsCompressorNode — Schnittstelle · JavaScript-Referenz

Signatur

interface DynamicsCompressorNode extends AudioNode

Beschreibung

DynamicsCompressorNode ist ein Knoten der Web Audio API, der die Dynamik eines Signals verringert. Überschreitet der Pegel den Schwellwert (threshold), wird er im Verhältnis ratio abgesenkt. So klingt eine Mischung aus vielen Quellen gleichmäßiger und das Clipping am Ausgang wird vermieden. Der Knoten hat genau einen Eingang und einen Ausgang.

Gesteuert wird der Kompressor über fünf AudioParam-Eigenschaften (nur lesbar, aber ihr .value ist veränderbar und automatisierbar):

threshold – Schwellwert in dB (−100 bis 0, Standard −24)
knee – weicher Übergangsbereich oberhalb des Schwellwerts in dB (0 bis 40, Standard 30)
ratio – Kompressionsverhältnis (1 bis 20, Standard 12)
attack – Zeit in Sekunden, um den Pegel um 10 dB abzusenken (0 bis 1, Standard 0,003)
release – Zeit in Sekunden, um den Pegel wieder um 10 dB anzuheben (0 bis 1, Standard 0,25)

Außerdem gibt es die nur lesbare Eigenschaft reduction (number, in dB, ≤ 0), die angibt, wie stark der Kompressor gerade absenkt – nützlich für eine Pegelanzeige. Erzeugt wird der Knoten mit new DynamicsCompressorNode(context, options) oder mit der Fabrikmethode BaseAudioContext.createDynamicsCompressor().

Typische Einsatzfälle sind ein Master-Limiter vor context.destination in Spielen oder Synthesizern, eine gleichmäßigere Lautstärke bei Sprachaufnahmen und der Schutz vor Lautstärkespitzen, wenn viele Klänge gleichzeitig abgespielt werden.

Parameter

Name	Typ	Default	Beschreibung
$context Pflicht	BaseAudioContext		Der `AudioContext` oder `OfflineAudioContext`, zu dem der Knoten gehört (Konstruktor).
$options	DynamicsCompressorOptions	{}	Optionales Objekt mit Anfangswerten: `threshold`, `knee`, `ratio`, `attack`, `release` sowie den allgemeinen `AudioNodeOptions` (`channelCount`, `channelCountMode`, `channelInterpretation`).

Rückgabewert

Typ

DynamicsCompressorNode

Beschreibung

Ein neuer Kompressor-Knoten, der sich per connect() in den Audiograph einbinden lässt.

Beispiele

Kompressor per Konstruktor erzeugen und einbinden

const ctx = new AudioContext();
const osc = new OscillatorNode(ctx, { type: 'sawtooth', frequency: 220 });

const compressor = new DynamicsCompressorNode(ctx, {
  threshold: -30,
  knee: 20,
  ratio: 8,
  attack: 0.005,
  release: 0.2
});

osc.connect(compressor).connect(ctx.destination);
osc.start();
osc.stop(ctx.currentTime + 2);

console.log(compressor.threshold.value, compressor.ratio.value);

-30 8

Master-Limiter für ein Audio-Element mit Fabrikmethode

const ctx = new AudioContext();
const audioEl = document.querySelector('audio');
const source = ctx.createMediaElementSource(audioEl);

const limiter = ctx.createDynamicsCompressor();
limiter.threshold.setValueAtTime(-6, ctx.currentTime);
limiter.knee.setValueAtTime(0, ctx.currentTime);
limiter.ratio.setValueAtTime(20, ctx.currentTime);
limiter.attack.setValueAtTime(0.001, ctx.currentTime);
limiter.release.setValueAtTime(0.1, ctx.currentTime);

source.connect(limiter).connect(ctx.destination);

// Autoplay-Richtlinie: Kontext erst nach Nutzerinteraktion fortsetzen
document.querySelector('#play').addEventListener('click', async () => {
  await ctx.resume();
  await audioEl.play();
});

Kompressor ein-/ausschalten und Absenkung anzeigen

const ctx = new AudioContext();
const source = new OscillatorNode(ctx, { frequency: 440 });
const compressor = new DynamicsCompressorNode(ctx, { threshold: -40, ratio: 12 });
source.start();

let active = false;
const toggle = () => {
  source.disconnect();
  compressor.disconnect();
  if (active) {
    source.connect(ctx.destination);
  } else {
    source.connect(compressor).connect(ctx.destination);
  }
  active = !active;
};

toggle(); // Kompressor aktiv

const meter = () => {
  console.log(`Absenkung: ${compressor.reduction.toFixed(1)} dB`);
  if (active) requestAnimationFrame(meter);
};
requestAnimationFrame(meter);

Absenkung: -9.8 dB (Wert variiert je nach Signal)

// Wichtig · Fallstricke

Browser-Kompatibilität: Wird von allen modernen Browsern unterstützt. Den Konstruktor new DynamicsCompressorNode() gibt es erst seit etwa 2017/2018; für sehr alte Browser (z. B. altes Safari mit webkitAudioContext) createDynamicsCompressor() verwenden.
reduction war früher ein AudioParam, heute ist es ein einfacher number-Wert. Also compressor.reduction statt compressor.reduction.value lesen. In älterem Code taucht noch die alte Form auf.
Die Eigenschaften threshold, ratio usw. sind AudioParams mit k-rate: Direkt zuweisen (compressor.ratio = 4) funktioniert nicht, der Wert muss über .value oder die Automatisierungsmethoden gesetzt werden. Werte außerhalb des erlaubten Bereichs werden auf die Grenzen beschnitten.
Der Kompressor arbeitet mit Vorausschau (Look-ahead), was eine kleine Latenz verursacht (in Chrome etwa 6 ms). Für die meisten Anwendungen spielt das keine Rolle, beim exakten Synchronisieren mit nicht komprimierten Signalen aber schon.
channelCount ist höchstens 2, und channelCountMode darf nicht "max" sein, sonst wird ein NotSupportedError ausgelöst.
Eine automatische Nachverstärkung (Make-up Gain) wird intern angewendet. Wer zusätzlich lauter oder leiser regeln will, hängt einen GainNode dahinter.
Wegen der Autoplay-Richtlinien startet ein AudioContext oft im Zustand "suspended" und muss nach einer Nutzerinteraktion mit resume() fortgesetzt werden.

Siehe auch

ScriptProcessorNode AnalyserNode WaveShaperNode ChannelMergerNode ConvolverNode