new MediaEncryptedEvent() — Methode · JavaScript-Referenz

Signatur

new MediaEncryptedEvent(type, options)

Beschreibung

Der Konstruktor MediaEncryptedEvent() erzeugt ein Ereignisobjekt vom Typ MediaEncryptedEvent. Solche Ereignisse löst der Browser normalerweise selbst als encrypted-Ereignis an einem HTMLMediaElement aus, wenn er beim Abspielen auf verschlüsselte Mediendaten stößt, z. B. auf eine pssh-Box in einem MP4-Container.

Das Ereignis enthält zwei zentrale Eigenschaften: initDataType (Format der Initialisierungsdaten, etwa "cenc", "keyids" oder "webm") und initData (die eigentlichen Daten als ArrayBuffer). Mit diesen Daten erzeugt eine Anwendung über MediaKeySession.generateRequest() eine Lizenzanfrage an den Lizenzserver.

Selbst aufrufen muss man den Konstruktor selten. Nützlich ist er vor allem für Unit-Tests von DRM-Logik, zum Simulieren von encrypted-Ereignissen oder wenn eine Anwendung Initialisierungsdaten auf anderem Weg bekommt (z. B. aus einem Manifest) und sie über denselben Ereignispfad weiterreichen will.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Name des Ereignisses, in der Praxis immer `"encrypted"`.
$options	object	{}	Optionales Wörterbuch. Neben den `Event`-Optionen (`bubbles`, `cancelable`, `composed`) gibt es: `initDataType` (`string`, Standard `""`): Format der Initialisierungsdaten, z. B. `"cenc"`, `"keyids"`, `"webm"`. `initData` (`ArrayBuffer \| null`, Standard `null`): die Initialisierungsdaten.

Rückgabewert

Typ

MediaEncryptedEvent

Beschreibung

Ein neues MediaEncryptedEvent-Objekt mit den angegebenen Eigenschaften initDataType und initData.

Beispiele

Ereignis erzeugen und Eigenschaften auslesen

// Initialisierungsdaten im "keyids"-Format (JSON, UTF-8-kodiert)
const json = JSON.stringify({ kids: ['LwVHf8JLtPrv2GUXFW2v_A'] });
const initData = new TextEncoder().encode(json).buffer;

const event = new MediaEncryptedEvent('encrypted', {
  initDataType: 'keyids',
  initData
});

console.log(event.type);
console.log(event.initDataType);
console.log(event.initData.byteLength);

encrypted keyids 39

encrypted-Ereignis simulieren (z. B. im Test)

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

video.addEventListener('encrypted', (e) => {
  console.log(`Encrypted-Ereignis: ${e.initDataType}, ${e.initData?.byteLength ?? 0} Bytes`);
});

const fakeInitData = new Uint8Array([0x00, 0x00, 0x00, 0x34]).buffer;
video.dispatchEvent(new MediaEncryptedEvent('encrypted', {
  initDataType: 'cenc',
  initData: fakeInitData
}));

Encrypted-Ereignis: cenc, 4 Bytes

Echter Handler: Lizenzanfrage erzeugen

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

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

video.addEventListener('encrypted', async (event) => {
  const session = video.mediaKeys.createSession();
  session.addEventListener('message', (msg) => {
    // msg.message an den Lizenzserver schicken, Antwort mit session.update() übergeben
    console.log('Lizenzanfrage bereit:', msg.messageType);
  });
  await session.generateRequest(event.initDataType, event.initData);
});

setupKeys();

Lizenzanfrage bereit: license-request

// Wichtig · Fallstricke

Sicherer Kontext: Encrypted Media Extensions stehen nur über HTTPS (bzw. localhost) zur Verfügung; in unsicheren Kontexten ist MediaEncryptedEvent ggf. nicht definiert.
Selbst erzeugte Ereignisse haben isTrusted === false. Sie lösen keine echte Schlüsselverarbeitung im Browser aus, sondern rufen nur registrierte Listener auf.
initData muss ein ArrayBuffer sein. Ein Uint8Array direkt zu übergeben, führt je nach Browser zu einem TypeError. Deshalb .buffer verwenden.
Ein encrypted-Ereignis kann bei einem Medium mehrfach auftreten (z. B. einmal pro Spur oder pssh-Box). Doppelte Initialisierungsdaten sollte man erkennen und nicht mehrere Sitzungen dafür öffnen.
Welche Werte für initDataType unterstützt werden, hängt vom Schlüsselsystem ab (Clear Key, Widevine, PlayReady, FairPlay). Safari hat historisch zusätzlich das ältere webkitneedkey-Modell verwendet.
Browser-Kompatibilität: aktuelle Versionen von Chrome, Edge, Firefox und Safari unterstützen den Konstruktor. Vor der Nutzung mit 'MediaEncryptedEvent' in window prüfen.

Siehe auch

new DocumentPictureInPictureEvent() new MediaQueryListEvent() new MediaStreamEvent() new MIDIMessageEvent() new MediaKeyMessageEvent()