MediaKeySystemAccess.getConfiguration() — Methode · JavaScript-Referenz

Signatur

MediaKeySystemAccess.prototype.getConfiguration()

Beschreibung

getConfiguration() gehört zur Encrypted Media Extensions (EME)-API. Nachdem navigator.requestMediaKeySystemAccess() erfolgreich aufgelöst wurde, liefert diese Methode die Konfiguration, die der Browser aus den übergebenen Kandidaten-Konfigurationen tatsächlich ausgewählt hat. Das Objekt enthält nur die Optionen, die das Schlüsselsystem (z. B. Widevine, PlayReady, FairPlay oder Clear Key) auch unterstützt.

Das zurückgegebene MediaKeySystemConfiguration-Objekt enthält unter anderem folgende Felder:

label – die optionale Bezeichnung der gewählten Konfiguration,
initDataTypes – unterstützte Initialisierungsdaten-Formate (z. B. "cenc", "webm", "keyids"),
audioCapabilities / videoCapabilities – unterstützte Kombinationen aus contentType und robustness,
distinctiveIdentifier und persistentState – jeweils "required" oder "not-allowed" (nie "optional"),
sessionTypes – unterstützte Sitzungstypen wie "temporary" oder "persistent-license".

Man verwendet die Methode, um nach der Aushandlung zu prüfen, welcher Codec, welche Robustheitsstufe oder welcher Sitzungstyp nutzbar ist – etwa um die passende Video-Rendition (z. B. HD nur bei Hardware-DRM) auszuwählen oder um zu entscheiden, ob Offline-Lizenzen möglich sind.

Rückgabewert

Typ

MediaKeySystemConfiguration

Beschreibung

Ein neues Objekt mit der vom Browser gewählten, unterstützten Teilmenge einer der an requestMediaKeySystemAccess() übergebenen Konfigurationen. Optionen mit "optional" werden auf "required" oder "not-allowed" aufgelöst.

Beispiele

Ausgewählte Konfiguration nach der Aushandlung auslesen

const configs = [{
  label: 'clearkey-mp4',
  initDataTypes: ['cenc', 'keyids'],
  videoCapabilities: [
    { contentType: 'video/mp4; codecs="avc1.42E01E"' },
    { contentType: 'video/webm; codecs="vp9"' }
  ],
  audioCapabilities: [
    { contentType: 'audio/mp4; codecs="mp4a.40.2"' }
  ],
  sessionTypes: ['temporary']
}];

const access = await navigator.requestMediaKeySystemAccess('org.w3.clearkey', configs);
const config = access.getConfiguration();

console.log(access.keySystem);
console.log(config.label);
console.log(config.videoCapabilities.map((c) => c.contentType));
console.log(config.persistentState);

org.w3.clearkey clearkey-mp4 [ 'video/mp4; codecs="avc1.42E01E"', 'video/webm; codecs="vp9"' ] not-allowed

Widevine-Robustheit prüfen und HD-Stream nur bei Hardware-DRM wählen

const findBestAccess = async () => {
  const videoType = 'video/mp4; codecs="avc1.640028"';
  const configs = [{
    initDataTypes: ['cenc'],
    videoCapabilities: [
      { contentType: videoType, robustness: 'HW_SECURE_ALL' },
      { contentType: videoType, robustness: 'SW_SECURE_DECODE' }
    ]
  }];
  try {
    return await navigator.requestMediaKeySystemAccess('com.widevine.alpha', configs);
  } catch (err) {
    console.warn('Widevine nicht verfügbar:', err.name);
    return null;
  }
};

const access = await findBestAccess();
if (access) {
  const { videoCapabilities } = access.getConfiguration();
  const hwDrm = videoCapabilities.some((c) => c.robustness === 'HW_SECURE_ALL');
  const maxHeight = hwDrm ? 2160 : 720;
  console.log(`Maximale Auflösung: ${maxHeight}p`);
}

Maximale Auflösung: 720p

Unterstützung für Offline-Lizenzen erkennen

const supportsOffline = async (keySystem) => {
  try {
    const access = await navigator.requestMediaKeySystemAccess(keySystem, [{
      initDataTypes: ['cenc'],
      videoCapabilities: [{ contentType: 'video/mp4; codecs="avc1.42E01E"' }],
      persistentState: 'required',
      sessionTypes: ['persistent-license']
    }]);
    const { sessionTypes } = access.getConfiguration();
    return sessionTypes.includes('persistent-license');
  } catch {
    return false;
  }
};

console.log(await supportsOffline('com.widevine.alpha'));

true (abhängig von Browser und Plattform)

// Wichtig · Fallstricke

Kein Auswahlmechanismus: Die Methode verändert nichts – sie meldet nur, welche eine Konfiguration der Browser aus dem übergebenen Array gewählt hat. Nicht unterstützte Einträge in videoCapabilities/audioCapabilities fehlen im Ergebnis einfach.
Jeder Aufruf liefert ein neues Objekt; Änderungen daran haben keine Wirkung auf das Schlüsselsystem.
EME funktioniert nur in einem sicheren Kontext (HTTPS). In iframes muss die Permissions-Policy encrypted-media erlaubt sein.
Fehlt robustness in den Anfragen, geben Chrome & Co. eine Konsolenwarnung aus; im Ergebnis steht dann ein leerer String.
Die verfügbaren Schlüsselsysteme unterscheiden sich stark je nach Browser: Widevine (Chrome, Firefox, Edge), PlayReady (Edge), FairPlay (com.apple.fps, Safari). Nur org.w3.clearkey ist weitgehend überall verfügbar, bietet aber keinen echten Schutz.
Die Werte hängen vom Gerät ab (Hardware-DRM, Betriebssystem, Inkognito-Modus – dort werden persistent-license oder distinctiveIdentifier häufig verweigert).

Siehe auch

MediaKeySystemAccess.createMediaKeys() GPUCanvasContext.getConfiguration() RTCPeerConnection.getConfiguration() RTCPeerConnection.setConfiguration() USBDevice.selectConfiguration()