Signatur
Beschreibung
applyConstraints() ändert die Eigenschaften eines bereits laufenden MediaStreamTrack – etwa einer Kamera- oder Mikrofonspur aus getUserMedia(). So lässt sich zum Beispiel die Auflösung einer Videokonferenz bei schlechter Verbindung senken oder die Rauschunterdrückung umschalten, ohne einen neuen Stream anzufordern und den Nutzer erneut um Erlaubnis zu fragen.
Einschränkungen werden als MediaTrackConstraints-Objekt übergeben. Für jede Eigenschaft kannst du einen festen Wert angeben oder ein Objekt mit min, max, ideal und exact. Ein einfacher Wert (z. B. width: 1280) zählt als ideal, der Browser versucht also nur, ihm möglichst nahe zu kommen. min, max und exact sind dagegen Pflichtvorgaben: Kann das Gerät sie nicht erfüllen, wird das Promise abgelehnt. Über das Feld advanced gibst du eine Liste weiterer Einschränkungssätze an, die der Reihe nach versucht werden.
Die Methode gibt ein Promise zurück. Es wird erfüllt, sobald die Einschränkungen angewendet wurden. Welche Werte tatsächlich gelten, liest du danach mit track.getSettings() aus. Welche Eigenschaften und Wertebereiche das Gerät überhaupt kann, zeigen track.getCapabilities() und navigator.mediaDevices.getSupportedConstraints().
Wichtig: Jeder Aufruf ersetzt alle bisher gesetzten Einschränkungen des Tracks. Eigenschaften, die du nicht erneut angibst, fallen auf ihre Standardwerte zurück. Wenn du nur eine Eigenschaft ändern willst, übernimm die übrigen vorher mit track.getConstraints().
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $constraints | MediaTrackConstraints | {} | Objekt mit den gewünschten Einschränkungen, z. B. width, height, frameRate, aspectRatio, facingMode, echoCancellation, noiseSuppression, autoGainControl, sampleRate sowie optional advanced (Array weiterer Einschränkungssätze). Werte sind entweder direkt angegeben oder als { min, max, ideal, exact }. Ohne Argument bzw. mit {} werden alle Einschränkungen entfernt. |
Rückgabewert
OverconstrainedError abgelehnt, wenn Pflichtvorgaben (min, max, exact) nicht erfüllbar sind. Dessen Eigenschaft constraint nennt die betroffene Einschränkung.Beispiele
Auflösung einer laufenden Kamera ändern
const stream = await navigator.mediaDevices.getUserMedia({ video: true });
const [track] = stream.getVideoTracks();
// Einfache Werte gelten als „ideal“ – der Browser nähert sich an
await track.applyConstraints({ width: 1280, height: 720, frameRate: 30 });
const { width, height, frameRate } = track.getSettings();
console.log(`Aktiv: ${width}x${height} @ ${frameRate} fps`);Pflichtvorgaben mit Fehlerbehandlung (OverconstrainedError)
const stream = await navigator.mediaDevices.getUserMedia({ video: true });
const [track] = stream.getVideoTracks();
try {
await track.applyConstraints({
width: { exact: 3840 },
height: { exact: 2160 }
});
console.log('4K aktiv');
} catch (err) {
if (err.name === 'OverconstrainedError') {
console.warn(`Nicht erfüllbar: ${err.constraint}`);
// Ausweichlösung: Full HD als Idealwert
await track.applyConstraints({ width: { ideal: 1920 }, height: { ideal: 1080 } });
} else {
throw err;
}
}Nur eine Eigenschaft ändern, die übrigen behalten
const stream = await navigator.mediaDevices.getUserMedia({
audio: { echoCancellation: true, noiseSuppression: true }
});
const [mic] = stream.getAudioTracks();
const toggleNoiseSuppression = async (enabled) => {
// applyConstraints ersetzt ALLE Einschränkungen – daher bestehende übernehmen
const current = mic.getConstraints();
await mic.applyConstraints({ ...current, noiseSuppression: enabled });
console.log('Rauschunterdrückung:', mic.getSettings().noiseSuppression);
};
await toggleNoiseSuppression(false);Bildrate an die Gerätefähigkeiten anpassen (z. B. bei schwacher Verbindung)
const stream = await navigator.mediaDevices.getUserMedia({ video: true });
const [track] = stream.getVideoTracks();
const caps = track.getCapabilities?.() ?? {};
const minFps = caps.frameRate?.min ?? 5;
const target = Math.max(minFps, 15);
await track.applyConstraints({
...track.getConstraints(),
frameRate: { max: target }
});
console.log('Bildrate jetzt:', track.getSettings().frameRate);// Wichtig · Fallstricke
- Einschränkungen werden ersetzt, nicht ergänzt: Jeder Aufruf überschreibt alle bisherigen Einschränkungen. Wenn du nur einen Wert ändern willst, führe ihn mit
getConstraints()zusammen. - „ideal“ vs. Pflicht: Einfache Werte werden nur angestrebt. Mit
exact,minundmaxkann einOverconstrainedErrorausgelöst werden. Prüfe deshalb nach dem Aufruf immer die tatsächlichen Werte mitgetSettings(). - Unterstützung prüfen: Nicht jeder Browser kennt jede Einschränkung. Unbekannte Eigenschaften werden stillschweigend ignoriert. Frage die unterstützten Eigenschaften mit
navigator.mediaDevices.getSupportedConstraints()ab.getCapabilities()fehlt in älteren Firefox-Versionen. - Audio-Einschränkungen: Das nachträgliche Ändern von
echoCancellation,noiseSuppressionodersampleRatewird je nach Browser (vor allem Safari und ältere Chrome-Versionen) nicht oder nur eingeschränkt unterstützt. Manchmal hilft nur ein neuergetUserMedia()-Aufruf. - Beendete Tracks: Bei einem Track mit
readyState === 'ended'hat der Aufruf keine Wirkung. - Nur in sicheren Kontexten (HTTPS) verfügbar, wie die gesamte Media-Capture-API.
- Viele gleichzeitige oder schnell aufeinanderfolgende Aufrufe können kurz Bildaussetzer verursachen, weil die Kamera neu konfiguriert wird. Warte deshalb auf das Promise, bevor du den nächsten Aufruf startest.