MediaKeyStatusMap.get() — Methode · JavaScript-Referenz

Signatur

MediaKeyStatusMap.prototype.get(keyId)

Beschreibung

Die Methode get() gehört zur Schnittstelle MediaKeyStatusMap der Encrypted Media Extensions (EME). Eine solche Map erreicht man über MediaKeySession.keyStatuses. Sie ist schreibgeschützt und ordnet jeder Schlüssel-ID (Key ID) einer DRM-Sitzung ihren aktuellen Status zu.

Mit get() fragen Sie gezielt den Status einer bekannten Schlüssel-ID ab, etwa die ID aus dem tenc-Block der Medieninitialisierungsdaten oder aus dem Manifest (DASH cenc:default_KID). Das ist nützlich, um vor dem Wechsel auf eine andere Qualitätsstufe zu prüfen, ob der passende Schlüssel verwendbar ist oder ob z. B. eine Ausgabebeschränkung ("output-restricted") greift.

Mögliche Statuswerte sind: "usable", "expired", "released", "output-restricted", "output-downscaled", "usable-in-future", "status-pending" und "internal-error". Die Map ändert sich dynamisch; auf Änderungen reagiert man über das Event keystatuseschange der Sitzung.

Parameter

Name	Typ	Default	Beschreibung
$keyId Pflicht	BufferSource (ArrayBuffer \| TypedArray \| DataView)		Die Schlüssel-ID als Binärdaten (bei ClearKey/CENC meist 16 Byte). Verglichen wird der Byte-Inhalt, nicht die Objektidentität.

Rückgabewert

Typ

string | undefined

Beschreibung

Der MediaKeyStatus-String für die angegebene Schlüssel-ID oder undefined, wenn die ID in der Map nicht vorkommt.

Beispiele

Status einer bekannten Key-ID nach Statusänderung prüfen

// Hex-String (z. B. aus dem DASH-Manifest) in Uint8Array umwandeln
const hexToBytes = (hex) =>
  new Uint8Array(hex.match(/../g).map((b) => parseInt(b, 16)));

const keyId = hexToBytes('0123456789abcdef0123456789abcdef');

session.addEventListener('keystatuseschange', () => {
  const status = session.keyStatuses.get(keyId);
  console.log('Status des Schlüssels:', status);
});

Status des Schlüssels: usable

Vor einem Qualitätswechsel prüfen, ob der Schlüssel nutzbar ist

const canPlayWithKey = (session, keyId) => {
  const status = session.keyStatuses.get(keyId);
  if (status === undefined) return false; // Schlüssel (noch) nicht bekannt
  return status === 'usable' || status === 'output-downscaled';
};

if (!canPlayWithKey(session, hdKeyId)) {
  console.warn('HD-Schlüssel nicht verfügbar – bleibe bei SD');
}

HD-Schlüssel nicht verfügbar – bleibe bei SD

Vollständiger ClearKey-Ablauf mit has() und get()

const setupClearKey = async (video, initDataType, initData, keyId) => {
  const access = await navigator.requestMediaKeySystemAccess('org.w3.clearkey', [{
    initDataTypes: [initDataType],
    videoCapabilities: [{ contentType: 'video/mp4; codecs="avc1.42E01E"' }]
  }]);
  const mediaKeys = await access.createMediaKeys();
  await video.setMediaKeys(mediaKeys);

  const session = mediaKeys.createSession();
  session.addEventListener('keystatuseschange', () => {
    if (session.keyStatuses.has(keyId)) {
      console.log('Key-Status:', session.keyStatuses.get(keyId));
    }
  });
  await session.generateRequest(initDataType, initData);
  return session;
};

Key-Status: usable

// Wichtig · Fallstricke

Nur Binärdaten als Schlüssel: Ein Hex- oder Base64-String als Argument findet nichts – er muss erst in ein Uint8Array/ArrayBuffer umgewandelt werden. Bei ClearKey-Lizenzen liegen IDs oft als Base64url vor.
Die Map ist direkt nach createSession() leer; get() liefert dann undefined. Zuverlässig abfragen erst nach dem Event keystatuseschange.
Ältere Chrome-Versionen (vor ca. 2017) gaben die Key-ID in forEach() in vertauschter Argumentreihenfolge zurück; get() selbst ist davon nicht betroffen.
EME ist nur in sicheren Kontexten (HTTPS) verfügbar. Welche Status tatsächlich auftreten, hängt vom Key-System (Widevine, PlayReady, FairPlay, ClearKey) ab.

Siehe auch

KeyboardLayoutMap.get() MediaKeyStatusMap.has() MediaKeyStatusMap.keys() MediaKeyStatusMap.values() MediaKeyStatusMap.entries()