Signatur
Beschreibung
Die Eigenschaft screenPixelRatio des Wörterbuchs MediaTrackSettings ist eine Zahl (number). Sie gibt an, wie groß ein physisches Pixel der erfassten Anzeigefläche (bei ihrer physischen Auflösung) im Verhältnis zu einem logischen CSS-Pixel auf dem aufnehmenden Bildschirm ist. Bei einem HiDPI-/Retina-Monitor mit doppelter Pixeldichte liegt der Wert typischerweise bei 2.
Die Eigenschaft gibt es nur bei Videospuren aus der Bildschirmaufnahme, also aus navigator.mediaDevices.getDisplayMedia(). Kamera- und Mikrofonspuren liefern sie nicht. Du liest sie über MediaStreamTrack.getSettings() aus.
Wichtig ist sie vor allem, um zwischen physischer und logischer Auflösung umzurechnen. Teilst du width und height der Einstellungen durch screenPixelRatio, erhältst du die logische Größe der Fläche. Mit dieser Größe kannst du zum Beispiel per applyConstraints() Bandbreite sparen, etwa bei Videokonferenzen, in denen Text-Schärfe weniger wichtig ist als eine flüssige Übertragung. Ein Koordinaten-Abgleich zwischen dem Video und der Oberfläche ist damit ebenfalls möglich.
Der Wert ist eine reine Einstellung und keine Beschränkung (Constraint). Du kannst ihn also nur lesen und nicht über getDisplayMedia() oder applyConstraints() vorgeben.
Rückgabewert
1, 1.25 oder 2. Den Wert undefined bekommst du, wenn die Spur keine Bildschirmaufnahme ist oder der Browser die Eigenschaft nicht unterstützt.Beispiele
Pixelverhältnis einer Bildschirmaufnahme auslesen
const startCapture = async () => {
const stream = await navigator.mediaDevices.getDisplayMedia({ video: true });
const [track] = stream.getVideoTracks();
const { width, height, screenPixelRatio } = track.getSettings();
console.log(`Physisch: ${width}x${height}`);
console.log(`screenPixelRatio: ${screenPixelRatio ?? 'nicht unterstützt'}`);
};
document.querySelector('#share').addEventListener('click', startCapture);Logische Auflösung berechnen und Aufnahme herunterskalieren
const captureAtLogicalSize = async () => {
const stream = await navigator.mediaDevices.getDisplayMedia({ video: true });
const [track] = stream.getVideoTracks();
const { width, height, screenPixelRatio } = track.getSettings();
if (typeof screenPixelRatio === 'number' && screenPixelRatio > 1) {
const logicalWidth = Math.round(width / screenPixelRatio);
const logicalHeight = Math.round(height / screenPixelRatio);
// Bandbreite sparen: nur in logischer Auflösung übertragen
await track.applyConstraints({ width: logicalWidth, height: logicalHeight });
console.log('Neu:', track.getSettings().width, track.getSettings().height);
}
return stream;
};
document.querySelector('#share').addEventListener('click', captureAtLogicalSize);Unterstützung per Feature-Erkennung prüfen
const supported = navigator.mediaDevices.getSupportedConstraints();
if ('screenPixelRatio' in supported) {
console.log('screenPixelRatio wird unterstützt');
} else {
console.log('Fallback: Pixelverhältnis unbekannt, physische Auflösung verwenden');
}// Wichtig · Fallstricke
- Experimentell: Bisher unterstützen nur Chromium-basierte Browser die Eigenschaft. In Firefox und Safari ist sie
undefined. Prüfe sie deshalb immer mit??odertypeofund sieh einen Ersatzweg vor. - Nur für Bildschirmaufnahmen: Bei Spuren aus
getUserMedia()(Kamera, Mikrofon) fehlt die Eigenschaft. - Nicht als Constraint setzbar: Wenn du
screenPixelRatioangetDisplayMedia()oderapplyConstraints()übergibst, hat das keine Wirkung. Der Wert lässt sich nur lesen. - Nicht dasselbe wie
window.devicePixelRatio:devicePixelRatiobezieht sich auf das aktuelle Dokument.screenPixelRatiodagegen beschreibt die erfasste Fläche, und die kann ein anderer Monitor mit anderer Skalierung sein. - Wert kann sich ändern: Wenn Nutzer die Quelle wechseln oder ein Fenster auf einen anderen Monitor ziehen, ändert sich der Wert möglicherweise. Lies ihn bei Bedarf erneut mit
getSettings()aus. - Nur in sicheren Kontexten (HTTPS) verfügbar. Außerdem muss eine Nutzeraktion die Aufnahme auslösen, zum Beispiel ein Klick.