MediaTrackConstraints.echoCancellation — Eigenschaft · JavaScript-Referenz

Signatur

MediaTrackConstraints.echoCancellation

Beschreibung

Die Eigenschaft echoCancellation des Wörterbuchs MediaTrackConstraints gibt an, ob der Browser für eine Audiospur, etwa ein Mikrofon, die akustische Echounterdrückung (AEC) aktivieren soll. Die Echounterdrückung entfernt Ton, der aus den eigenen Lautsprechern kommt und vom Mikrofon wieder aufgenommen wird. Ohne sie hört das Gegenüber bei Videokonferenzen und VoIP-Gesprächen seine eigene Stimme verzögert zurück.

Der Typ ist ConstrainBooleanOrDOMString. Du kannst also einen einfachen booleschen Wert angeben, der dann als ideal gilt, also als Wunsch. Alternativ übergibst du ein Objekt mit exact oder ideal. Mit exact wird die Einschränkung verpflichtend: Kann der Browser sie nicht erfüllen, schlägt getUserMedia() mit einem OverconstrainedError fehl. Neuere Fassungen der Spezifikation erlauben zusätzlich die Zeichenketten "all" (jeglichen Systemton unterdrücken) und "remote-only" (nur Ton von entfernten Gesprächspartnern unterdrücken).

In Browsern ist die Echounterdrückung bei Mikrofonzugriff meist standardmäßig aktiv. Abschalten solltest du sie vor allem bei Musik-Apps, Instrumenten-Stimmgeräten, Podcast-Aufnahmen mit Kopfhörern oder Audioanalyse. Dort verfälscht die Signalverarbeitung den Klang. Oft schaltet man dann auch noiseSuppression und autoGainControl ab.

Welcher Wert tatsächlich gilt, erfährst du über MediaStreamTrack.getSettings().echoCancellation. Ob der Browser die Einschränkung überhaupt kennt, prüfst du mit navigator.mediaDevices.getSupportedConstraints().

Parameter

Name	Typ	Default	Beschreibung
$echoCancellation	boolean \| string \| { exact?: boolean \| string, ideal?: boolean \| string }	meist true (browserabhängig)	`true`/`false` als Wunsch, `{ exact: … }` als Pflicht und `{ ideal: … }` ausdrücklich als Wunsch. Die Zeichenketten `"all"` und `"remote-only"` sind neuer und werden erst von wenigen Browsern unterstützt.

Rückgabewert

Typ

boolean | string | ConstrainBooleanParameters

Beschreibung

Der im Einschränkungsobjekt angegebene Wert. Den tatsächlich angewendeten Zustand liefert MediaTrackSettings.echoCancellation als boolean (oder Zeichenkette).

Beispiele

Mikrofon für einen Videoanruf mit Echounterdrückung anfordern

const startCall = async () => {
  const stream = await navigator.mediaDevices.getUserMedia({
    audio: {
      echoCancellation: true,
      noiseSuppression: true,
      autoGainControl: true
    }
  });
  const [track] = stream.getAudioTracks();
  console.log('Echounterdrückung aktiv:', track.getSettings().echoCancellation);
  return stream;
};

startCall().catch(err => console.error(err.name, err.message));

Echounterdrückung aktiv: true

Unverfälschte Aufnahme für eine Musik-App (Pflicht-Einschränkung)

const getRawMic = async () => {
  try {
    return await navigator.mediaDevices.getUserMedia({
      audio: {
        echoCancellation: { exact: false },
        noiseSuppression: false,
        autoGainControl: false
      }
    });
  } catch (err) {
    if (err.name === 'OverconstrainedError') {
      console.warn('Echounterdrückung lässt sich nicht abschalten:', err.constraint);
      // Rückfall: ohne harte Vorgabe erneut versuchen
      return navigator.mediaDevices.getUserMedia({ audio: { echoCancellation: false } });
    }
    throw err;
  }
};

const stream = await getRawMic();
console.log(stream.getAudioTracks()[0].getSettings().echoCancellation);

false

Unterstützung prüfen und zur Laufzeit per applyConstraints umschalten

const supported = navigator.mediaDevices.getSupportedConstraints();
if (!supported.echoCancellation) {
  console.log('echoCancellation wird nicht unterstützt');
}

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

// z. B. wenn der Nutzer Kopfhörer einsteckt
const setEchoCancellation = async (enabled) => {
  await track.applyConstraints({ echoCancellation: enabled });
  console.log('Neuer Wert:', track.getSettings().echoCancellation);
};

await setEchoCancellation(false);

Neuer Wert: false

// Wichtig · Fallstricke

Wunsch statt Pflicht: Ein einfaches true/false gilt nur als ideal. Der Browser darf davon abweichen. Prüfe den tatsächlichen Wert deshalb immer mit track.getSettings().
OverconstrainedError: Bei { exact: … } schlägt getUserMedia() bzw. applyConstraints() fehl, wenn das Gerät die Vorgabe nicht erfüllen kann. Plane dafür einen Rückfall ein.
Umschalten zur Laufzeit: Nicht jeder Browser ändert echoCancellation über applyConstraints() bei einer laufenden Spur zuverlässig. Unter Umständen musst du die Spur beenden und neu anfordern.
Zeichenketten-Werte: "all" und "remote-only" sind neu in der Spezifikation und werden bisher kaum unterstützt. Für breite Kompatibilität solltest du bei booleschen Werten bleiben.
Plattformunterschiede: Manche Betriebssysteme (z. B. iOS/macOS im Sprachmodus) bringen eine eigene Echounterdrückung mit. Sie lässt sich per Browser nicht immer vollständig abschalten.
Die Eigenschaft wirkt nur bei Audiospuren. Bei Videospuren wird sie ignoriert. getUserMedia() funktioniert außerdem nur in sicheren Kontexten (HTTPS oder localhost).

Siehe auch

MediaTrackConstraints.channelCount MediaTrackConstraints.aspectRatio MediaTrackConstraints.autoGainControl MediaTrackConstraints.frameRate MediaTrackConstraints.deviceId