PressureObserver — Schnittstelle · JavaScript-Referenz

Signatur

interface PressureObserver

Beschreibung

PressureObserver ist die zentrale Schnittstelle der Compute Pressure API. Mit ihr erfährt eine Webanwendung, wie stark eine Systemressource gerade ausgelastet ist, z. B. die CPU ("cpu"). Genaue Messwerte wie Prozent oder Taktfrequenz liefert sie nicht. Stattdessen meldet sie aus Datenschutzgründen nur vier grobe Zustände: "nominal", "fair", "serious" und "critical".

Typische Einsatzfälle sind Videokonferenzen, Spiele, Streaming und rechenintensive Editoren. Diese Anwendungen können bei hoher Last ihre Arbeit verringern und so Ruckeln, Überhitzung und schnelle Akkuentladung vermeiden. Beispiele: weniger Videokacheln anzeigen, die Auflösung senken, Effekte wie das Weichzeichnen des Hintergrunds abschalten oder weniger Arbeit an Web Worker verteilen.

Die Nutzung folgt dem bekannten Observer-Muster:

Mit new PressureObserver(callback) wird ein Observer erzeugt.
observe(source, options) startet die Beobachtung einer Quelle und gibt ein Promise zurück.
unobserve(source) beendet die Beobachtung einer einzelnen Quelle, disconnect() beendet alle.
takeRecords() leert die Warteschlange noch nicht zugestellter Einträge und gibt sie zurück.

Welche Quellen der Browser unterstützt, steht in der statischen Eigenschaft PressureObserver.knownSources. Der Callback bekommt ein Array von PressureRecord-Objekten mit den Feldern source, state und time. Er wird nur aufgerufen, wenn sich der Zustand ändert, nicht bei jeder Messung.

Parameter

Name	Typ	Default	Beschreibung
$callback Pflicht	(records: PressureRecord[], observer: PressureObserver) => void		Parameter des Konstruktors. Wird bei jeder Zustandsänderung aufgerufen und erhält ein Array von `PressureRecord`-Objekten sowie den Observer selbst.
$source Pflicht	"cpu" \| "thermal"		Parameter von `observe()` und `unobserve()`: die zu beobachtende Quelle. In der Praxis wird derzeit nur `"cpu"` unterstützt. Welche Quellen verfügbar sind, zeigt `PressureObserver.knownSources`.
$options.sampleInterval	number	0	Option von `observe()`: gewünschter Mindestabstand zwischen zwei Messungen in Millisekunden. Der Browser darf den Wert nach oben anpassen.

Rückgabewert

Typ

PressureObserver

Beschreibung

Der Konstruktor gibt eine neue PressureObserver-Instanz zurück. observe() gibt ein Promise<undefined> zurück, takeRecords() ein PressureRecord[]. unobserve() und disconnect() geben undefined zurück.

Beispiele

Observer erzeugen und CPU-Druck beobachten

const observer = new PressureObserver((records) => {
  // Der letzte Eintrag ist der aktuellste
  const latest = records.at(-1);
  console.log(`${latest.source}: ${latest.state} (t=${Math.round(latest.time)} ms)`);
});

try {
  await observer.observe('cpu', { sampleInterval: 1000 });
  console.log('Beobachtung gestartet');
} catch (err) {
  // NotSupportedError, NotAllowedError …
  console.error('Compute Pressure nicht verfügbar:', err.name);
}

Beobachtung gestartet cpu: nominal (t=1532 ms) cpu: serious (t=9870 ms)

Funktionsprüfung mit knownSources

const supportsCpuPressure = () =>
  'PressureObserver' in globalThis &&
  PressureObserver.knownSources.includes('cpu');

if (supportsCpuPressure()) {
  console.log('Unterstützte Quellen:', PressureObserver.knownSources);
} else {
  console.log('Compute Pressure API wird nicht unterstützt – Fallback aktiv');
}

Unterstützte Quellen: ["cpu"]

Videoqualität in einer Videokonferenz anpassen

const qualityByState = {
  nominal: { width: 1280, frameRate: 30 },
  fair: { width: 960, frameRate: 30 },
  serious: { width: 640, frameRate: 24 },
  critical: { width: 320, frameRate: 15 }
};

const stream = await navigator.mediaDevices.getUserMedia({ video: true });
const [track] = stream.getVideoTracks();

const observer = new PressureObserver(async (records) => {
  const { state } = records.at(-1);
  await track.applyConstraints(qualityByState[state]);
  console.log(`CPU-Druck ${state} → ${qualityByState[state].width}px`);
});

await observer.observe('cpu', { sampleInterval: 2000 });

CPU-Druck serious → 640px

Beobachtung beenden und offene Einträge abholen

const observer = new PressureObserver((records) => {
  records.forEach((r) => console.log(r.toJSON()));
});
await observer.observe('cpu');

// Später, z. B. beim Verlassen des Anrufs:
const pending = observer.takeRecords();
console.log('Noch nicht zugestellt:', pending.length);

observer.unobserve('cpu'); // nur diese Quelle beenden
observer.disconnect();     // oder: alle Quellen beenden

Noch nicht zugestellt: 0

// Wichtig · Fallstricke

Browserunterstützung: Die API ist experimentell und nur in Chromium-basierten Desktop-Browsern verfügbar (Chrome/Edge ab Version 125). Firefox und Safari unterstützen sie nicht. Prüfen Sie deshalb vor der Nutzung immer, ob die API vorhanden ist, und sehen Sie einen Fallback vor.
Sicherer Kontext: Die API funktioniert nur über HTTPS bzw. localhost. Sie steht in Window, in Dedicated Workern und in Shared Workern zur Verfügung.
Berechtigungsrichtlinie: In iframes muss die Nutzung ausdrücklich erlaubt werden, z. B. mit allow="compute-pressure". Fehlt diese Freigabe, schlägt observe() mit NotAllowedError fehl. Eine nicht unterstützte Quelle führt zu NotSupportedError.
Datenschutz: Der Browser liefert bewusst nur grobe Zustände. Außerdem stellt er Einträge nur zu, wenn das Dokument sichtbar ist bzw. den Fokus hat, damit die Werte nicht als Seitenkanal zwischen Tabs missbraucht werden können. Erwarten Sie also keine Meldungen, solange der Tab im Hintergrund ist.
Keine Leistungsmessung: Der gemeldete Zustand beschreibt das gesamte System, nicht nur Ihre Seite. Andere Programme können ihn beeinflussen. Reagieren Sie deshalb mit Verzögerung (Hysterese), damit die Qualität nicht ständig hin- und herspringt.
sampleInterval ist nur ein Wunschwert. Der Callback wird ausschließlich bei einer Zustandsänderung aufgerufen.
Rufen Sie disconnect() auf, wenn Sie den Observer nicht mehr brauchen, damit keine Ressourcen unnötig gebunden bleiben.

Siehe auch

ResizeObserver FileSystemObserver PressureRecord MutationObserver PerformanceObserver ResizeObserverSize