MediaKeys.getStatusForPolicy() — Methode · JavaScript-Referenz

Signatur

MediaKeys.prototype.getStatusForPolicy(policy)

Beschreibung

Die Methode getStatusForPolicy() gehört zu den Encrypted Media Extensions (EME). Mit ihr prüft eine Anwendung vorab, ob das CDM verschlüsselte Inhalte unter einer bestimmten Richtlinie wiedergeben könnte, also etwa mit einem Schlüssel, der mindestens HDCP 2.2 am Ausgang verlangt. Eine Lizenz muss man dafür nicht anfordern, und eine MediaKeySession ist auch nicht nötig.

Typisch ist der Einsatz beim adaptiven Streaming: Bevor ein Player UHD- oder HDR-Varianten in die Auswahl nimmt, fragt er ab, ob die Ausgabekette (Grafikkarte, Kabel, Monitor) die nötige HDCP-Version unterstützt. Ist das nicht der Fall, wählt er gleich eine niedrigere Qualitätsstufe. So bleibt der Bildschirm nicht schwarz, und Lizenzanfragen, die ohnehin scheitern würden, fallen weg.

Die Promise wird mit einem MediaKeyStatus-String erfüllt. Die wichtigsten Werte sind "usable" (Wiedergabe möglich) und "output-restricted" (Richtlinie am Ausgang nicht erfüllbar). Möglich sind auch "output-downscaled", "status-pending" oder "internal-error". Die Methode steht nur auf einem MediaKeys-Objekt zur Verfügung, das man über navigator.requestMediaKeySystemAccess() und MediaKeySystemAccess.createMediaKeys() erhält.

Parameter

Name	Typ	Default	Beschreibung
$policy Pflicht	MediaKeysPolicy (Object)		Dictionary mit der Richtlinie, die geprüft werden soll. Aktuell gibt es nur die Eigenschaft `minHdcpVersion` (String), z. B. `"1.0"`, `"1.4"`, `"2.2"` oder `"2.3"`. Ist keine Eigenschaft gesetzt, wird die Promise mit `TypeError` abgelehnt.

Rückgabewert

Typ

Promise<MediaKeyStatus>

Beschreibung

Eine Promise, die mit einem MediaKeyStatus-String erfüllt wird, etwa "usable", "output-restricted", "output-downscaled", "status-pending" oder "internal-error". Abgelehnt wird sie mit TypeError (leere oder ungültige Richtlinie), NotSupportedError (Richtlinie oder Methode vom CDM nicht unterstützt) oder InvalidStateError.

Beispiele

HDCP-2.2-Unterstützung mit Widevine prüfen

const config = [{
  initDataTypes: ['cenc'],
  videoCapabilities: [{ contentType: 'video/mp4; codecs="avc1.640028"' }]
}];

const checkHdcp = async () => {
  const access = await navigator.requestMediaKeySystemAccess('com.widevine.alpha', config);
  const mediaKeys = await access.createMediaKeys();

  const status = await mediaKeys.getStatusForPolicy({ minHdcpVersion: '2.2' });
  console.log(`HDCP 2.2: ${status}`);
};

checkHdcp().catch(err => console.error(err.name, err.message));

HDCP 2.2: usable

Höchste verfügbare HDCP-Version ermitteln

const HDCP_VERSIONS = ['2.3', '2.2', '2.1', '2.0', '1.4', '1.0'];

const getMaxHdcpVersion = async (mediaKeys) => {
  if (typeof mediaKeys.getStatusForPolicy !== 'function') return null;

  for (const version of HDCP_VERSIONS) {
    try {
      const status = await mediaKeys.getStatusForPolicy({ minHdcpVersion: version });
      if (status === 'usable') return version;
    } catch (err) {
      // Version vom CDM nicht unterstützt: nächste probieren
      if (err.name !== 'NotSupportedError') throw err;
    }
  }
  return 'keine';
};

// Verwendung (mediaKeys aus createMediaKeys()):
// console.log(await getMaxHdcpVersion(mediaKeys));

1.4

Qualitätsstufe für adaptives Streaming wählen

const selectMaxResolution = async (mediaKeys) => {
  // Ohne API-Unterstützung vorsichtig auf HD begrenzen
  if (!('getStatusForPolicy' in mediaKeys)) return 1080;

  try {
    const status = await mediaKeys.getStatusForPolicy({ minHdcpVersion: '2.2' });
    return status === 'usable' ? 2160 : 1080;
  } catch {
    return 720;
  }
};

// const maxHeight = await selectMaxResolution(mediaKeys);
// player.setMaxVideoHeight(maxHeight);

2160

// Wichtig · Fallstricke

Experimentell und nur teilweise unterstützt: Chromium-Browser (Chrome, Edge, Opera) bieten die Methode seit Version 73 an, Firefox und Safari nicht. Vor dem Aufruf deshalb mit 'getStatusForPolicy' in mediaKeys prüfen und eine Ersatzlösung vorsehen.
Sicherer Kontext: EME und damit diese Methode stehen nur über HTTPS (oder localhost) zur Verfügung. In iframes muss die Permissions-Policy encrypted-media erlaubt sein.
Das Ergebnis ist eine Momentaufnahme: Wird später ein anderer Monitor oder ein anderes Kabel angeschlossen, kann sich der Status ändern. Während der Wiedergabe deshalb zusätzlich das keystatuseschange-Ereignis der MediaKeySession beobachten.
Auch wenn das CDM die HDCP-Anforderung erfüllt, entscheidet der Lizenzserver weiterhin selbst, welche Schlüssel er ausliefert.
Bei Clear Key (org.w3.clearkey) gibt es keinen HDCP-Schutz. Die Methode ist dort meist nicht sinnvoll oder wird mit NotSupportedError abgelehnt.
Datenschutz: Die Antworten verraten etwas über die Hardware und können zum Fingerprinting beitragen. Browser können die Ergebnisse deshalb vereinheitlichen oder einschränken.

Siehe auch

MediaKeys.createSession() MediaKeys.setServerCertificate() MediaKeyStatusMap.forEach() MediaKeyStatusMap.get() MediaKeyStatusMap.has()