Navigator.mediaCapabilities — Eigenschaft · JavaScript-Referenz

Signatur

Navigator.mediaCapabilities

Beschreibung

navigator.mediaCapabilities gibt ein MediaCapabilities-Objekt zurück. Es hat zwei Methoden: decodingInfo() für die Wiedergabe und encodingInfo() für die Aufnahme bzw. das Encodieren. Beide nehmen eine Medienkonfiguration entgegen, also Codec, Auflösung, Bitrate und Bildrate. Sie liefern ein Promise, das sich mit einem Objekt mit drei booleschen Feldern erfüllt: supported, smooth und powerEfficient.

Die API sagt also mehr als HTMLMediaElement.canPlayType() oder MediaSource.isTypeSupported(). Diese melden nur, ob ein Format grundsätzlich unterstützt wird, und das oft mit einem vagen "maybe". mediaCapabilities schätzt dagegen auch ab, ob die Wiedergabe ohne Ruckeln läuft und ob dafür Hardware-Decodierung genutzt wird, was Energie spart.

Typische Einsatzfälle sind Streaming mit adaptiver Bitrate (Wahl der Startqualität und Filtern der Varianten), die Wahl zwischen AV1, VP9 und H.264, die Wahl eines Codecs für WebRTC sowie die Wahl der Encoder-Einstellungen für MediaRecorder. Mit dem Feld keySystemConfiguration kann decodingInfo() auch die Unterstützung für verschlüsselte Medien (EME/DRM) prüfen.

Rückgabewert

Typ

MediaCapabilities

Beschreibung

Ein MediaCapabilities-Objekt mit den Methoden decodingInfo(config) und encodingInfo(config). Beide geben Promise<MediaCapabilitiesInfo> zurück, also ein Objekt der Form { supported, smooth, powerEfficient }.

Beispiele

Prüfen, ob ein 4K-VP9-Video flüssig abgespielt wird

const config = {
  type: 'media-source', // oder 'file'
  video: {
    contentType: 'video/webm; codecs="vp09.00.10.08"',
    width: 3840,
    height: 2160,
    bitrate: 12_000_000, // Bit pro Sekunde
    framerate: 30
  }
};

const checkVideo = async () => {
  if (!('mediaCapabilities' in navigator)) {
    console.log('MediaCapabilities nicht verfügbar');
    return;
  }
  const info = await navigator.mediaCapabilities.decodingInfo(config);
  console.log(`unterstützt: ${info.supported}, flüssig: ${info.smooth}, sparsam: ${info.powerEfficient}`);
};

checkVideo();

unterstützt: true, flüssig: true, sparsam: false

Beste Streaming-Variante für adaptive Wiedergabe wählen

const variants = [
  { label: 'AV1 1080p', contentType: 'video/mp4; codecs="av01.0.08M.08"', width: 1920, height: 1080, bitrate: 4_000_000 },
  { label: 'VP9 1080p', contentType: 'video/webm; codecs="vp09.00.40.08"', width: 1920, height: 1080, bitrate: 5_000_000 },
  { label: 'H.264 1080p', contentType: 'video/mp4; codecs="avc1.640028"', width: 1920, height: 1080, bitrate: 6_000_000 }
];

const pickVariant = async () => {
  const results = await Promise.all(
    variants.map(async (v) => {
      const info = await navigator.mediaCapabilities.decodingInfo({
        type: 'media-source',
        video: { contentType: v.contentType, width: v.width, height: v.height, bitrate: v.bitrate, framerate: 30 }
      });
      return { ...v, ...info };
    })
  );
  // Bevorzugt: flüssig UND energiesparend, sonst wenigstens flüssig
  const best =
    results.find((r) => r.supported && r.smooth && r.powerEfficient) ??
    results.find((r) => r.supported && r.smooth) ??
    results.find((r) => r.supported);
  console.log('Gewählt:', best?.label ?? 'keine');
};

pickVariant();

Gewählt: VP9 1080p

Encoder-Fähigkeit für eine Aufnahme mit MediaRecorder prüfen

const checkRecording = async () => {
  const info = await navigator.mediaCapabilities.encodingInfo({
    type: 'record', // 'record' für MediaRecorder, 'webrtc' für WebRTC
    video: {
      contentType: 'video/webm; codecs="vp8"',
      width: 1280,
      height: 720,
      bitrate: 2_500_000,
      framerate: 30
    },
    audio: {
      contentType: 'audio/webm; codecs="opus"',
      channels: 2,
      bitrate: 128_000,
      samplerate: 48_000
    }
  });
  console.log(info.supported ? 'Aufnahme möglich' : 'Format nicht encodierbar');
};

checkRecording().catch((err) => console.error('Ungültige Konfiguration:', err));

Aufnahme möglich

DRM-Unterstützung (EME) zusammen mit dem Codec prüfen

const checkDrm = async () => {
  const info = await navigator.mediaCapabilities.decodingInfo({
    type: 'media-source',
    video: {
      contentType: 'video/mp4; codecs="avc1.640028"',
      width: 1920, height: 1080, bitrate: 5_000_000, framerate: 25
    },
    keySystemConfiguration: {
      keySystem: 'com.widevine.alpha',
      video: { robustness: 'SW_SECURE_DECODE' }
    }
  });
  if (info.supported) {
    // keySystemAccess direkt für EME weiterverwenden
    const mediaKeys = await info.keySystemAccess.createMediaKeys();
    console.log('DRM bereit:', mediaKeys instanceof MediaKeys);
  } else {
    console.log('Widevine nicht verfügbar');
  }
};

checkDrm();

DRM bereit: true

// Wichtig · Fallstricke

Kompatibilität: Wird in allen aktuellen Browsern unterstützt (Chrome 66+, Firefox 63+, Safari 13+). encodingInfo() und keySystemConfiguration werden aber uneinheitlich unterstützt. Deshalb immer mit 'mediaCapabilities' in navigator prüfen und notfalls auf MediaSource.isTypeSupported() zurückfallen.
Nur Schätzwerte: smooth und powerEfficient sind Heuristiken des Browsers, zum Teil auf Basis früherer Wiedergaben. Eine ruckelfreie Wiedergabe ist damit nicht garantiert.
Pflichtfelder: Bei video müssen contentType, width, height, bitrate und framerate angegeben werden, bei audio mindestens contentType. Fehlt ein Feld oder ist der MIME-Typ ungültig, wird das Promise mit einem TypeError abgelehnt. Es erfüllt sich dann nicht mit supported: false.
Ist supported false, sind auch smooth und powerEfficient immer false.
Datenschutz: Die Ergebnisse können zum Fingerprinting beitragen. Manche Browser (z. B. mit Resist-Fingerprinting in Firefox) liefern deshalb absichtlich allgemeine Werte.
Verschlüsselte Medien (keySystemConfiguration) lassen sich nur in einem sicheren Kontext (HTTPS) prüfen.
Auch in Web-Workern verfügbar, dort über WorkerNavigator.mediaCapabilities.

Siehe auch

Navigator Navigator.mediaDevices Navigator.mediaSession Navigator.devicePosture Navigator.geolocation