MediaCapabilities — Schnittstelle · JavaScript-Referenz

Signatur

interface MediaCapabilities

Beschreibung

Die Schnittstelle MediaCapabilities gehört zur Media Capabilities API. Man greift über navigator.mediaCapabilities darauf zu, im Hauptthread und in Workern. Sie beantwortet nicht nur die Frage „Kann der Browser dieses Format abspielen?“, sondern sagt auch, ob die Wiedergabe flüssig (smooth) und energieeffizient (powerEfficient) läuft, etwa durch Hardware-Decodierung.

Die Schnittstelle hat zwei Methoden:

decodingInfo(configuration) prüft Decodierungsfähigkeiten für die Typen "file", "media-source" und "webrtc", bei Bedarf auch mit Schlüsselsystemen (EME/DRM).
encodingInfo(configuration) prüft Encodierungsfähigkeiten für die Typen "record" (MediaRecorder) und "webrtc".

Beide Methoden geben ein Promise zurück. Es erfüllt sich mit einem Objekt der Form { supported, smooth, powerEfficient }. Typische Anwendungen sind adaptive Streaming-Player, die aus mehreren Codecs und Auflösungen die beste Variante wählen: zum Beispiel AV1 nur mit Hardware-Beschleunigung, sonst VP9 oder H.264. Das ist deutlich aussagekräftiger als HTMLMediaElement.canPlayType() oder MediaSource.isTypeSupported().

Parameter

Name	Typ	Beschreibung
$configuration.type Pflicht	"file" \| "media-source" \| "webrtc" \| "record"	Art der Medienquelle. Für `decodingInfo()` gelten `file`, `media-source` und `webrtc`, für `encodingInfo()` gelten `record` und `webrtc`.
$configuration.video	VideoConfiguration	Objekt mit `contentType` (MIME-Typ inkl. `codecs`), `width`, `height`, `bitrate` und `framerate`. Optional sind `hdrMetadataType`, `colorGamut`, `transferFunction` und `scalabilityMode`.
$configuration.audio	AudioConfiguration	Objekt mit `contentType`. Optional sind `channels`, `bitrate` und `samplerate`. Es muss mindestens `video` oder `audio` angegeben werden.
$configuration.keySystemConfiguration	MediaCapabilitiesKeySystemConfiguration	Nur bei `decodingInfo()`: DRM-Konfiguration (z. B. `keySystem: "com.widevine.alpha"`) für die Abfrage verschlüsselter Inhalte.

Rückgabewert

Typ

Promise<MediaCapabilitiesInfo>

Beschreibung

Die Methoden decodingInfo() und encodingInfo() erfüllen sich mit { supported: boolean, smooth: boolean, powerEfficient: boolean }. Bei DRM-Abfragen kommt zusätzlich keySystemAccess hinzu. Ist die Konfiguration ungültig, wird das Promise mit einem TypeError abgelehnt.

Beispiele

Zugriff und einfache Decodierungsabfrage

const config = {
  type: 'file',
  video: {
    contentType: 'video/webm; codecs="vp09.00.10.08"',
    width: 1920,
    height: 1080,
    bitrate: 4_000_000,
    framerate: 30
  }
};

if ('mediaCapabilities' in navigator) {
  const info = await navigator.mediaCapabilities.decodingInfo(config);
  console.log(`unterstützt: ${info.supported}, flüssig: ${info.smooth}, effizient: ${info.powerEfficient}`);
}

unterstützt: true, flüssig: true, effizient: true

Besten Codec für einen Streaming-Player wählen

const kandidaten = [
  { name: 'AV1', contentType: 'video/mp4; codecs="av01.0.08M.08"' },
  { name: 'VP9', contentType: 'video/webm; codecs="vp09.00.10.08"' },
  { name: 'H.264', contentType: 'video/mp4; codecs="avc1.640028"' }
];

const waehleCodec = async () => {
  const ergebnisse = await Promise.all(kandidaten.map(async (k) => {
    const info = await navigator.mediaCapabilities.decodingInfo({
      type: 'media-source',
      video: { contentType: k.contentType, width: 1920, height: 1080, bitrate: 5_000_000, framerate: 30 }
    });
    return { ...k, ...info };
  }));
  // Bevorzugt: flüssig UND energieeffizient, sonst nur unterstützt
  return ergebnisse.find((r) => r.supported && r.smooth && r.powerEfficient)
      ?? ergebnisse.find((r) => r.supported);
};

const codec = await waehleCodec();
console.log('Gewählter Codec:', codec?.name ?? 'keiner');

Gewählter Codec: VP9

Encodierung für MediaRecorder prüfen

const info = await navigator.mediaCapabilities.encodingInfo({
  type: 'record',
  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 unterstützt');

Aufnahme möglich

// Wichtig · Fallstricke

Browser-Kompatibilität: decodingInfo() funktioniert in allen modernen Browsern. encodingInfo() und die Typen "webrtc" und "record" werden uneinheitlich unterstützt, vor allem in Safari und Firefox. Deshalb vorher mit 'mediaCapabilities' in navigator prüfen und eine Alternative über canPlayType() oder MediaSource.isTypeSupported() vorsehen.
Codec-Strings genau angeben: Ein contentType ohne codecs-Parameter (z. B. nur video/mp4) führt je nach Browser zu einem TypeError oder zu wenig aussagekräftigen Ergebnissen.
Pflichtfelder: Bei video sind width, height, bitrate und framerate Pflicht. Fehlen sie, wird das Promise abgelehnt.
Heuristik statt Garantie: smooth und powerEfficient sind Schätzungen des Browsers, die teils auf früheren Wiedergaben beruhen. Die tatsächliche Leistung kann wegen Systemlast oder Akkustand abweichen.
Datenschutz: Die API kann zum Fingerprinting beitragen. Manche Browser liefern deshalb vereinfachte oder verallgemeinerte Werte.
Sicherer Kontext: DRM-Abfragen über keySystemConfiguration erfordern HTTPS.

Siehe auch

VRDisplayCapabilities InputDeviceCapabilities MediaDevices MediaList MediaMetadata