MediaTrackConstraints.aspectRatio — Eigenschaft · JavaScript-Referenz

Signatur

MediaTrackConstraints.aspectRatio

Beschreibung

Mit aspectRatio im MediaTrackConstraints-Objekt gibst du vor, welches Seitenverhältnis ein Videotrack haben soll. Das Verhältnis ist Breite geteilt durch Höhe, also z. B. 16 / 9 ≈ 1.7778 oder 4 / 3 ≈ 1.3333. Die Einschränkung gilt nur für Videotracks, etwa von Kameras über navigator.mediaDevices.getUserMedia() oder von der Bildschirmaufnahme über getDisplayMedia().

Als ConstrainDouble nimmt die Eigenschaft entweder eine einfache Zahl oder ein Objekt an. Eine Zahl allein ist eine Wunschvorgabe (entspricht ideal): Der Browser versucht, möglichst nah heranzukommen. Mit exact, min und max machst du daraus eine Pflichtvorgabe. Kann das Gerät sie nicht erfüllen, wird das Promise mit einem OverconstrainedError abgelehnt.

Du setzt aspectRatio vor allem, wenn deine Oberfläche ein festes Format braucht, z. B. quadratische Profilbilder, 16:9-Videokonferenzen oder Hochformat-Streams für Mobilgeräte. Ob der Browser die Einschränkung überhaupt kennt, prüfst du mit navigator.mediaDevices.getSupportedConstraints().aspectRatio. Den tatsächlich verwendeten Wert liest du über track.getSettings().aspectRatio aus.

Parameter

Name	Typ	Beschreibung
$aspectRatio	number \| { exact?: number, ideal?: number, min?: number, max?: number }	Gewünschtes Seitenverhältnis (Breite ÷ Höhe). Eine Zahl allein wirkt wie `ideal`. `exact`, `min` und `max` sind Pflichtvorgaben.
$exact	number	Das Verhältnis muss genau diesem Wert entsprechen, sonst schlägt der Aufruf mit `OverconstrainedError` fehl.
$ideal	number	Wunschwert. Der Browser wählt die Einstellung, die diesem Wert am nächsten kommt.
$min	number	Kleinstes zulässiges Seitenverhältnis.
$max	number	Größtes zulässiges Seitenverhältnis.

Rückgabewert

Typ

number | ConstrainDoubleRange

Beschreibung

Die hinterlegte Vorgabe für das Seitenverhältnis: entweder eine Zahl oder ein Objekt mit exact, ideal, min und/oder max.

Beispiele

16:9-Kamerabild anfordern (Wunschvorgabe)

const startCamera = async () => {
  const stream = await navigator.mediaDevices.getUserMedia({
    video: {
      width: { ideal: 1280 },
      aspectRatio: 16 / 9 // wirkt wie { ideal: 1.7778 }
    }
  });
  const [track] = stream.getVideoTracks();
  console.log('Tatsächliches Verhältnis:', track.getSettings().aspectRatio?.toFixed(4));
  document.querySelector('video').srcObject = stream;
};

startCamera().catch(console.error);

Tatsächliches Verhältnis: 1.7778

Quadratisches Bild erzwingen mit Fehlerbehandlung

const getSquareStream = async () => {
  try {
    return await navigator.mediaDevices.getUserMedia({
      video: { aspectRatio: { exact: 1 } }
    });
  } catch (err) {
    if (err.name === 'OverconstrainedError') {
      console.warn(`Nicht erfüllbar: ${err.constraint}`);
      // Rückfall: nur Wunschvorgabe
      return navigator.mediaDevices.getUserMedia({ video: { aspectRatio: 1 } });
    }
    throw err;
  }
};

getSquareStream().then((s) => console.log('Stream bereit:', s.id));

Nicht erfüllbar: aspectRatio Stream bereit: …

Seitenverhältnis eines laufenden Tracks ändern

const switchToPortrait = async (track) => {
  const supported = navigator.mediaDevices.getSupportedConstraints();
  if (!supported.aspectRatio) {
    console.log('aspectRatio wird nicht unterstützt');
    return;
  }
  // Hochformat 9:16, Bereich tolerieren
  await track.applyConstraints({
    aspectRatio: { ideal: 9 / 16, min: 0.5, max: 0.6 }
  });
  console.log(track.getConstraints().aspectRatio);
};

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

{ ideal: 0.5625, min: 0.5, max: 0.6 }

// Wichtig · Fallstricke

Gleitkommawerte: 16 / 9 ergibt 1.777…. Viele Kameras liefern Auflösungen, die nicht genau passen, z. B. 1366×768. Deshalb schlägt exact oft unerwartet fehl. Nimm besser ideal oder einen kleinen Bereich mit min/max.
Widersprüche: Wenn du gleichzeitig width, height und aspectRatio als Pflichtvorgaben setzt, können sie sich widersprechen. Dann gibt es einen OverconstrainedError.
Zuschneiden: Der Browser darf das Bild beschneiden oder skalieren, um das Verhältnis zu erreichen (vgl. resizeMode). Dadurch kann das Sichtfeld kleiner werden.
Kompatibilität: Wird in aktuellen Chromium-Browsern, in Firefox und Safari unterstützt. Prüfe es vorher mit getSupportedConstraints(). Ältere Safari-Versionen haben die Einschränkung nur teilweise beachtet.
Kontext: getUserMedia() funktioniert nur in sicherem Kontext (HTTPS oder localhost) und erst nach Zustimmung des Nutzers.
Bei Audiotracks wird aspectRatio ignoriert.

Siehe auch

MediaTrackConstraints.sampleRate MediaTrackConstraints.frameRate MediaTrackConstraints.deviceId MediaTrackConstraints.height MediaTrackConstraints.channelCount