MediaCapabilities.encodingInfo() — Methode · JavaScript-Referenz

Signatur

MediaCapabilities.prototype.encodingInfo(configuration)

Beschreibung

encodingInfo() gehört zur Media Capabilities API und wird über navigator.mediaCapabilities aufgerufen. Man übergibt eine Beschreibung der gewünschten Kodierung, also Codec, Auflösung, Bitrate, Bildrate oder Abtastrate. Zurück kommt ein Promise, das mit einem Objekt erfüllt wird. Dieses Objekt enthält die drei booleschen Werte supported, smooth und powerEfficient.

Die Methode ist das Gegenstück zu decodingInfo(). Sie hilft vor allem bei Aufnahme-Anwendungen (type: "record", z. B. mit MediaRecorder) und bei WebRTC-Übertragungen (type: "webrtc"). Damit lässt sich die beste Einstellung vorab auswählen, statt sie erst durch Ausprobieren zu ermitteln. Man kann z. B. auf einem schwachen Gerät automatisch von 1080p auf 720p herunterschalten oder einen Codec mit Hardware-Beschleunigung wählen.

Im Unterschied zu MediaRecorder.isTypeSupported() sagt encodingInfo() nicht nur, ob ein Format unterstützt wird. Die Methode schätzt auch ab, wie gut es auf dem aktuellen Gerät läuft. smooth bedeutet, dass die angegebene Bildrate voraussichtlich gehalten wird. powerEfficient deutet meist auf Hardware-Kodierung hin.

Parameter

Name	Typ	Beschreibung
$configuration Pflicht	MediaEncodingConfiguration	Objekt mit `type` (`"record"` oder `"webrtc"`) und mindestens einem der Schlüssel `video` oder `audio`.
$configuration.type Pflicht	"record" \| "webrtc"	`"record"` für lokale Aufnahmen (z. B. `MediaRecorder`), `"webrtc"` für die Übertragung per `RTCPeerConnection`.
$configuration.video	VideoConfiguration	Pflichtfelder: `contentType` (z. B. `"video/webm;codecs=vp9"` oder bei WebRTC `"video/VP9"`), `width`, `height`, `bitrate` (Bit/s) und `framerate`. Optional ist u. a. `scalabilityMode` (z. B. `"L1T3"`, nur WebRTC).
$configuration.audio	AudioConfiguration	Pflichtfeld: `contentType` (z. B. `"audio/webm;codecs=opus"`). Optional sind `channels`, `bitrate` und `samplerate`.

Rückgabewert

Typ

Promise<MediaCapabilitiesInfo>

Beschreibung

Promise, das mit einem Objekt erfüllt wird: { supported, smooth, powerEfficient }, jeweils boolean. Manche Browser liefern zusätzlich die geprüfte configuration mit. Ist supported gleich false, sind auch die beiden anderen Werte false. Bei einer ungültigen Konfiguration wird das Promise mit einem TypeError abgelehnt.

Beispiele

Einfache Prüfung einer Videoaufnahme-Konfiguration

const config = {
  type: 'record',
  video: {
    contentType: 'video/webm;codecs=vp8',
    width: 1280,
    height: 720,
    bitrate: 2_500_000, // 2,5 Mbit/s
    framerate: 30
  }
};

const info = await navigator.mediaCapabilities.encodingInfo(config);
console.log(`unterstützt: ${info.supported}, flüssig: ${info.smooth}, stromsparend: ${info.powerEfficient}`);

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

Beste Aufnahme-Auflösung für MediaRecorder automatisch wählen

const kandidaten = [
  { width: 1920, height: 1080, bitrate: 5_000_000 },
  { width: 1280, height: 720, bitrate: 2_500_000 },
  { width: 640, height: 360, bitrate: 800_000 }
];

const waehleProfil = async (codec = 'video/webm;codecs=vp9') => {
  for (const k of kandidaten) {
    const { supported, smooth } = await navigator.mediaCapabilities.encodingInfo({
      type: 'record',
      video: { contentType: codec, framerate: 30, ...k },
      audio: { contentType: 'audio/webm;codecs=opus', channels: 2, bitrate: 128_000, samplerate: 48_000 }
    });
    if (supported && smooth) return k;
  }
  return kandidaten.at(-1); // Rückfall auf niedrigste Stufe
};

const profil = await waehleProfil();
console.log('Verwende', `${profil.width}x${profil.height}`);

Verwende 1280x720

WebRTC: hardwarebeschleunigten Codec bevorzugen

const codecs = ['video/AV1', 'video/VP9', 'video/H264', 'video/VP8'];

const pruefe = (contentType) => navigator.mediaCapabilities.encodingInfo({
  type: 'webrtc',
  video: { contentType, width: 1280, height: 720, bitrate: 1_500_000, framerate: 30, scalabilityMode: 'L1T3' }
}).then((info) => ({ contentType, ...info }))
  .catch(() => ({ contentType, supported: false, smooth: false, powerEfficient: false }));

const ergebnisse = await Promise.all(codecs.map(pruefe));
const bester = ergebnisse.find((r) => r.supported && r.powerEfficient)
  ?? ergebnisse.find((r) => r.supported);

console.log('Gewählter Codec:', bester?.contentType ?? 'keiner');

Gewählter Codec: video/H264

// Wichtig · Fallstricke

Funktion vorab prüfen: if ('mediaCapabilities' in navigator && 'encodingInfo' in navigator.mediaCapabilities). encodingInfo() wurde später und weniger einheitlich umgesetzt als decodingInfo(), vor allem der Typ \"webrtc\" in älteren Firefox- und Safari-Versionen. Die Methode steht auch in Web Workern zur Verfügung.
Werte umbenannt: Ältere Fassungen der Spezifikation nannten den WebRTC-Typ \"transmission\". Heute heißt er \"webrtc\".
Format von contentType: Bei \"record\" einen vollständigen MIME-Typ mit codecs angeben (video/webm;codecs=vp9). Bei \"webrtc\" reicht die Form video/VP9 bzw. audio/opus. Ist der MIME-Typ ungültig oder fehlen sowohl video als auch audio, wird das Promise mit einem TypeError abgelehnt. Deshalb immer try/catch bzw. .catch() verwenden.
Nur eine Schätzung: smooth und powerEfficient sind Prognosen des Browsers und keine Garantie. Die tatsächliche Leistung hängt auch von der Systemlast, dem Akkuzustand und der Temperatur ab.
Datenschutz: Die Ergebnisse können zum Fingerprinting beitragen. Manche Browser liefern deshalb absichtlich grobe oder vereinheitlichte Antworten.

Siehe auch

MediaCapabilities.decodingInfo() MediaList.appendMedium() MediaList.toString() TextEncoder.encodeInto() Fence.getNestedConfigs() new XRVisibilityMaskChangeEvent()