MediaTrackSupportedConstraints.aspectRatio — Eigenschaft · JavaScript-Referenz

Signatur

MediaTrackSupportedConstraints.aspectRatio

Beschreibung

Die Eigenschaft aspectRatio gehört zum Wörterbuch MediaTrackSupportedConstraints. Ein solches Objekt liefert navigator.mediaDevices.getSupportedConstraints(). Die Eigenschaft ist nur vorhanden und hat dann den Wert true, wenn der Benutzeragent die Einschränkung (Constraint) aspectRatio kennt. Kennt er sie nicht, fehlt die Eigenschaft ganz. Beim Auslesen erhält man dann undefined.

Mit der Einschränkung aspectRatio legt man fest, welches Seitenverhältnis (Breite geteilt durch Höhe) eine Videospur haben soll, etwa 16 / 9 ≈ 1.7778 oder 4 / 3 ≈ 1.3333. Das ist hilfreich, wenn die Videovorschau in ein festes Layout passen soll, zum Beispiel in eine quadratische Profilbild-Aufnahme oder ein 16:9-Konferenzfenster.

Man prüft diese Eigenschaft vor dem Aufruf von getUserMedia() oder MediaStreamTrack.applyConstraints(). Ist die Einschränkung nicht verfügbar, kann die Anwendung auf width/height ausweichen oder das Bild per CSS (object-fit) zuschneiden.

Wichtig: Der Wert sagt nur aus, dass der Browser die Einschränkung versteht. Ob die Kamera das gewünschte Seitenverhältnis tatsächlich liefern kann, verrät er nicht. Das zeigen erst MediaStreamTrack.getCapabilities() und getSettings().

Rückgabewert

Typ

boolean | undefined

Beschreibung

true, wenn die Einschränkung aspectRatio unterstützt wird. Wird sie nicht unterstützt, fehlt die Eigenschaft und der Wert ist undefined. Ein false ist laut Spezifikation nicht vorgesehen.

Beispiele

Unterstützung prüfen

const supported = navigator.mediaDevices.getSupportedConstraints();

if (supported.aspectRatio) {
  console.log('aspectRatio wird unterstützt');
} else {
  console.log('aspectRatio wird NICHT unterstützt');
}

aspectRatio wird unterstützt

Kamera im 16:9-Format anfordern (mit Rückfallebene)

const startCamera = async (videoEl) => {
  const supported = navigator.mediaDevices.getSupportedConstraints();

  const video = supported.aspectRatio
    ? { aspectRatio: { ideal: 16 / 9 }, width: { ideal: 1280 } }
    : { width: { ideal: 1280 }, height: { ideal: 720 } }; // Rückfall

  const stream = await navigator.mediaDevices.getUserMedia({ video });
  videoEl.srcObject = stream;

  const { aspectRatio, width, height } = stream.getVideoTracks()[0].getSettings();
  console.log(`Tatsächlich: ${width}x${height} (Verhältnis ${aspectRatio?.toFixed(4) ?? (width / height).toFixed(4)})`);
};

startCamera(document.querySelector('video')).catch(console.error);

Tatsächlich: 1280x720 (Verhältnis 1.7778)

Laufende Spur auf quadratisches Format umstellen

const makeSquare = async (track) => {
  if (!navigator.mediaDevices.getSupportedConstraints().aspectRatio) {
    console.warn('aspectRatio nicht verfügbar – CSS object-fit verwenden');
    return;
  }
  try {
    await track.applyConstraints({ aspectRatio: { exact: 1 } });
    console.log('Neues Verhältnis:', track.getSettings().aspectRatio);
  } catch (err) {
    // OverconstrainedError, wenn die Kamera 1:1 nicht liefern kann
    console.error(err.name, err.constraint);
  }
};

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

Neues Verhältnis: 1

// Wichtig · Fallstricke

Nur Aussage über den Browser: true heißt nicht, dass die Kamera jedes Seitenverhältnis liefern kann. Den tatsächlichen Wertebereich zeigt track.getCapabilities().aspectRatio (mit min/max).
exact vermeiden: { exact: … } kann einen OverconstrainedError auslösen. Mit ideal fällt der Browser bei Bedarf auf ein Format zurück, das nah am Wunsch liegt. Manche Browser schneiden das Bild dafür zu oder skalieren es.
Prüfung ohne false: Nicht unterstützte Einschränkungen fehlen im Objekt ganz. Deshalb auf Wahrheitswert prüfen (if (supported.aspectRatio)), nicht auf === false.
Gleitkommawerte: Das Verhältnis ist eine Dezimalzahl, zum Beispiel 1.7777777778. Beim Vergleich runden oder eine Toleranz verwenden.
Sicherer Kontext: navigator.mediaDevices gibt es nur über HTTPS oder localhost. getSupportedConstraints() selbst verlangt keine Berechtigung.
Browser-Unterstützung: Chromium und Safari unterstützen die Eigenschaft. Firefox meldet sie in älteren Versionen möglicherweise nicht; deshalb immer eine Rückfallebene mit width/height vorsehen.

Siehe auch

MediaTrackConstraints.noiseSuppression MediaTrackSupportedConstraints.sampleRate MediaTrackSupportedConstraints.frameRate MediaTrackSupportedConstraints.deviceId MediaTrackSupportedConstraints.height