MediaTrackSettings.latency — Eigenschaft · JavaScript-Referenz

Signatur

MediaTrackSettings.latency

Beschreibung

Die Eigenschaft latency des Dictionarys MediaTrackSettings liefert die tatsächlich wirksame Latenz eines MediaStreamTrack in Sekunden. Gemeint ist die Zeit vom Eintreffen des Signals an der Hardware (z. B. am Mikrofon) bis die Daten beim Aufrufer ankommen. Den Wert bekommst du über track.getSettings().

Die Eigenschaft ist für Audiospuren gedacht. Nützlich ist sie überall, wo Verzögerung eine Rolle spielt: bei Echtzeitkommunikation (WebRTC), in Musik- und DAW-Anwendungen, bei Live-Monitoring oder beim Abgleich von Audio mit Video bzw. anderen Spuren.

Mit der Einschränkung (constraint) latency in getUserMedia() oder applyConstraints() kannst du eine Wunschlatenz anfragen. getSettings().latency zeigt dann, was der Browser bzw. das Gerät wirklich umgesetzt hat. Der Wert ist eine Schätzung und kann je nach Treiber, Puffergröße und Betriebssystem stark schwanken.

Bevor du den Wert verwendest, prüfe mit navigator.mediaDevices.getSupportedConstraints().latency, ob der Browser die Eigenschaft überhaupt kennt.

Rückgabewert

Typ

number | undefined

Beschreibung

Geschätzte Latenz in Sekunden als double (z. B. 0.01 = 10 ms). Ist undefined, wenn der Browser oder die Spur die Eigenschaft nicht unterstützt (z. B. bei Videospuren).

Beispiele

Aktuelle Mikrofon-Latenz auslesen

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

if (latency !== undefined) {
  console.log(`Latenz: ${(latency * 1000).toFixed(1)} ms`);
} else {
  console.log('latency wird nicht unterstützt');
}

Latenz: 10.0 ms

Niedrige Latenz anfragen und Ergebnis prüfen

const supported = navigator.mediaDevices.getSupportedConstraints();

if (supported.latency) {
  const stream = await navigator.mediaDevices.getUserMedia({
    audio: {
      latency: { ideal: 0.005 }, // Wunsch: 5 ms
      echoCancellation: false
    }
  });
  const [track] = stream.getAudioTracks();
  console.log('Angefragt: 0.005 s, erhalten:', track.getSettings().latency, 's');
}

Angefragt: 0.005 s, erhalten: 0.01 s

Latenz nachträglich mit applyConstraints ändern

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

console.log('Vorher:', track.getSettings().latency);

try {
  await track.applyConstraints({ latency: { max: 0.02 } });
  console.log('Nachher:', track.getSettings().latency);
} catch (err) {
  // OverconstrainedError, wenn max nicht einhaltbar ist
  console.warn('Latenz nicht erreichbar:', err.constraint);
}

Vorher: 0.02133 Nachher: 0.01

// Wichtig · Fallstricke

Einheit: Der Wert ist in Sekunden angegeben, nicht in Millisekunden. Für die Anzeige also mit 1000 multiplizieren.
Browser-Kompatibilität: Chromium-Browser und Safari unterstützen die Eigenschaft, Firefox nicht. Dort ist der Wert undefined. Prüfe die Unterstützung vorher mit getSupportedConstraints().
Nur eine Schätzung: Die gemeldete Latenz berücksichtigt nicht unbedingt alle Puffer, etwa die Verarbeitung in der Web Audio API oder Netzwerkverzögerungen bei WebRTC. Für eine exakte Synchronisation zusätzlich AudioContext.baseLatency und outputLatency einbeziehen.
Eine sehr niedrige Wunschlatenz kann Aussetzer (Knackser) verursachen. Mit exact oder max droht außerdem ein OverconstrainedError, deshalb besser ideal verwenden.
Audioverarbeitung wie echoCancellation oder noiseSuppression kann die Latenz erhöhen.
Der Zugriff auf das Mikrofon erfordert einen sicheren Kontext (HTTPS) und die Erlaubnis des Nutzers.

Siehe auch

MediaTrackConstraints.groupId MediaTrackSettings.cursor MediaTrackSettings.frameRate MediaTrackSettings.groupId MediaTrackSettings.height