Signatur
Beschreibung
Die Eigenschaft width des Wörterbuchs MediaTrackConstraints beschreibt die gewünschte oder verpflichtende Breite eines Videotracks in Pixeln. Man verwendet sie mit navigator.mediaDevices.getUserMedia(), getDisplayMedia() oder MediaStreamTrack.applyConstraints(), um z. B. eine Kamera in HD-Auflösung anzufordern.
Der Wert ist ein ConstrainULong. Er kann eine einfache ganze Zahl sein oder ein Objekt mit den Schlüsseln min, max, exact und ideal. Eine einfache Zahl ist in getUserMedia() ein Wunschwert (wie ideal): Der Browser versucht, möglichst nah heranzukommen, liefert aber notfalls eine andere Breite. Nur min, max und exact sind verpflichtend. Lassen sie sich nicht erfüllen, wird das Promise mit einem OverconstrainedError abgelehnt.
Welche Breite der Track am Ende wirklich hat, liest du mit track.getSettings().width aus. Den Wertebereich, den das Gerät unterstützt, liefert track.getCapabilities().width. Ob der Browser die Einschränkung überhaupt kennt, zeigt navigator.mediaDevices.getSupportedConstraints().width.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $width | number | { min?: number, max?: number, exact?: number, ideal?: number } | Breite in Pixeln als ganze Zahl ohne Vorzeichen (ConstrainULong). Eine einfache Zahl gilt als Wunschwert. min, max und exact sind verpflichtend, ideal ist ein Wunschwert. |
Rückgabewert
min/max/exact/ideal.Beispiele
Kamera in HD-Auflösung anfordern
const startCamera = async () => {
const stream = await navigator.mediaDevices.getUserMedia({
video: {
width: { ideal: 1280 },
height: { ideal: 720 }
}
});
const [track] = stream.getVideoTracks();
console.log('Tatsächliche Breite:', track.getSettings().width);
document.querySelector('video').srcObject = stream;
};
startCamera().catch(console.error);Mindestbreite verpflichtend verlangen und Fehler behandeln
const requestFullHd = async () => {
try {
const stream = await navigator.mediaDevices.getUserMedia({
video: { width: { min: 1920 } }
});
return stream;
} catch (err) {
if (err.name === 'OverconstrainedError') {
console.warn(`Nicht erfüllbar: ${err.constraint}`);
// Ausweichlösung ohne harte Vorgabe
return navigator.mediaDevices.getUserMedia({ video: { width: 1920 } });
}
throw err;
}
};
requestFullHd();Breite eines laufenden Tracks mit applyConstraints() ändern
const stream = await navigator.mediaDevices.getUserMedia({ video: true });
const [track] = stream.getVideoTracks();
const caps = track.getCapabilities();
console.log('Unterstützt:', caps.width); // z. B. { min: 1, max: 1920 }
await track.applyConstraints({
width: { ideal: 640, max: caps.width.max }
});
console.log('Neue Breite:', track.getSettings().width);Unterstützung prüfen
const supported = navigator.mediaDevices.getSupportedConstraints();
console.log(supported.width ? 'width wird unterstützt' : 'width wird nicht unterstützt');// Wichtig · Fallstricke
- Zahl heißt Wunschwert:
{ width: 1280 }ist keine harte Vorgabe. Brauchst du genau diesen Wert, schreibe{ exact: 1280 }– dann riskierst du aber einenOverconstrainedError. InapplyConstraints()behandeln einige Browser einfache Zahlen strenger. - Ausrichtung: Auf Mobilgeräten im Hochformat tauschen Breite und Höhe oft die Rollen. Prüfe das Ergebnis deshalb immer mit
getSettings(). - Skalierung: Chrome kann das Bild selbst herunterskalieren oder zuschneiden, um den Wert zu treffen. Firefox und Safari halten sich eher an die nativen Modi der Kamera.
- Nur für Video: Die Einschränkung gilt nur für Videotracks. Bei Audiotracks wird sie ignoriert.
- Sicherer Kontext:
getUserMedia()funktioniert nur über HTTPS oder auflocalhostund braucht die Erlaubnis der Nutzerin bzw. des Nutzers. - Kompatibilität: Wird von allen modernen Browsern unterstützt (Chrome, Edge, Firefox, Safari). Ältere Chrome-Versionen nutzten eine eigene Syntax mit
mandatory/optional, die veraltet ist.