MediaKeys.createSession() — Methode · JavaScript-Referenz

Signatur

MediaKeys.prototype.createSession(sessionType)

Beschreibung

createSession() ist Teil der Encrypted Media Extensions (EME). Die Methode liefert ein neues MediaKeySession-Objekt, das einen Kontext für den Austausch von Nachrichten zwischen Ihrer Anwendung, dem Content Decryption Module (CDM) und dem Lizenzserver darstellt. Jede Sitzung verwaltet einen oder mehrere Entschlüsselungsschlüssel.

Die Methode wird synchron aufgerufen und gibt sofort eine Sitzung zurück, die aber noch leer ist. Erst mit session.generateRequest(initDataType, initData) wird eine Lizenzanfrage erzeugt; das CDM feuert daraufhin ein message-Event, dessen Inhalt Sie an den Lizenzserver senden. Die Antwort des Servers übergeben Sie per session.update(response) wieder an das CDM.

Typischer Ablauf: navigator.requestMediaKeySystemAccess() → access.createMediaKeys() → video.setMediaKeys(mediaKeys) → beim encrypted-Event des Medienelements mediaKeys.createSession() aufrufen und die Lizenzanfrage starten.

Über den Parameter sessionType legen Sie fest, ob die Lizenz nur temporär im Speicher gehalten ("temporary") oder dauerhaft gespeichert werden soll ("persistent-license"), etwa für Offline-Wiedergabe.

Parameter

Name	Typ	Default	Beschreibung
$sessionType	"temporary" \| "persistent-license"	"temporary"	Art der Sitzung. `"temporary"`: Lizenz und Schlüssel werden nicht gespeichert. `"persistent-license"`: Lizenz wird dauerhaft gespeichert und kann später per `session.load(sessionId)` wiederhergestellt werden – nur möglich, wenn die Konfiguration bei `requestMediaKeySystemAccess()` diesen Sitzungstyp in `sessionTypes` angefordert hat.

Rückgabewert

Typ

MediaKeySession

Beschreibung

Eine neue, noch nicht initialisierte MediaKeySession. Ihre sessionId ist leer, bis generateRequest() oder load() erfolgreich war.

Beispiele

Vollständiger EME-Ablauf mit Clear Key

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

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

const setupEme = async () => {
  const access = await navigator.requestMediaKeySystemAccess('org.w3.clearkey', config);
  const mediaKeys = await access.createMediaKeys();
  await video.setMediaKeys(mediaKeys);

  video.addEventListener('encrypted', async (event) => {
    // Neue temporäre Sitzung erzeugen
    const session = mediaKeys.createSession();

    session.addEventListener('message', async (msgEvent) => {
      // Lizenzanfrage an den Server schicken
      const response = await fetch('/license', {
        method: 'POST',
        body: msgEvent.message
      });
      const license = await response.arrayBuffer();
      await session.update(license);
      console.log('Lizenz geladen, Sitzung:', session.sessionId);
    });

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

setupEme().catch((err) => console.error('EME-Fehler:', err));

Lizenz geladen, Sitzung: 3F2A…

Persistente Lizenz für Offline-Wiedergabe

const createPersistentSession = async (keySystem, initData) => {
  const access = await navigator.requestMediaKeySystemAccess(keySystem, [{
    initDataTypes: ['cenc'],
    videoCapabilities: [{ contentType: 'video/mp4; codecs="avc1.42E01E"' }],
    persistentState: 'required',
    sessionTypes: ['persistent-license']
  }]);
  const mediaKeys = await access.createMediaKeys();

  const session = mediaKeys.createSession('persistent-license');
  await session.generateRequest('cenc', initData);
  // Nach update() die ID merken, um die Lizenz später wiederzuverwenden
  session.addEventListener('keystatuseschange', () => {
    localStorage.setItem('drmSessionId', session.sessionId);
  });
  return { mediaKeys, session };
};

Gespeicherte Sitzung wiederherstellen und schließen

const restoreSession = async (mediaKeys) => {
  const storedId = localStorage.getItem('drmSessionId');
  if (!storedId) return null;

  const session = mediaKeys.createSession('persistent-license');
  const loaded = await session.load(storedId);
  console.log(loaded ? 'Lizenz wiederhergestellt' : 'Keine Lizenz gefunden');
  return loaded ? session : null;
};

// Beim Verlassen der Seite Ressourcen freigeben
const cleanup = async (session) => {
  await session.close();
  console.log('Sitzung geschlossen');
};

Lizenz wiederhergestellt

// Wichtig · Fallstricke

Fehler: Wirft synchron eine NotSupportedError-DOMException, wenn sessionType vom Schlüsselsystem oder der gewählten Konfiguration nicht unterstützt wird (z. B. "persistent-license" ohne sessionTypes in der Konfiguration). Ein ungültiger String führt zu einem TypeError. Bei einem CDM-Problem kann ein InvalidStateError auftreten.
Sicherer Kontext: EME ist in modernen Browsern nur über HTTPS verfügbar.
Ressourcen: Sitzungen belegen CDM-Ressourcen. Nicht mehr benötigte Sitzungen mit session.close() schließen; persistente Lizenzen per session.remove() löschen.
Mehrfache encrypted-Events: Für denselben Inhalt kann das Event mehrmals ausgelöst werden. Prüfen Sie, ob für die initData bereits eine Sitzung existiert, um doppelte Lizenzanfragen zu vermeiden.
Kompatibilität: Von Chrome, Edge, Firefox und Safari unterstützt, die verfügbaren Schlüsselsysteme unterscheiden sich aber (Widevine, PlayReady, FairPlay, Clear Key). "persistent-license" wird nicht überall unterstützt, z. B. oft nicht in Firefox oder im privaten Modus.

Siehe auch

MediaKeys.getStatusForPolicy() MediaKeys.setServerCertificate() Document.createExpression() MediaKeyStatusMap.get() MediaKeyStatusMap.has()