Signatur
Beschreibung
MediaTrackConstraints ist keine Klasse, die man mit new erzeugt, sondern ein einfaches Objekt (ein Dictionary). Es beschreibt, welche Eigenschaften ein Audio- oder Video-Track haben soll. Verwendet wird es vor allem in navigator.mediaDevices.getUserMedia(), getDisplayMedia() und MediaStreamTrack.prototype.applyConstraints(). Mit MediaStreamTrack.prototype.getConstraints() liest man die aktuell gesetzten Vorgaben wieder aus.
Jede Eigenschaft kann als einfacher Wert oder als Objekt mit den Schlüsseln min, max, ideal und exact angegeben werden. Einfache Werte und ideal sind Wünsche: Der Browser versucht, möglichst nah heranzukommen. min, max und exact sind harte Vorgaben. Lassen sie sich nicht erfüllen, wird das Promise mit einem OverconstrainedError abgelehnt.
Die wichtigsten Gruppen:
- Allgemein:
deviceId,groupId - Video:
width,height,aspectRatio,frameRate,facingMode,resizeMode - Audio:
echoCancellation,noiseSuppression,autoGainControl,sampleRate,sampleSize,channelCount,latency - Bildschirmfreigabe:
displaySurface,logicalSurface - Erweitert:
advanced, ein Array weiterer Vorgaben-Sätze, die der Reihe nach versucht und übersprungen werden, wenn sie sich nicht erfüllen lassen
Welche Vorgaben der aktuelle Browser überhaupt kennt, verrät navigator.mediaDevices.getSupportedConstraints(). Welche Werte ein konkretes Gerät unterstützt, liefert track.getCapabilities().
Rückgabewert
getUserMedia(), getDisplayMedia() oder applyConstraints(); zurückgegeben wird es von getConstraints().Beispiele
Kamera mit bevorzugter HD-Auflösung anfordern
const constraints = {
video: {
width: { ideal: 1280 },
height: { ideal: 720 },
frameRate: { ideal: 30, max: 60 },
facingMode: 'user'
},
audio: {
echoCancellation: true,
noiseSuppression: true
}
};
const start = async () => {
try {
const stream = await navigator.mediaDevices.getUserMedia(constraints);
document.querySelector('video').srcObject = stream;
const [videoTrack] = stream.getVideoTracks();
console.log(videoTrack.getSettings());
} catch (err) {
console.error(err.name, err.message);
}
};
start();Harte Vorgaben und OverconstrainedError abfangen
const openRearCamera = async () => {
try {
return await navigator.mediaDevices.getUserMedia({
video: {
facingMode: { exact: 'environment' },
width: { min: 1920 }
}
});
} catch (err) {
if (err.name === 'OverconstrainedError') {
console.warn(`Nicht erfüllbar: ${err.constraint}`);
// Ausweichlösung mit weichen Vorgaben
return navigator.mediaDevices.getUserMedia({ video: { facingMode: 'environment' } });
}
throw err;
}
};
openRearCamera().then((s) => console.log('Tracks:', s.getTracks().length));Vorgaben eines laufenden Tracks ändern und auslesen
const stream = await navigator.mediaDevices.getUserMedia({ video: true });
const [track] = stream.getVideoTracks();
const caps = track.getCapabilities();
console.log('Max. Breite:', caps.width?.max);
await track.applyConstraints({
width: { ideal: 640 },
advanced: [{ frameRate: 15 }]
});
console.log(track.getConstraints());Unterstützte Vorgaben prüfen und ein bestimmtes Mikrofon wählen
const supported = navigator.mediaDevices.getSupportedConstraints();
console.log('sampleRate unterstützt:', !!supported.sampleRate);
const devices = await navigator.mediaDevices.enumerateDevices();
const mic = devices.find((d) => d.kind === 'audioinput');
const stream = await navigator.mediaDevices.getUserMedia({
audio: {
deviceId: mic ? { exact: mic.deviceId } : undefined,
channelCount: 1,
...(supported.sampleRate && { sampleRate: 48000 })
}
});
console.log(stream.getAudioTracks()[0].label);