Signatur
Beschreibung
Die schreibgeschützte Eigenschaft height des Wörterbuchs RTCVideoSourceStats enthält die Höhe in Pixeln des zuletzt gelieferten Frames einer lokalen Videoquelle. Solche Statistikobjekte bekommst du über RTCPeerConnection.getStats() oder RTCRtpSender.getStats(). Du erkennst sie am Eintrag type === "media-source" zusammen mit kind === "video".
Der Wert beschreibt die Auflösung vor der Kodierung, also so, wie der MediaStreamTrack die Frames erzeugt. Das ist nicht unbedingt die Auflösung, die tatsächlich gesendet wird. Wenn der Encoder wegen knapper Bandbreite oder hoher CPU-Last herunterskaliert oder Simulcast nutzt, findest du die gesendete Höhe in RTCOutboundRtpStreamStats.frameHeight.
Typische Einsatzfälle sind die Diagnose von Kamera-Einschränkungen (etwa ob getUserMedia-Vorgaben wie height: 720 eingehalten werden), Qualitäts-Dashboards und der Vergleich zwischen Quell- und Sendeauflösung, um eine Herunterskalierung zu erkennen.
Rückgabewert
undefined, solange noch kein Frame von der Quelle geliefert wurde.Beispiele
Auflösung der lokalen Kamera auslesen
const pc = new RTCPeerConnection();
const stream = await navigator.mediaDevices.getUserMedia({ video: { height: 720 } });
stream.getTracks().forEach((track) => pc.addTrack(track, stream));
// Kurz warten, bis erste Frames geliefert wurden
await new Promise((r) => setTimeout(r, 1000));
const report = await pc.getStats();
report.forEach((stats) => {
if (stats.type === 'media-source' && stats.kind === 'video') {
console.log(`Quelle: ${stats.width}x${stats.height} @ ${stats.framesPerSecond} fps`);
}
});Herunterskalierung durch den Encoder erkennen
const checkScaling = async (sender) => {
const report = await sender.getStats();
let source, outbound;
report.forEach((s) => {
if (s.type === 'media-source' && s.kind === 'video') source = s;
if (s.type === 'outbound-rtp' && s.kind === 'video') outbound = s;
});
if (!source?.height || !outbound?.frameHeight) return;
const ratio = outbound.frameHeight / source.height;
if (ratio < 1) {
console.warn(`Skaliert: ${source.height}p → ${outbound.frameHeight}p (Grund: ${outbound.qualityLimitationReason})`);
}
};
const [videoSender] = pc.getSenders().filter((s) => s.track?.kind === 'video');
setInterval(() => checkScaling(videoSender), 2000);Wechsel der Quellauflösung überwachen (z. B. Bildschirmfreigabe)
let lastHeight;
const monitor = async (pc) => {
const report = await pc.getStats();
for (const s of report.values()) {
if (s.type === 'media-source' && s.kind === 'video' && s.height !== lastHeight) {
console.log(`Neue Quellhöhe: ${s.height ?? 'noch kein Frame'}`);
lastHeight = s.height;
}
}
};
setInterval(() => monitor(pc), 1000);// Wichtig · Fallstricke
- Nicht mit der gesendeten Auflösung verwechseln:
heightgibt die Auflösung der Quelle an. Was tatsächlich gesendet wird, steht inRTCOutboundRtpStreamStats.frameHeight, und die beiden Werte können sich unterscheiden. - Der Wert kann
undefinedsein, solange noch kein Frame geliefert wurde. Prüfe ihn deshalb vorher, zum Beispiel mit?.oder??. - Bei Bildschirmfreigabe oder gedrehten Mobilgeräten ändert sich die Höhe während der Verbindung. Frage den Wert deshalb regelmäßig ab, statt ihn nur einmal zu lesen.
- Browser-Kompatibilität: Chromium-Browser und Safari unterstützen
RTCVideoSourceStats. Firefox liefert bisher keinemedia-source-Einträge für Video. Prüfe also, ob die Eigenschaft vorhanden ist, bevor du sie auswertest. - Die Statistiken liegen nur für lokale Tracks vor, die über einen
RTCRtpSenderangebunden sind. Für empfangene Streams gibt es sie nicht.