MediaTrackSettings.autoGainControl — Eigenschaft · JavaScript-Referenz

Signatur

MediaTrackSettings.autoGainControl

Beschreibung

Die Eigenschaft autoGainControl im Wörterbuch MediaTrackSettings gibt an, ob die automatische Verstärkungsregelung (Automatic Gain Control, AGC) auf einem Audiotrack gerade aktiv ist. Bei eingeschalteter AGC passt der Browser bzw. das Betriebssystem die Mikrofonlautstärke laufend an. Leise Sprache wird angehoben, laute Signale werden gedämpft.

Den Wert liest du über MediaStreamTrack.getSettings() aus. Er zeigt den tatsächlich angewendeten Zustand und nicht den Wunsch, den du per Einschränkung (MediaTrackConstraints.autoGainControl) angefordert hast. So kannst du prüfen, ob der Browser deine Anforderung umgesetzt hat.

Wichtig ist das vor allem für Anwendungen wie Musikaufnahme, Podcasting, Instrumenten-Tuner oder Audioanalyse. Dort verfälscht AGC die Dynamik, deshalb schaltet man sie meist ab. Bei Sprachanrufen und Videokonferenzen ist AGC dagegen meist erwünscht und oft voreingestellt.

Rückgabewert

Typ

boolean | undefined

Beschreibung

true, wenn AGC aktiv ist, false, wenn nicht. Die Eigenschaft fehlt (undefined) bei Videotracks oder wenn der Browser bzw. das Gerät die Einstellung nicht meldet.

Beispiele

AGC-Status eines Mikrofontracks auslesen

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

console.log(`AGC aktiv: ${autoGainControl}`);

AGC aktiv: true

AGC für Musikaufnahme abschalten und prüfen

const stream = await navigator.mediaDevices.getUserMedia({
  audio: {
    autoGainControl: false,
    echoCancellation: false,
    noiseSuppression: false
  }
});
const [track] = stream.getAudioTracks();
const settings = track.getSettings();

if (settings.autoGainControl) {
  console.warn('Browser hat AGC trotz Anforderung aktiviert – Aufnahme kann verfälscht sein.');
} else {
  console.log('AGC deaktiviert – unverfälschte Dynamik.');
}

AGC deaktiviert – unverfälschte Dynamik.

AGC zur Laufzeit umschalten

const toggleAgc = async (track, enabled) => {
  // Wird die Einschränkung nicht unterstützt, wird sie ignoriert
  // oder applyConstraints wirft einen Fehler
  const supported = navigator.mediaDevices.getSupportedConstraints();
  if (!supported.autoGainControl) {
    console.log('autoGainControl wird nicht unterstützt');
    return;
  }
  await track.applyConstraints({ autoGainControl: enabled });
  console.log('Neuer Zustand:', track.getSettings().autoGainControl);
};

const stream = await navigator.mediaDevices.getUserMedia({ audio: true });
await toggleAgc(stream.getAudioTracks()[0], false);

Neuer Zustand: false

// Wichtig · Fallstricke

Nur lesbar über getSettings(): Wenn du den Wert im zurückgegebenen Objekt änderst, passiert nichts. Zum Ändern nimmst du getUserMedia()-Einschränkungen oder applyConstraints().
Nicht immer vorhanden: Bei Videotracks und bei manchen Geräten oder Browsern fehlt die Eigenschaft. Prüfe deshalb immer auf undefined. Mit navigator.mediaDevices.getSupportedConstraints().autoGainControl fragst du ab, ob der Browser die Einstellung grundsätzlich unterstützt.
Einstellungen hängen zusammen: In manchen Browsern, vor allem Chromium, hängen AGC, echoCancellation und noiseSuppression intern zusammen. Wird eine davon deaktiviert, kann sich das auf die anderen auswirken. Kontrolliere deshalb das Ergebnis immer mit getSettings().
Das Betriebssystem kann AGC selbst regeln: Manche Systeme, etwa macOS und einige Android-Geräte, oder die Treiber haben eine eigene Verstärkungsregelung. Die kann auch dann greifen, wenn der Browser false meldet.
Sichere Umgebung nötig: getUserMedia() funktioniert nur über HTTPS oder auf localhost, und der Nutzer muss den Mikrofonzugriff erlauben.

Siehe auch

MediaTrackSettings.echoCancellation MediaTrackSettings.aspectRatio MediaTrackSettings.channelCount MediaTrackSettings.cursor MediaTrackSettings.facingMode