Signatur
Beschreibung
Die Eigenschaft autoGainControl gehört zum Wörterbuch MediaTrackSupportedConstraints, das von navigator.mediaDevices.getSupportedConstraints() zurückgegeben wird. Ist sie vorhanden und hat den Wert true, kennt der User-Agent die gleichnamige Einschränkung autoGainControl. Mit ihr lässt sich bei Mikrofonaufnahmen die automatische Verstärkungsregelung (Automatic Gain Control, AGC) an- oder abschalten.
Die automatische Verstärkungsregelung gleicht Lautstärkeschwankungen aus. Leise Sprecher werden angehoben, laute gedämpft. Bei Sprachanrufen und Videokonferenzen ist das nützlich. Bei Musikaufnahmen, Messanwendungen oder Instrumenten-Stimmgeräten stört sie dagegen, weil sie die ursprüngliche Dynamik verfälscht.
Die Eigenschaft sagt nur aus, ob der Browser die Einschränkung versteht. Ob das konkrete Gerät oder die Plattform die Regelung auch umsetzt, verrät sie nicht. Das prüfen Sie nach dem Aufruf von getUserMedia() mit MediaStreamTrack.getSettings() oder getCapabilities(). Wird die Einschränkung nicht unterstützt, fehlt die Eigenschaft meist ganz. Sie ist dann nicht false, sondern undefined.
Rückgabewert
true, wenn der Browser die Einschränkung autoGainControl kennt. Wird sie nicht unterstützt, fehlt die Eigenschaft in der Regel (undefined).Beispiele
Unterstützung prüfen
const supported = navigator.mediaDevices.getSupportedConstraints();
if (supported.autoGainControl) {
console.log('autoGainControl wird unterstützt');
} else {
console.log('autoGainControl wird nicht unterstützt');
}AGC für Musikaufnahmen abschalten
const startMusicRecording = async () => {
const supported = navigator.mediaDevices.getSupportedConstraints();
const audio = {};
// Rohsignal: Verstärkungsregelung, Rauschunterdrückung und Echounterdrückung aus
if (supported.autoGainControl) audio.autoGainControl = false;
if (supported.noiseSuppression) audio.noiseSuppression = false;
if (supported.echoCancellation) audio.echoCancellation = false;
const stream = await navigator.mediaDevices.getUserMedia({
audio: Object.keys(audio).length ? audio : true
});
const [track] = stream.getAudioTracks();
console.log('Tatsächliche AGC-Einstellung:', track.getSettings().autoGainControl);
return stream;
};
startMusicRecording().catch(err => console.error(err.name, err.message));AGC zur Laufzeit per Umschalter ändern
const toggleAgc = async (track, enabled) => {
if (!navigator.mediaDevices.getSupportedConstraints().autoGainControl) {
console.warn('AGC nicht steuerbar');
return;
}
try {
await track.applyConstraints({ autoGainControl: enabled });
console.log('AGC jetzt:', track.getSettings().autoGainControl);
} catch (err) {
console.error('Konnte AGC nicht setzen:', err.name);
}
};
const stream = await navigator.mediaDevices.getUserMedia({ audio: true });
await toggleAgc(stream.getAudioTracks()[0], false);// Wichtig · Fallstricke
- Unterstützt heißt nicht wirksam:
truebedeutet nur, dass der Browser die Einschränkung kennt. Ob die Regelung tatsächlich aktiv ist, prüfen Sie mittrack.getSettings().autoGainControl. - Fehlend statt
false: Wird die Einschränkung nicht unterstützt, fehlt die Eigenschaft meist ganz. Prüfen Sie deshalb auf Wahrheitswert (if (supported.autoGainControl)) und nicht mit=== false. - Standardwert: Bei Audiospuren ist AGC in den meisten Browsern standardmäßig eingeschaltet. Für unverfälschte Aufnahmen müssen Sie sie ausdrücklich mit
falseanfordern. - Verwandte Verarbeitung: Einige Browser (z. B. ältere Chrome-Versionen) koppeln AGC intern an
echoCancellationundnoiseSuppression. Schalten Sie für ein Rohsignal alle drei ab. - Kompatibilität: Firefox unterstützt die Einschränkung seit Version 55, Chromium-Browser seit etwa Version 72. Safari unterstützt sie nur eingeschränkt.
getUserMedia()funktioniert nur in sicheren Kontexten (HTTPS oder localhost).