HTMLMediaElement.mediaKeys — Eigenschaft · JavaScript-Referenz

Signatur

get HTMLMediaElement.mediaKeys

Beschreibung

Die schreibgeschützte Eigenschaft mediaKeys eines <video>- oder <audio>-Elements gehört zu den Encrypted Media Extensions (EME). Sie liefert das MediaKeys-Objekt, das dem Element aktuell zugeordnet ist. Dieses Objekt steht für einen Satz Schlüssel, die ein Content Decryption Module (CDM) wie Widevine, PlayReady, FairPlay oder Clear Key zum Entschlüsseln geschützter Inhalte nutzt. Ist noch kein Objekt zugeordnet, ist der Wert null.

Die Eigenschaft selbst lässt sich nicht beschreiben. Zugeordnet wird ein Objekt über die Methode HTMLMediaElement.setMediaKeys(). Der übliche Ablauf: Mit navigator.requestMediaKeySystemAccess() ein Schlüsselsystem anfragen, per MediaKeySystemAccess.createMediaKeys() ein MediaKeys-Objekt erzeugen, es mit setMediaKeys() an das Element binden und anschließend beim encrypted-Event über mediaKeys.createSession() eine Lizenzsitzung öffnen.

Gebraucht wird mediaKeys vor allem, um zu prüfen, ob ein Element schon für DRM eingerichtet ist (damit man es nicht doppelt initialisiert), und um im encrypted-Handler an das passende Objekt für neue Sitzungen zu kommen.

Rückgabewert

Typ

MediaKeys | null

Beschreibung

Das dem Element zugeordnete MediaKeys-Objekt oder null, wenn noch keines gesetzt wurde.

Beispiele

Prüfen, ob schon MediaKeys gesetzt sind

const video = document.querySelector('video');

if (video.mediaKeys === null) {
  console.log('Noch kein Schlüsselsystem zugeordnet.');
} else {
  console.log('MediaKeys aktiv:', video.mediaKeys);
}

Noch kein Schlüsselsystem zugeordnet.

Clear Key einrichten und mediaKeys auslesen

const video = document.querySelector('video');

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

const setupDrm = async () => {
  const access = await navigator.requestMediaKeySystemAccess('org.w3.clearkey', config);
  const keys = await access.createMediaKeys();
  await video.setMediaKeys(keys);
  console.log(video.mediaKeys === keys);
};

setupDrm().catch((err) => console.error('EME nicht verfügbar:', err));

true

Sitzung im encrypted-Event über mediaKeys erzeugen

const video = document.querySelector('video');

video.addEventListener('encrypted', async (event) => {
  // Das zugeordnete MediaKeys-Objekt verwenden
  const keys = video.mediaKeys;
  if (!keys) {
    console.warn('Keine MediaKeys gesetzt – zuerst setMediaKeys() aufrufen.');
    return;
  }

  const session = keys.createSession();
  session.addEventListener('message', async (msg) => {
    // Lizenzanfrage an den eigenen Lizenzserver schicken
    const res = await fetch('/license', { method: 'POST', body: msg.message });
    await session.update(await res.arrayBuffer());
  });

  await session.generateRequest(event.initDataType, event.initData);
});

MediaKeys wieder lösen

const video = document.querySelector('video');

const resetDrm = async () => {
  await video.setMediaKeys(null);
  console.log(video.mediaKeys);
};

resetDrm();

null

// Wichtig · Fallstricke

Schreibgeschützt: video.mediaKeys = keys bewirkt nichts (im Strict Mode gibt es einen TypeError). Zum Setzen immer das Promise-basierte setMediaKeys() nehmen und darauf warten.
Sicherer Kontext: EME läuft nur über HTTPS (bzw. localhost). In iframes muss außerdem die Permissions Policy encrypted-media erlaubt sein.
Browser-Unterschiede: Welche Schlüsselsysteme verfügbar sind, hängt vom Browser ab. Chrome, Edge und Firefox bringen Widevine mit, Edge zusätzlich PlayReady, Safari setzt auf FairPlay (com.apple.fps). Alle bieten Clear Key an. Ältere Safari-Versionen hatten nur das präfixierte webkitKeys.
Ein MediaKeys-Objekt lässt sich meist nur mit einem Element gleichzeitig verwenden. Beim Neuzuordnen während der Wiedergabe kann setMediaKeys() mit einem Fehler abgelehnt werden.
In privaten Fenstern oder mit deaktiviertem DRM (z. B. in Firefox) schlägt requestMediaKeySystemAccess() fehl, und mediaKeys bleibt null. Dafür eine Rückfalllösung vorsehen.

Siehe auch

HTMLMediaElement.mediaGroup HTMLMediaElement.ended HTMLMediaElement.muted HTMLMediaElement.played HTMLMediaElement.remote