BaseAudioContext.createDynamicsCompressor() — Methode · JavaScript-Referenz

Signatur

BaseAudioContext.prototype.createDynamicsCompressor()

Beschreibung

Die Methode createDynamicsCompressor() von BaseAudioContext (und damit auch von AudioContext und OfflineAudioContext) erzeugt einen DynamicsCompressorNode. Ein Kompressor senkt die Lautstärke der lautesten Stellen eines Signals ab. Dadurch wird der Abstand zwischen leisen und lauten Stellen kleiner, und das digitale Clipping, also die Übersteuerung beim Mischen mehrerer Quellen, wird vermieden.

Typische Einsatzfälle sind Spiele und interaktive Anwendungen, in denen viele Klänge gleichzeitig abgespielt werden, außerdem Sprachaufnahmen mit schwankendem Pegel, Web-Synthesizer und das Mastering im Browser. Den Knoten setzt man meist ans Ende der Signalkette direkt vor context.destination.

Das Verhalten steuert man über die AudioParam-Eigenschaften threshold (dB), knee (dB), ratio, attack (Sekunden) und release (Sekunden). Die schreibgeschützte Eigenschaft reduction gibt die aktuelle Pegelabsenkung in dB zurück, zum Beispiel für eine Anzeige.

Anstelle dieser Fabrikmethode kann man auch den Konstruktor new DynamicsCompressorNode(context, options) verwenden. Damit lassen sich die Startwerte direkt beim Erzeugen übergeben.

Rückgabewert

Typ

DynamicsCompressorNode

Beschreibung

Ein neuer DynamicsCompressorNode mit diesen Standardwerten: threshold −24 dB, knee 30 dB, ratio 12, attack 0,003 s, release 0,25 s.

Beispiele

Kompressor zwischen Audio-Element und Ausgabe schalten

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

const compressor = ctx.createDynamicsCompressor();
compressor.threshold.setValueAtTime(-50, ctx.currentTime);
compressor.knee.setValueAtTime(40, ctx.currentTime);
compressor.ratio.setValueAtTime(12, ctx.currentTime);
compressor.attack.setValueAtTime(0, ctx.currentTime);
compressor.release.setValueAtTime(0.25, ctx.currentTime);

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

// AudioContext erst nach einer Benutzeraktion starten
document.querySelector('#play').addEventListener('click', async () => {
  await ctx.resume();
  audioEl.play();
});

Kompression per Checkbox ein- und ausschalten

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

source.connect(ctx.destination); // zunächst ohne Kompression

document.querySelector('#compress').addEventListener('change', (e) => {
  source.disconnect();
  compressor.disconnect();
  if (e.target.checked) {
    source.connect(compressor).connect(ctx.destination);
  } else {
    source.connect(ctx.destination);
  }
});

Pegelabsenkung beim Offline-Rendering messen

const ctx = new OfflineAudioContext(1, 44100, 44100);
const osc = ctx.createOscillator();
const gain = ctx.createGain();
gain.gain.value = 2; // bewusst übersteuert

const compressor = ctx.createDynamicsCompressor();
console.log(compressor.threshold.value, compressor.ratio.value);

osc.connect(gain).connect(compressor).connect(ctx.destination);
osc.start();

const buffer = await ctx.startRendering();
console.log(`Absenkung: ${compressor.reduction.toFixed(1)} dB`);
console.log(`Samples: ${buffer.length}`);

-24 12 Absenkung: -20.6 dB (Wert ungefähr) Samples: 44100

// Wichtig · Fallstricke

Autoplay-Richtlinie: Browser starten einen AudioContext oft im Zustand suspended. Rufen Sie ctx.resume() erst nach einer Benutzeraktion auf, zum Beispiel einem Klick.
Wertebereiche: threshold reicht von −100 bis 0 dB, knee von 0 bis 40 dB, ratio von 1 bis 20, attack von 0 bis 1 s und release von 0 bis 1 s. Werte außerhalb dieser Bereiche werden abgeschnitten.
reduction war in alten Chrome-Versionen ein AudioParam. Heute ist es eine einfache Zahl vom Typ float, also ohne .value lesen.
Ein Kompressor ist kein echter Limiter: Sehr schnelle Pegelspitzen können trotzdem kurz clippen. Für harte Begrenzung eignen sich eine hohe ratio, eine attack nahe 0 und ein vorgeschalteter GainNode.
Durch die interne Vorausschau (Look-ahead) entsteht eine kleine Latenz von einigen Millisekunden.
Kompatibilität: Die Methode wird in allen modernen Browsern unterstützt. Sehr alte WebKit-Versionen benötigen webkitAudioContext. Parameter mit setValueAtTime() zu setzen ist robuster als die direkte Zuweisung an .value.

Siehe auch

DynamicsCompressorNode BaseAudioContext AudioContext BaseAudioContext.createGain() BaseAudioContext.createBiquadFilter() AudioParam