MediaTrackSettings.echoCancellation — Eigenschaft · JavaScript-Referenz

Signatur

MediaTrackSettings.echoCancellation

Beschreibung

Die Eigenschaft echoCancellation des Wörterbuchs MediaTrackSettings zeigt den tatsächlich angewendeten Zustand der Echo-Unterdrückung einer Audiospur (MediaStreamTrack) an. Sie erhalten das Objekt über track.getSettings(). Ist der Wert true, versucht der Browser bzw. das Betriebssystem, den Ton, der aus den Lautsprechern kommt und vom Mikrofon wieder aufgenommen wird, aus dem Eingangssignal herauszufiltern.

Wichtig ist der Unterschied zwischen Einschränkung und Einstellung: Mit getUserMedia({ audio: { echoCancellation: true } }) oder track.applyConstraints() äußern Sie nur einen Wunsch. Was der Browser daraus macht, sehen Sie erst in getSettings().echoCancellation. Der Browser kann eine Anfrage ignorieren, wenn Hardware oder Plattform die Funktion nicht anbieten.

Typische Anwendungsfälle:

Videokonferenzen und Sprachchat (WebRTC): Hier sollte die Echo-Unterdrückung aktiv sein, sonst hören Gesprächspartner sich selbst.
Musik- und Aufnahme-Apps: Hier schaltet man sie meist zusammen mit noiseSuppression und autoGainControl ab, weil die Filter das Signal hörbar verändern.

Bei Videospuren gibt es die Eigenschaft nicht, sie ist dann undefined.

Rückgabewert

Typ

boolean | undefined

Beschreibung

true, wenn die Echo-Unterdrückung aktiv ist, sonst false. undefined, wenn es sich um keine Audiospur handelt oder der Browser die Eigenschaft nicht meldet.

Beispiele

Aktuellen Zustand nach getUserMedia auslesen

const pruefeEcho = async () => {
  const stream = await navigator.mediaDevices.getUserMedia({
    audio: { echoCancellation: true }
  });
  const [track] = stream.getAudioTracks();
  const { echoCancellation } = track.getSettings();
  console.log(`Echo-Unterdrückung aktiv: ${echoCancellation}`);
};

pruefeEcho().catch(console.error);

Echo-Unterdrückung aktiv: true

Für Musikaufnahmen alle Audiofilter abschalten und prüfen

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

  if (settings.echoCancellation) {
    console.warn('Browser hat die Echo-Unterdrückung trotzdem aktiviert.');
  } else {
    console.log('Rohsignal ohne Echo-Unterdrückung.');
  }
  return stream;
};

starteRohaufnahme();

Rohsignal ohne Echo-Unterdrückung.

Zur Laufzeit umschalten mit applyConstraints()

const schalteEcho = async (track, aktiv) => {
  const unterstuetzt = navigator.mediaDevices
    .getSupportedConstraints().echoCancellation;
  if (!unterstuetzt) {
    console.log('echoCancellation wird nicht unterstützt.');
    return;
  }
  await track.applyConstraints({ echoCancellation: aktiv });
  console.log('Neuer Zustand:', track.getSettings().echoCancellation);
};

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

Neuer Zustand: false

// Wichtig · Fallstricke

Einstellung ≠ Einschränkung: Verlassen Sie sich nie darauf, dass eine angefragte Einschränkung auch gilt. Prüfen Sie immer mit getSettings(). Mit { exact: false } erzwingen Sie den Wert. Ist das nicht möglich, schlägt getUserMedia() mit OverconstrainedError fehl.
Umschalten zur Laufzeit: Nicht jeder Browser kann die Echo-Unterdrückung per applyConstraints() an einer laufenden Spur ändern. Manchmal muss die Spur neu angefordert werden. Das gilt besonders für Safari und Firefox.
Kombinierte Filter: In Chrome hängen echoCancellation, noiseSuppression und autoGainControl intern zusammen. Wenn Sie nur einen Filter abschalten, kann das Ergebnis trotzdem verarbeitet klingen.
Kompatibilität: Wird von allen modernen Browsern unterstützt. Nur in sicherem Kontext (HTTPS) verfügbar und erst nach Zustimmung des Nutzers zum Mikrofonzugriff. Neuere Entwürfe der Spezifikation sehen zusätzlich die Zeichenketten-Werte "all" und "remote-only" vor. Diese werden bisher kaum unterstützt, prüfen Sie also defensiv auf true bzw. einen Wert, der als wahr gilt.
Bei Videospuren ist der Wert undefined.

Siehe auch

MediaTrackSettings.channelCount MediaTrackSettings.screenPixelRatio MediaTrackSettings.aspectRatio MediaTrackSettings.autoGainControl MediaTrackSettings.frameRate