MediaTrackSettings.aspectRatio — Eigenschaft · JavaScript-Referenz

Signatur

MediaTrackSettings.aspectRatio

Beschreibung

Die Eigenschaft aspectRatio des Wörterbuchs MediaTrackSettings gibt an, mit welchem Seitenverhältnis ein Video-Track gerade arbeitet. Der Wert ist ein number (double) und entspricht der Breite geteilt durch die Höhe, gerundet auf zehn Nachkommastellen. Ein 1280×720-Stream liefert also etwa 1.7777777778, ein 640×480-Stream 1.3333333333.

Das Settings-Objekt holen Sie über MediaStreamTrack.getSettings(). Anders als bei getConstraints() steht darin nicht, was Sie angefordert haben, sondern was der Browser bzw. die Kamera tatsächlich eingestellt hat. Das ist wichtig, denn Einschränkungen (Constraints) wie { aspectRatio: { ideal: 16 / 9 } } sind nur Wünsche, die das Gerät nicht erfüllen muss.

Typische Anwendungsfälle sind das passende Dimensionieren eines <video>- oder <canvas>-Elements, die Kontrolle nach einem applyConstraints()-Aufruf und die Wahl eines passenden Layouts (Hoch- oder Querformat) bei Kameras auf Mobilgeräten.

Bei Audio-Tracks gibt es die Eigenschaft nicht. Ob der Browser sie grundsätzlich unterstützt, prüfen Sie mit navigator.mediaDevices.getSupportedConstraints().aspectRatio.

Rückgabewert

Typ

number | undefined

Beschreibung

Aktuelles Seitenverhältnis (Breite ÷ Höhe) als Gleitkommazahl mit bis zu zehn Nachkommastellen. undefined, wenn der Track kein Video ist oder der Browser die Eigenschaft nicht meldet.

Beispiele

Seitenverhältnis der Webcam auslesen

const zeigeSeitenverhaeltnis = async () => {
  const stream = await navigator.mediaDevices.getUserMedia({ video: true });
  const [track] = stream.getVideoTracks();
  const { aspectRatio, width, height } = track.getSettings();

  console.log(`Auflösung: ${width}×${height}`);
  console.log(`Seitenverhältnis: ${aspectRatio?.toFixed(3) ?? 'unbekannt'}`);
};

zeigeSeitenverhaeltnis().catch(console.error);

Auflösung: 640×480 Seitenverhältnis: 1.333

16:9 anfordern und das Ergebnis prüfen

const starteBreitbild = async () => {
  const stream = await navigator.mediaDevices.getUserMedia({
    video: { aspectRatio: { ideal: 16 / 9 } }
  });
  const [track] = stream.getVideoTracks();
  const ratio = track.getSettings().aspectRatio;

  // Toleranz verwenden, da Gleitkommazahlen gerundet sind
  const istBreitbild = Math.abs(ratio - 16 / 9) < 0.01;
  console.log(istBreitbild ? '16:9 aktiv' : `Kamera liefert ${ratio}`);
  return stream;
};

starteBreitbild();

16:9 aktiv

Canvas passend zum Video-Track dimensionieren

const canvas = document.querySelector('canvas');

const passeCanvasAn = (track, breite = 800) => {
  const { aspectRatio, width, height } = track.getSettings();
  // Fallback, falls aspectRatio nicht gemeldet wird
  const ratio = aspectRatio ?? (width && height ? width / height : 16 / 9);
  canvas.width = breite;
  canvas.height = Math.round(breite / ratio);
  console.log(`Canvas: ${canvas.width}×${canvas.height}`);
};

navigator.mediaDevices.getUserMedia({ video: true })
  .then((stream) => passeCanvasAn(stream.getVideoTracks()[0]));

Canvas: 800×450

Nach applyConstraints() das neue Verhältnis kontrollieren

const wechsleAufQuadrat = async (track) => {
  try {
    await track.applyConstraints({ aspectRatio: { exact: 1 } });
    console.log('Neu:', track.getSettings().aspectRatio);
  } catch (err) {
    // OverconstrainedError, wenn die Kamera 1:1 nicht kann
    console.warn('Nicht unterstützt:', err.constraint);
  }
};

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

Neu: 1

// Wichtig · Fallstricke

Nur lesbar über getSettings(): Wenn Sie den Wert im zurückgegebenen Objekt ändern, passiert am Track nichts. Änderungen laufen über applyConstraints().
Gleitkommavergleich: Vergleichen Sie nie direkt mit === gegen 16 / 9, denn der Wert wird gerundet. Arbeiten Sie mit einer Toleranz.
Browser-Unterstützung: Chrome, Edge und Safari melden aspectRatio. Firefox liefert den Wert in getSettings() je nach Version nicht. Berechnen Sie ihn deshalb als Fallback aus width / height und prüfen Sie vorher mit getSupportedConstraints().
Ausrichtung auf Mobilgeräten: Dreht man das Gerät, können sich Breite und Höhe vertauschen. Dann gilt z. B. 0.5625 statt 1.777…. Lesen Sie die Einstellungen neu aus, statt den Wert zwischenzuspeichern.
Sicherer Kontext: getUserMedia() funktioniert nur über HTTPS bzw. localhost und braucht die Erlaubnis der Nutzerin oder des Nutzers.
Bei Audio-Tracks ist die Eigenschaft immer undefined.

Siehe auch

MediaTrackSettings.sampleRate MediaTrackSettings.frameRate MediaTrackSettings.cursor MediaTrackSettings.deviceId MediaTrackSettings.height