MediaTrackConstraints.latency — Eigenschaft · JavaScript-Referenz

Signatur

MediaTrackConstraints.latency

Beschreibung

Die Eigenschaft latency des Wörterbuchs MediaTrackConstraints legt fest, welche Latenz eine Audiospur haben soll. Gemeint ist die Zeit zwischen der Aufnahme des Signals und dem Moment, in dem es zur Verarbeitung bereitsteht. Die Angabe erfolgt in Sekunden als Gleitkommazahl, zum Beispiel 0.01 für 10 ms. Diese Einschränkung gilt nur für Audiospuren.

Der Wert ist ein ConstrainDouble. Er kann eine einfache Zahl sein, die als Wunschwert gilt, oder ein Objekt mit den Schlüsseln min, max, ideal und exact. Mit ideal und einer einfachen Zahl nennt man nur einen Wunsch. Der Browser wählt dann den nächstmöglichen Wert. Mit exact, min und max legt man dagegen harte Grenzen fest. Wenn das Gerät sie nicht einhalten kann, schlägt getUserMedia() bzw. applyConstraints() mit einem OverconstrainedError fehl.

Eine niedrige Latenz ist vor allem bei Echtzeitanwendungen wichtig, etwa bei Musik-Apps, Live-Monitoring, Sprachsteuerung oder VoIP. Eine höhere Latenz erlaubt größere Puffer und macht die Übertragung stabiler, zum Beispiel bei reinen Aufnahmen. Welchen Wert der Browser tatsächlich eingestellt hat, liest man mit MediaStreamTrack.getSettings().latency aus.

Parameter

Name	Typ	Default	Beschreibung
$latency	number \| { min?: number, max?: number, ideal?: number, exact?: number }		Latenz in Sekunden. Eine einfache Zahl gilt als `ideal`. `exact`, `min` und `max` sind harte Anforderungen.

Rückgabewert

Typ

number | ConstrainDoubleRange

Beschreibung

Die Einschränkung, die im Constraints-Objekt angegeben wurde. Den tatsächlich eingestellten Wert liefert getSettings().latency.

Beispiele

Mikrofon mit möglichst niedriger Latenz anfordern

const holeMikrofon = async () => {
  const stream = await navigator.mediaDevices.getUserMedia({
    audio: {
      latency: { ideal: 0.01 }, // Wunsch: 10 ms
      echoCancellation: false
    }
  });
  const [track] = stream.getAudioTracks();
  console.log('Tatsächliche Latenz:', track.getSettings().latency);
  return stream;
};

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

Tatsächliche Latenz: 0.01

Harte Obergrenze mit Fehlerbehandlung

const starteLiveMonitoring = async () => {
  try {
    const stream = await navigator.mediaDevices.getUserMedia({
      audio: { latency: { max: 0.02 } } // höchstens 20 ms
    });
    console.log('Monitoring aktiv');
    return stream;
  } catch (err) {
    if (err.name === 'OverconstrainedError') {
      console.warn(`Einschränkung nicht erfüllbar: ${err.constraint}`);
      // Ausweichen auf einen reinen Wunschwert
      return navigator.mediaDevices.getUserMedia({ audio: { latency: 0.02 } });
    }
    throw err;
  }
};

starteLiveMonitoring();

Monitoring aktiv

Unterstützung prüfen und Einschränkung nachträglich ändern

const passeLatenzAn = async (track, sekunden) => {
  const unterstuetzt = navigator.mediaDevices.getSupportedConstraints();
  if (!unterstuetzt.latency) {
    console.log('latency wird nicht unterstützt');
    return;
  }
  const { latency } = track.getCapabilities?.() ?? {};
  console.log('Möglicher Bereich:', latency);
  await track.applyConstraints({ latency: { ideal: sekunden } });
  console.log('Neu:', track.getSettings().latency);
};

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

Möglicher Bereich: { min: 0.01, max: 0.1 } Neu: 0.05

// Wichtig · Fallstricke

Einheit: Die Werte stehen in Sekunden, nicht in Millisekunden. Wer 10 statt 0.01 schreibt, fordert 10 Sekunden an.
Browser-Unterstützung: Die Eigenschaft wird im Wesentlichen nur von Chromium-basierten Browsern unterstützt. Firefox und Safari ignorieren sie. Deshalb vorher navigator.mediaDevices.getSupportedConstraints().latency prüfen. Unbekannte Einschränkungen führen nicht zu einem Fehler, sie werden stillschweigend übergangen.
Harte Einschränkungen: exact, min und max können einen OverconstrainedError auslösen. Für breite Kompatibilität besser ideal verwenden.
Der Wert beschreibt die Latenz der Aufnahme, nicht die Gesamtlatenz bis zur Wiedergabe. Dafür siehe AudioContext.baseLatency und outputLatency.
Die Einschränkung gilt nur für Audiospuren. Bei Videospuren hat sie keine Wirkung.
getUserMedia() funktioniert nur in einem sicheren Kontext (HTTPS) und erst, nachdem der Nutzer die Berechtigung erteilt hat.

Siehe auch

MediaStreamTrackProcessor.readable MediaTrackConstraints.frameRate MediaTrackConstraints.groupId MediaTrackConstraints.height MediaTrackConstraints.volume