Signatur
Beschreibung
Die schreibgeschützte Eigenschaft keyStatuses einer MediaKeySession gibt eine MediaKeyStatusMap zurück. Die Map ordnet jeder Schlüssel-ID (BufferSource) einen Status-String zu, etwa "usable", "expired", "released", "output-restricted", "output-downscaled", "usable-in-future", "status-pending" oder "internal-error".
Gebraucht wird die Eigenschaft in DRM-Playern, die auf den Encrypted Media Extensions (EME) aufbauen. Mit ihr lässt sich prüfen, ob die Lizenz vom Content Decryption Module (CDM) angenommen wurde, ob Schlüssel abgelaufen sind oder ob die Ausgabe eingeschränkt ist, z. B. weil HDCP fehlt. So kann der Player gezielt reagieren: eine niedrigere Auflösung wählen, die Lizenz erneuern oder eine Fehlermeldung anzeigen.
Die Map ändert sich, sobald das CDM neue Informationen hat, meist nach MediaKeySession.update(). Jede Änderung meldet das Ereignis keystatuseschange. Man sollte die Map deshalb im Handler dieses Ereignisses auswerten und nicht nur einmal direkt nach dem Erstellen der Sitzung.
Rückgabewert
ArrayBuffer) als Schlüsseln und Status-Strings als Werten. Sie bietet size, get(), has(), forEach(), entries(), keys(), values() und ist iterierbar.Beispiele
Schlüsselstatus beim Ereignis keystatuseschange ausgeben
const toHex = (buf) =>
[...new Uint8Array(buf)].map((b) => b.toString(16).padStart(2, '0')).join('');
session.addEventListener('keystatuseschange', () => {
for (const [keyId, status] of session.keyStatuses) {
console.log(`Schlüssel ${toHex(keyId)}: ${status}`);
}
});Auf abgelaufene oder eingeschränkte Schlüssel reagieren
session.addEventListener('keystatuseschange', async () => {
const statuses = [...session.keyStatuses.values()];
if (statuses.includes('expired')) {
console.warn('Lizenz abgelaufen, Sitzung wird geschlossen.');
await session.close();
} else if (statuses.includes('output-restricted')) {
console.warn('Ausgabe eingeschränkt (z. B. HDCP fehlt), niedrigere Qualität wählen.');
// z. B. player.selectMaxHeight(480);
} else if (statuses.every((s) => s === 'usable')) {
console.log(`Alle ${session.keyStatuses.size} Schlüssel nutzbar.`);
}
});Status einer bestimmten Schlüssel-ID abfragen
// Key-ID als Hex-String, z. B. aus dem Manifest (default_KID)
const hexToBytes = (hex) =>
new Uint8Array(hex.match(/../g).map((h) => parseInt(h, 16)));
const kid = hexToBytes('1a2b3c4d5e6f708192a3b4c5d6e7f801');
if (session.keyStatuses.has(kid)) {
console.log('Status:', session.keyStatuses.get(kid));
} else {
console.log('Schlüssel noch nicht bekannt (Lizenz fehlt?)');
}// Wichtig · Fallstricke
- Direkt nach
createSession()und vor dem erstenupdate()ist die Map normalerweise leer (size === 0). Werten Sie sie deshalb im Ereigniskeystatuseschangeaus. - Die Schlüssel der Map sind Binärdaten (
ArrayBuffer).get()undhas()vergleichen den Inhalt der Bytes, nicht die Objektreferenz. Zum Ausgeben in der Konsole oder für Logs wandeln Sie die IDs selbst in Hex um. - Was genau gemeldet wird, hängt vom CDM ab (Widevine, PlayReady, FairPlay, Clear Key). Manche CDMs verwenden z. B.
"output-downscaled"nicht, oder sie melden eine Ersatz-Schlüssel-ID statt der echten. - Der Status
"usable-in-future"ist neuer als die übrigen Status und wird noch nicht überall unterstützt. Fangen Sie unbekannte Status-Strings deshalb im Code ab. - EME steht nur in sicheren Kontexten (HTTPS) zur Verfügung. Moderne Browser unterstützen es, auf manchen Linux- oder Chromium-Varianten fehlen aber proprietäre CDMs.