OverconstrainedError.constraint — Eigenschaft · JavaScript-Referenz

Signatur

OverconstrainedError.constraint

Beschreibung

Die schreibgeschützte Eigenschaft constraint eines OverconstrainedError enthält den Namen der Bedingung (Constraint), an der eine Medienanfrage gescheitert ist, zum Beispiel "width", "frameRate", "facingMode" oder "deviceId". Den Wert legt der Browser fest, wenn er den Fehler erzeugt, oder er wird beim eigenen Aufruf von new OverconstrainedError(constraint, message) als erstes Argument übergeben.

Ein solcher Fehler tritt auf, wenn navigator.mediaDevices.getUserMedia() oder MediaStreamTrack.prototype.applyConstraints() mit Bedingungen aufgerufen wird, die kein verfügbares Gerät erfüllen kann. Das passiert fast nur bei verpflichtenden Angaben wie exact, min oder max. Einfache Werte und ideal gelten dagegen nur als Wunsch und lösen den Fehler normalerweise nicht aus.

Praktisch nutzt man constraint, um gezielt auszuweichen: Scheitert z. B. width, fordert man eine kleinere Auflösung an. Scheitert deviceId, fällt man auf die Standardkamera zurück. Außerdem kann man dem Nutzer damit eine verständliche Fehlermeldung zeigen.

Rückgabewert

Typ

string

Beschreibung

Name der nicht erfüllbaren Constraint, z. B. "width". Kann ein leerer String sein, wenn der Browser (etwa aus Datenschutzgründen) keinen Namen preisgibt.

Beispiele

Gescheiterte Constraint bei getUserMedia auslesen

const startKamera = async () => {
  try {
    const stream = await navigator.mediaDevices.getUserMedia({
      video: { width: { exact: 7680 }, height: { exact: 4320 } }
    });
    document.querySelector('video').srcObject = stream;
  } catch (err) {
    if (err.name === 'OverconstrainedError') {
      console.warn(`Nicht erfüllbar: ${err.constraint}`);
    } else {
      console.error(err);
    }
  }
};

startKamera();

Nicht erfüllbar: width

Gezielter Rückfall je nach Constraint

const holeStream = async (deviceId) => {
  const wunsch = {
    video: {
      deviceId: { exact: deviceId },
      frameRate: { min: 60 }
    }
  };
  try {
    return await navigator.mediaDevices.getUserMedia(wunsch);
  } catch (err) {
    if (err.name !== 'OverconstrainedError') throw err;
    switch (err.constraint) {
      case 'deviceId':
        // Gerät nicht vorhanden → Standardkamera
        delete wunsch.video.deviceId;
        break;
      case 'frameRate':
        // 60 fps nicht möglich → nur noch Wunschwert
        wunsch.video.frameRate = { ideal: 60 };
        break;
      default:
        wunsch.video = true;
    }
    return navigator.mediaDevices.getUserMedia(wunsch);
  }
};

applyConstraints auf einer laufenden Spur

const [track] = stream.getVideoTracks();

try {
  await track.applyConstraints({ aspectRatio: { exact: 21 / 9 } });
} catch (err) {
  if (err.name === 'OverconstrainedError') {
    console.log(`Spur unverändert, da "${err.constraint}" nicht passt.`);
  }
}

Spur unverändert, da "aspectRatio" nicht passt.

Eigenen Fehler erzeugen

const fehler = new OverconstrainedError('facingMode', 'Keine Rückkamera gefunden');
console.log(fehler.name, fehler.constraint, fehler.message);
console.log(fehler instanceof DOMException);

OverconstrainedError facingMode Keine Rückkamera gefunden true

// Wichtig · Fallstricke

Nur Lesezugriff: Zuweisungen an constraint werden still ignoriert bzw. werfen im Strict Mode einen TypeError.
Nur ein Name: Obwohl mehrere Constraints unerfüllbar sein können, liefert die Eigenschaft nur eine davon. Der Wert selbst (z. B. 7680) ist nicht enthalten.
Datenschutz: Hat der Nutzer noch keine Freigabe erteilt, geben manche Browser nur einen leeren String zurück oder melden das Problem erst später, damit Seiten keine Gerätemerkmale ausspähen können (Fingerprinting).
Typprüfung: Ältere Browser (Firefox unter 90, Safari unter 14.1) werfen stattdessen eine DOMException mit name === "OverconstrainedError". Prüfe darum lieber err.name als instanceof OverconstrainedError.
Funktioniert nur in sicheren Kontexten (HTTPS oder localhost), weil getUserMedia nur dort verfügbar ist.

Siehe auch

OverconstrainedError MediaDevices.getUserMedia() MediaStreamTrack.applyConstraints() MediaDevices.getSupportedConstraints() DOMException PerformanceTiming.unloadEventStart