MediaKeySession.remove() — Methode · JavaScript-Referenz

Signatur

MediaKeySession.prototype.remove()

Beschreibung

Die Methode remove() gehört zur Schnittstelle MediaKeySession der Encrypted Media Extensions (EME). Sie weist das Content Decryption Module (CDM) an, alle Lizenzen und Schlüssel zu löschen, die zu dieser Sitzung gehören. Das zurückgegebene Promise wird erfüllt, sobald das CDM den Auftrag angenommen hat.

Am meisten bringt remove() bei Sitzungen vom Typ "persistent-license". Hier löscht das CDM die gespeicherte Lizenz und erzeugt einen Freigabenachweis (englisch „record of license destruction“). Diesen Nachweis bekommst du über ein message-Event mit messageType === "license-release". Du schickst ihn an den Lizenzserver und übergibst dessen Antwort per update() an die Sitzung. Danach sind die gespeicherten Sitzungsdaten endgültig gelöscht. So kann der Server zum Beispiel die Zahl gleichzeitiger Offline-Lizenzen begrenzen.

Bei "temporary"-Sitzungen verwirft remove() die Schlüssel sofort. Die Einträge in keyStatuses wechseln dann auf "released" oder werden entfernt. Anders als close() beendet remove() die Sitzung aber nicht. Das Objekt bleibt bestehen, bis du close() aufrufst.

Rückgabewert

Typ

Promise<void>

Beschreibung

Ein Promise, das mit undefined erfüllt wird, sobald das CDM die Löschung angenommen hat. Es wird mit InvalidStateError abgelehnt, wenn die Sitzung geschlossen ist oder noch nicht initialisiert wurde (kein generateRequest() bzw. load() vorher). Bei einem Fehler im CDM wird es mit TypeError abgelehnt.

Beispiele

Temporäre Sitzung: Schlüssel verwerfen und Sitzung schließen

// session: eine MediaKeySession, die bereits per generateRequest() initialisiert wurde
const releaseKeys = async (session) => {
  try {
    await session.remove();
    console.log('Schlüssel entfernt, Status:', [...session.keyStatuses.values()]);
  } finally {
    await session.close(); // remove() allein beendet die Sitzung nicht
  }
};

Schlüssel entfernt, Status: []

Persistente Offline-Lizenz zurückgeben (license-release)

const returnOfflineLicense = async (mediaKeys, sessionId) => {
  const session = mediaKeys.createSession('persistent-license');
  const loaded = await session.load(sessionId);
  if (!loaded) {
    console.warn('Keine gespeicherte Sitzung gefunden');
    return;
  }

  // Freigabenachweis vom CDM abfangen und an den Server senden
  session.addEventListener('message', async (event) => {
    if (event.messageType !== 'license-release') return;
    const response = await fetch('https://license.example.com/release', {
      method: 'POST',
      body: event.message
    });
    await session.update(await response.arrayBuffer());
    console.log('Lizenz beim Server freigegeben');
    await session.close();
  });

  await session.remove();
};

Lizenz beim Server freigegeben

Fehlerbehandlung bei nicht initialisierter Sitzung

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

const access = await navigator.requestMediaKeySystemAccess('org.w3.clearkey', config);
const mediaKeys = await access.createMediaKeys();
const session = mediaKeys.createSession();

try {
  await session.remove(); // noch kein generateRequest() aufgerufen
} catch (err) {
  console.log(err.name);
}

InvalidStateError

// Wichtig · Fallstricke

Sitzung bleibt offen: remove() ersetzt close() nicht. Rufe danach close() auf, sonst belegt die Sitzung weiter Ressourcen im CDM.
Nur für initialisierte Sitzungen: Ohne vorheriges generateRequest() oder load() wird das Promise mit InvalidStateError abgelehnt. Das gilt auch für bereits geschlossene Sitzungen.
Persistente Lizenzen: Die gespeicherten Daten sind erst dann endgültig gelöscht, wenn die Serverantwort auf die license-release-Nachricht per update() übergeben wurde. Hänge den message-Listener an, bevor du remove() aufrufst.
Kompatibilität: EME gibt es nur in sicheren Kontexten (HTTPS). Wie sich remove() im Detail verhält, hängt vom Schlüsselsystem ab (Widevine, PlayReady, FairPlay, Clear Key). Nicht jedes CDM unterstützt "persistent-license". Safari bietet zum Beispiel nur eingeschränkte Unterstützung für persistente Sitzungen.

Siehe auch

MediaKeySession.close() MediaKeySession.load() MediaKeySession.update() MediaKeySession.generateRequest() DOMTokenList.remove()