MediaTrackConstraints.height — Eigenschaft · JavaScript-Referenz

Signatur

MediaTrackConstraints.height

Beschreibung

Mit der Eigenschaft height im Wörterbuch MediaTrackConstraints gibst du an, welche Bildhöhe (in Pixeln) ein Video-Track haben soll. Das passiert meist beim Aufruf von navigator.mediaDevices.getUserMedia() oder getDisplayMedia(). Später kannst du die Höhe auch mit MediaStreamTrack.applyConstraints() ändern.

Der Wert ist ein ConstrainULong, also eines von beiden:

eine Ganzzahl, z. B. height: 720. Sie gilt als Wunsch (wie ideal). Der Browser versucht, möglichst nah an diesen Wert zu kommen, und schlägt nicht fehl, wenn das nicht klappt.
ein Objekt mit den Schlüsseln min, max, exact und/oder ideal. Dabei sind min, max und exact Pflicht-Einschränkungen: Kann das Gerät sie nicht erfüllen, wird das Promise mit einem OverconstrainedError abgelehnt.

Du nutzt height meist zusammen mit width oder aspectRatio, z. B. um für Videokonferenzen eine feste Auflösung anzufordern, für schwache Verbindungen die Bandbreite zu senken oder für Fotoaufnahmen eine Mindestqualität zu erzwingen. Ob der Browser height überhaupt als Einschränkung kennt, verrät navigator.mediaDevices.getSupportedConstraints().height. Welche Höhe tatsächlich eingestellt wurde, liest du mit track.getSettings().height aus.

Parameter

Name	Typ	Beschreibung
$height	number \| { min?: number, max?: number, ideal?: number, exact?: number }	Gewünschte Höhe in Pixeln. Eine reine Zahl gilt als `ideal`. `min`, `max` und `exact` sind Pflicht-Einschränkungen.
$height.min	number	Kleinste zulässige Höhe. Wird sie unterschritten, gibt es einen `OverconstrainedError`.
$height.max	number	Größte zulässige Höhe.
$height.ideal	number	Bevorzugte Höhe. Der Browser wählt die nächstgelegene verfügbare Einstellung.
$height.exact	number	Genau diese Höhe ist Pflicht. Ohne passende Einstellung schlägt die Anfrage fehl.

Rückgabewert

Typ

number | ConstrainULongRange

Beschreibung

Der gesetzte Einschränkungswert: entweder eine Zahl oder ein Objekt mit min/max/ideal/exact. Die tatsächlich erreichte Höhe steht in MediaTrackSettings.height.

Beispiele

Kamera mit bevorzugter HD-Höhe öffnen

const startCamera = async () => {
  const stream = await navigator.mediaDevices.getUserMedia({
    video: { width: { ideal: 1280 }, height: { ideal: 720 } }
  });
  const [track] = stream.getVideoTracks();
  const { width, height } = track.getSettings();
  console.log(`Tatsächliche Auflösung: ${width}x${height}`);
  document.querySelector('video').srcObject = stream;
};

startCamera().catch(console.error);

Tatsächliche Auflösung: 1280x720

Mindesthöhe erzwingen und Fehler abfangen

const openHighResCamera = async () => {
  try {
    return await navigator.mediaDevices.getUserMedia({
      video: { height: { min: 1080 } }
    });
  } catch (err) {
    if (err.name === 'OverconstrainedError') {
      console.warn(`Einschränkung nicht erfüllbar: ${err.constraint}`);
      // Rückfall auf eine weiche Anforderung
      return navigator.mediaDevices.getUserMedia({ video: { height: 720 } });
    }
    throw err;
  }
};

openHighResCamera().then((s) => console.log('Stream aktiv:', s.active));

Einschränkung nicht erfüllbar: height Stream aktiv: true

Höhe eines laufenden Tracks per applyConstraints reduzieren

const reduceQuality = async (stream) => {
  const [track] = stream.getVideoTracks();
  if (!navigator.mediaDevices.getSupportedConstraints().height) {
    console.log('height wird nicht unterstützt');
    return;
  }
  // z. B. bei schlechter Verbindung auf 360p wechseln
  await track.applyConstraints({ height: { max: 360 } });
  console.log('Neue Höhe:', track.getSettings().height);
};

const stream = await navigator.mediaDevices.getUserMedia({ video: true });
await reduceQuality(stream);

Neue Höhe: 360

Aktuelle Einschränkungen und Fähigkeiten auslesen

const stream = await navigator.mediaDevices.getUserMedia({ video: { height: 480 } });
const [track] = stream.getVideoTracks();

console.log('Angefordert:', track.getConstraints().height);
console.log('Möglich:', track.getCapabilities?.().height);

Angefordert: 480 Möglich: { max: 1080, min: 1 }

// Wichtig · Fallstricke

Zahl heißt „Wunsch“: height: 1080 garantiert keine 1080 Pixel. Wenn du genau diesen Wert brauchst, nimm exact oder min. Prüfe außerdem immer getSettings().
OverconstrainedError: Pflicht-Einschränkungen, die das Gerät nicht erfüllen kann, lassen das Promise mit einem Fehler scheitern. Die Eigenschaft err.constraint nennt die verantwortliche Einschränkung. Plane einen Rückfall ein.
Ausrichtung: Auf Mobilgeräten im Hochformat tauschen manche Browser Breite und Höhe. Bei einer Anforderung von 1280×720 kann dann 720×1280 geliefert werden.
Zusammenspiel mit width und aspectRatio: Widersprüchliche Werte können dazu führen, dass der Browser das Bild skaliert oder beschneidet, oder dass die Anfrage fehlschlägt.
getDisplayMedia(): Hier sind min und exact nicht erlaubt (TypeError). Verwende nur max und ideal.
Kompatibilität: Wird von allen modernen Browsern unterstützt. getUserMedia funktioniert nur in einem sicheren Kontext (HTTPS oder localhost) und nach Freigabe durch die Nutzerin oder den Nutzer. getCapabilities() fehlt in älteren Firefox-Versionen.

Siehe auch

MediaTrackConstraints.width MediaTrackConstraints.deviceId MediaTrackConstraints.volume MediaTrackConstraints.groupId MediaTrackConstraints.latency