MediaTrackConstraints.frameRate — Eigenschaft · JavaScript-Referenz

Signatur

MediaTrackConstraints.frameRate

Beschreibung

Die Eigenschaft frameRate des Wörterbuchs MediaTrackConstraints gibt an, welche Bildrate du für eine Videospur haben möchtest. Die Einschränkung übergibst du an navigator.mediaDevices.getUserMedia(), getDisplayMedia() oder MediaStreamTrack.applyConstraints(). Der Wert ist ein ConstrainDouble, also eine Gleitkommazahl in Bildern pro Sekunde (fps).

Du kannst die Bildrate auf zwei Arten angeben:

als einfache Zahl (z. B. 30): Sie gilt als Idealwert, und der Browser wählt die Einstellung, die am nächsten daran liegt;
als Objekt mit den Schlüsseln min, max, exact und ideal: Damit legst du feste Grenzen oder einen genauen Wert fest.

Hilfreich ist das z. B. bei Videokonferenzen, wo du mit einer niedrigen Bildrate Bandbreite und CPU sparst. Auch bei Bildschirmaufnahmen mit wenig Bewegung reichen oft 5–15 fps. Für flüssige Aufnahmen, etwa beim Spiele-Streaming, kannst du dagegen 60 fps oder mehr anfordern. Ob die Kamera eine Bildrate überhaupt einstellen kann, prüfst du vorher mit navigator.mediaDevices.getSupportedConstraints().frameRate. Welche Werte möglich sind, liefert MediaStreamTrack.getCapabilities().

Welche Bildrate tatsächlich eingestellt wurde, liest du nach dem Anwenden mit track.getSettings().frameRate aus. Dieser Wert kann vom gewünschten Wert abweichen, wenn du nur ideal angegeben hast.

Parameter

Name	Typ	Beschreibung
$frameRate	number \| { min?: number, max?: number, exact?: number, ideal?: number }	Gewünschte Bildrate in fps. Eine einfache Zahl gilt als `ideal`. Bei `min`, `max` und `exact` muss der Browser den Wert einhalten, sonst schlägt die Anfrage fehl.
$frameRate.min	number	Untergrenze der Bildrate. Diesen Wert muss der Browser mindestens erreichen.
$frameRate.max	number	Obergrenze der Bildrate. Diesen Wert darf der Browser nicht überschreiten.
$frameRate.exact	number	Genau diese Bildrate wird verlangt. Kann der Browser sie nicht liefern, gibt es einen `OverconstrainedError`.
$frameRate.ideal	number	Bevorzugte Bildrate. Der Browser wählt einen Wert, der möglichst nah daran liegt.

Rückgabewert

Typ

number | ConstrainDoubleRange | undefined

Beschreibung

Die festgelegte Einschränkung für die Bildrate, also eine Zahl oder ein Objekt mit min/max/exact/ideal. Wurde nichts festgelegt, ist der Wert undefined.

Beispiele

Kamera mit bevorzugten 30 fps und höchstens 60 fps öffnen

const startCamera = async () => {
  // Prüfen, ob der Browser die Einschränkung frameRate kennt
  if (!navigator.mediaDevices.getSupportedConstraints().frameRate) {
    console.warn('frameRate wird nicht unterstützt');
  }
  const stream = await navigator.mediaDevices.getUserMedia({
    video: { frameRate: { ideal: 30, max: 60 } }
  });
  const [track] = stream.getVideoTracks();
  console.log('Tatsächliche Bildrate:', track.getSettings().frameRate);
  document.querySelector('video').srcObject = stream;
};

startCamera().catch(console.error);

Tatsächliche Bildrate: 30

Bildrate im laufenden Betrieb senken (Bandbreite sparen)

const reduceFrameRate = async (track) => {
  const caps = track.getCapabilities?.() ?? {};
  console.log('Möglicher Bereich:', caps.frameRate);
  try {
    await track.applyConstraints({ frameRate: { max: 15 } });
    console.log('Neue Bildrate:', track.getSettings().frameRate);
  } catch (err) {
    console.error('Einschränkung nicht erfüllbar:', err.name, err.constraint);
  }
};

const stream = await navigator.mediaDevices.getUserMedia({ video: true });
await reduceFrameRate(stream.getVideoTracks()[0]);

Möglicher Bereich: { min: 1, max: 30 } Neue Bildrate: 15

Bildschirmaufnahme mit niedriger Bildrate

const shareScreen = async () => {
  // Für Präsentationen reichen wenige Bilder pro Sekunde
  const stream = await navigator.mediaDevices.getDisplayMedia({
    video: { frameRate: 5 }
  });
  const [track] = stream.getVideoTracks();
  console.log(track.getConstraints().frameRate);
  return stream;
};

document.querySelector('#share').addEventListener('click', shareScreen);

5

Fehler bei einer nicht erfüllbaren exakten Vorgabe

try {
  await navigator.mediaDevices.getUserMedia({
    video: { frameRate: { exact: 240 } }
  });
} catch (err) {
  if (err.name === 'OverconstrainedError') {
    console.log('Nicht erfüllbar:', err.constraint);
  }
}

Nicht erfüllbar: frameRate

// Wichtig · Fallstricke

Pflichtvorgaben: Wenn du exact, min oder max angibst und der Browser sie nicht einhalten kann, schlägt getUserMedia() bzw. applyConstraints() mit einem OverconstrainedError fehl. In err.constraint steht dann "frameRate". Verwende möglichst ideal, damit die Anfrage auch auf anderen Geräten funktioniert.
Nur eine Obergrenze: Die tatsächliche Bildrate kann schwanken, z. B. bei schwachem Licht, wenn die Kamera die Belichtung verlängert, oder bei hoher CPU-Last. Der Wert in getSettings().frameRate ist ein Zielwert und nicht die gemessene Bildrate. Die tatsächlich gelieferte Rate ermittelst du zum Beispiel über die WebRTC-Statistik (getStats()).
Bildschirmaufnahme: Bei getDisplayMedia() sind min und exact nicht erlaubt und führen zu einem TypeError. Die Werte ideal und max sind möglich.
Kompatibilität: Alle modernen Browser unterstützen die Eigenschaft. Firefox beachtet frameRate bei manchen Kameras allerdings nur eingeschränkt. Safari unter iOS unterstützt nur bestimmte Kombinationen aus Auflösung und Bildrate. Die API steht nur in sicheren Kontexten (HTTPS) zur Verfügung.
Die Angabe frameRate gilt nur für Videospuren. Bei Audiospuren wird sie ignoriert.

Siehe auch

MediaTrackConstraints.sampleRate MediaTrackConstraints.latency MediaTrackConstraints.sampleSize MediaTrackConstraints.aspectRatio MediaTrackConstraints.facingMode