MediaTrackConstraints.autoGainControl — Eigenschaft · JavaScript-Referenz

Signatur

MediaTrackConstraints.autoGainControl

Beschreibung

Die Eigenschaft autoGainControl des Wörterbuchs MediaTrackConstraints steuert die automatische Verstärkungsregelung einer Mikrofonspur. Ist sie aktiv, passt der Browser bzw. das Betriebssystem die Eingangslautstärke laufend an, damit leise und laute Sprecher ungefähr gleich laut ankommen. Das ist bei Videokonferenzen und Sprachanrufen praktisch. Bei Musikaufnahmen, Podcasts oder Pegelmessungen stört es dagegen, weil Dynamik und Pegel verfälscht werden.

Der Wert ist ein ConstrainBoolean. Er kann ein einfaches true/false sein, das als Wunsch gilt. Oder er ist ein Objekt mit exact (zwingend) bzw. ideal (bevorzugt). Den Constraint übergibt man an navigator.mediaDevices.getUserMedia() unter audio oder nachträglich an MediaStreamTrack.applyConstraints().

Ob der Browser die Eigenschaft überhaupt unterstützt, prüft man mit navigator.mediaDevices.getSupportedConstraints().autoGainControl. Welcher Wert tatsächlich gilt, verrät track.getSettings().autoGainControl, und welche Werte das Gerät erlaubt, zeigt track.getCapabilities().autoGainControl.

Parameter

Name	Typ	Default	Beschreibung
$autoGainControl	boolean \| { exact?: boolean, ideal?: boolean }	abhängig vom Browser (meist true bei Audio-Aufnahmen)	`true`/`false` als Wunsch; `{ exact: … }` erzwingt den Wert (sonst `OverconstrainedError`); `{ ideal: … }` ist ein bevorzugter Wert.

Rückgabewert

Typ

boolean | ConstrainBooleanParameters

Beschreibung

Der hinterlegte Constraint-Wert. Ob die Regelung tatsächlich aktiv ist, verrät MediaStreamTrack.getSettings().autoGainControl (ein boolean).

Beispiele

Unverfälschte Aufnahme für Musik anfordern

const startRecording = async () => {
  const supported = navigator.mediaDevices.getSupportedConstraints();
  if (!supported.autoGainControl) {
    console.warn('autoGainControl wird nicht unterstützt');
  }

  const stream = await navigator.mediaDevices.getUserMedia({
    audio: {
      autoGainControl: false,
      echoCancellation: false,
      noiseSuppression: false
    }
  });

  const [track] = stream.getAudioTracks();
  console.log('AGC aktiv:', track.getSettings().autoGainControl);
  return stream;
};

startRecording();

AGC aktiv: false

Wert zwingend verlangen und Fehler abfangen

try {
  const stream = await navigator.mediaDevices.getUserMedia({
    audio: { autoGainControl: { exact: true } }
  });
  console.log('AGC erzwungen:', stream.getAudioTracks()[0].getSettings().autoGainControl);
} catch (err) {
  if (err.name === 'OverconstrainedError') {
    console.error('Gerät kann AGC nicht liefern:', err.constraint);
  } else {
    console.error(err);
  }
}

AGC erzwungen: true

AGC zur Laufzeit per applyConstraints umschalten

const stream = await navigator.mediaDevices.getUserMedia({ audio: true });
const [track] = stream.getAudioTracks();

const setAgc = async (enabled) => {
  await track.applyConstraints({ autoGainControl: enabled });
  console.log('Neuer Zustand:', track.getSettings().autoGainControl);
};

console.log('Fähigkeiten:', track.getCapabilities?.().autoGainControl);
await setAgc(false);

Fähigkeiten: [true, false] Neuer Zustand: false

// Wichtig · Fallstricke

Ein einfaches true/false ist nur ein Wunsch. Der Browser darf ihn ignorieren. Prüfe deshalb immer mit getSettings(), was tatsächlich gilt.
{ exact: … } kann in getUserMedia() und applyConstraints() einen OverconstrainedError auslösen, wenn das Gerät den Wert nicht liefern kann.
Manche Browser koppeln AGC, echoCancellation und noiseSuppression intern. Einzelne Werte zur Laufzeit zu ändern, klappt daher nicht überall zuverlässig. Setze sie deshalb am besten gleich beim Aufruf von getUserMedia().
Nur in sicheren Kontexten (HTTPS) und nach Freigabe des Mikrofons durch den Nutzer verfügbar. getCapabilities() fehlt in älteren Firefox-Versionen.
Nur für Audiospuren sinnvoll. Bei Videospuren wird der Constraint ignoriert.

Siehe auch

MediaTrackConstraints.echoCancellation MediaTrackConstraints.aspectRatio MediaTrackConstraints.channelCount MediaTrackConstraints.facingMode MediaTrackConstraints.latency