RTCRtpReceiver: getCapabilities() statische Methode

Die statische Methode RTCRtpReceiver.getCapabilities() gibt ein Objekt zurück, das die von RTCRtpReceiver-Objekten auf dem aktuellen Gerät unterstützten Codec- und Header-Erweiterungskapazitäten beschreibt.

Sie können auf ähnliche Weise die Fähigkeiten von RTCRtpSender-Objekten durch Aufrufen der statischen Funktion RTCRtpSender.getCapabilities() abrufen.

Syntax

js
RTCRtpReceiver.getCapabilities(kind)

Parameter

kind

Ein String, der den Medientyp angibt, für den die Empfangskapazitäten des Browsers angefordert werden. Die unterstützten Medientypen sind: audio und video.

Rückgabewert

Ein neues Objekt, das anzeigt, welche Fähigkeiten der Browser hat, um die angegebene Medienart über eine RTCPeerConnection zu empfangen. Wenn der Browser keinen Support für den angegebenen Medientyp kind hat, ist der zurückgegebene Wert null.

Das zurückgegebene Objekt hat die folgenden Eigenschaften:

codecs

Ein Array von Objekten, von denen jedes die grundlegenden Fähigkeiten eines einzelnen Media Codecs beschreibt, die vom RTCRtpReceiver unterstützt werden.

Hinweis: Das Array enthält spezielle Einträge, die die zugrunde liegenden Komponenten des Transports darstellen – diese können ignoriert werden, wenn Sie sich nur für die tatsächlich für das Medium verwendeten Codecs interessieren. Diese werden unten im Abschnitt Das Codec-Array beschrieben.

Jedes Codec-Objekt hat die folgenden Eigenschaften:

channels Optional

Ein positiver ganzzahliger Wert, der die maximale Anzahl der vom Codec unterstützten Kanäle angibt; zum Beispiel würde ein Codec, der nur Mono-Sound unterstützt, einen Wert von 1 haben; Stereo-Codecs hätten einen Wert von 2 usw.

clockRate

Ein positiver ganzzahliger Wert, der die Taktfrequenz des Codecs in Hertz (Hz) angibt. Die IANA pflegt eine Liste von Codecs und deren Parameter, einschließlich ihrer Taktfrequenzen.

mimeType

Ein String, der den MIME-Medientyp und -subtyp des Codecs angibt. Die MIME-Typ-Strings, die von RTP verwendet werden, unterscheiden sich von denen, die anderweitig verwendet werden. Siehe RFC 3555, Abschnitt 4 für das vollständige IANA-Register dieser Typen. Siehe auch Codecs, die von WebRTC verwendet werden für Details zu potenziellen Codecs, die hier referenziert werden könnten.

sdpFmtpLine Optional

Ein String, der das format-spezifische Parameterfeld aus der a=fmtp-Zeile im SDP angibt, die dem Codec entspricht, sofern eine solche Zeile existiert. Wenn es kein Parameterfeld gibt, wird diese Eigenschaft weggelassen.

headerExtensions

Ein Array von Objekten, von denen jedes die URI einer Header-Erweiterung angibt, die für den aktuellen Medientyp kind unterstützt wird. Jedes Objekt hat die folgende Eigenschaft:

uri

Ein String, der die URI einer Header-Erweiterung angibt. Die URI ist formatiert, wie in RFC 5285 beschrieben.

Beschreibung

Als statische Funktion wird dies immer in folgender Form aufgerufen:

js
capabilities = RTCRtpReceiver.getCapabilities("audio");

Das zurückgegebene Set von Fähigkeiten ist die optimistischste mögliche Liste. Es ist durchaus möglich, dass bestimmte Kombinationen von Optionen nicht funktionieren, wenn Sie versuchen, sie tatsächlich zu verwenden.

Das Aufrufen von RTCRtpReceiver.getCapabilities() bereitet den Browser in keiner Weise darauf vor, Medien zu verarbeiten. Nichts wird geladen, abgerufen oder anderweitig vorbereitet. Es ist ein Mittel, um festzustellen, was möglicherweise nutzbar ist, bevor Sie versuchen, auf Medien zuzugreifen.

Da der verfügbare Fähigkeitensatz dazu neigt, längere Zeit stabil zu bleiben (die Menschen installieren und deinstallieren Codecs und dergleichen nicht sehr oft), können die Medienfähigkeiten ganz oder teilweise eine plattformübergreifende Methode zur Identifizierung eines Nutzers bieten. Aus diesem Grund kann der Browser in datenschutzsensiblen Kontexten wählen, die Fähigkeiten zu verschleiern; dies könnte zum Beispiel dadurch erfolgen, dass selten verwendete Codec-Konfigurationen weggelassen werden.

Das Codec-Array

Das codecs-Array ist ein Array von Objekten, das einen einzelnen Codec und seine grundlegenden Fähigkeiten beschreibt. Der Browser wird nur unterschiedliche Fähigkeitenskombinationen separat melden. Wenn zwei Fähigkeitenmengen als eine beschrieben werden können, werden sie es. Das bedeutet zum Beispiel, wenn es zwei Einträge für den H.264-Codec gibt (wie durch das mimeType als "video/H264" identifiziert), dass es andere Werte in den Fähigkeitenobjekten gibt, die anzeigen, wie sie in irgendeiner Weise unterschiedlich sind.

Es gibt drei spezielle Einträge, die immer vorhanden sein sollten und die zugrunde liegenden Komponenten des Transports darstellen. Diese Komponenten sind:

RED (REDundant Audio Data)

Der Medientyp eines RED-Eintrags kann variieren, da es mehrere Versionen davon gibt, aber er wird mit red enden, wie video/red oder video/fwdred. Der RED-Standard kann in RFC 2198 gefunden werden. Es kann mehrere Einträge für RED geben, wenn verschiedene Formen unterstützt werden; jeder wird in diesem Fall einen eindeutigen Medientyp haben.

FEC (Forward Error Correction)

Eine FEC-Komponente behandelt Fehlerkorrekturdaten; ihr Medientyp kann auch variieren, da fortgeschrittene Versionen des Standards vorhanden sein können, aber sie wird immer mit fec enden. Ein möglicher Wert ist video/ulpfec (ein generisches Fehlerkorrekturmodell). Es kann auch mehrere FEC-Einträge geben, wenn mehr als eine Form unterstützt wird.

RTX (Retransmission)

Diese Komponente ist verantwortlich für die erneute Übertragung von Daten; ihr Medientyp sollte video/rtx sein. Es wird nur einen Eintrag für RTX geben, und er wird keine sdpFmtpLine-Eigenschaft haben.

Diese Einträge sollten ignoriert werden, wenn nur Codecs, die mit den Medien zusammenhängen, von Interesse sind.

Beispiele

Funktionsunterstützung

Sie können Object.hasOwn() verwenden, um zu prüfen, ob RTCRtpReceiver.getCapabilities() unterstützt wird:

js
log.textContent = `RTCRtpReceiver.getCapabilities() supported: ${Object.hasOwn(
  RTCRtpReceiver,
  "getCapabilities",
)}`;

Unterstützung für einen bestimmten Codec prüfen

Die folgende Funktion gibt einen Boolean zurück, der angibt, ob das Gerät in der Lage ist, H.264-Video über eine WebRTC-Verbindung zu empfangen.

Hinweis: Da RTCRtpReceiver.getCapabilities() tatsächlich nur wahrscheinliche Unterstützung angibt, könnte der Versuch, H.264-Video zu empfangen, auch nach einer positiven Antwort dieser Funktion noch fehlschlagen.

js
function canReceiveH264() {
  let capabilities = RTCRtpReceiver.getCapabilities("video");

  capabilities.codecs.forEach((codec) => {
    if (codec.mimeType === "video/H264") {
      return true;
    }
  });
  return false;
}

Alle Fähigkeiten abrufen

Dieses Codebeispiel zeigt, wie wir alle unterstützten Codecs und Header abrufen könnten. Das HTML definiert eine Auswahlliste für die beiden Arten von Fähigkeiten und einen Logbereich.

html
<select id="kind">
  <option value="audio">audio</option>
  <option value="video">video</option>
</select>
<textarea rows="40" cols="100" id="log"></textarea>

Das JavaScript definiert eine Funktion, die die Fähigkeiten für eine bestimmte „Art“ protokolliert. Dies wird zunächst mit dem Wert audio aufgerufen. Ein Listener aktualisiert den Wert, wenn sich die Auswahlliste kind ändert.

js
const log = document.querySelector("#log");
const kindSelector = document.querySelector("#kind");

logMediaCapabilities("audio");

kindSelector.addEventListener("click", () => {
  log.textContent = "";
  logMediaCapabilities(kindSelector.value);
});

function logMediaCapabilities(kind) {
  if (!Object.hasOwn(RTCRtpReceiver, "getCapabilities")) {
    log.textContent = "RTCRtpReceiver.getCapabilities() not supported";
    return;
  }
  const capabilities = RTCRtpReceiver.getCapabilities(`${kind}`);
  log.textContent += "Headers\n";
  capabilities.headerExtensions.forEach((header) => {
    log.textContent += ` uri: ${header.uri}\n`;
  });

  log.textContent += "\nCodecs\n";
  capabilities.codecs.forEach((codec) => {
    log.textContent += ` mime type: ${codec.mimeType}\n`;
    log.textContent += `   channels: ${codec.channels}\n`; //max channels - e.g. 2 is stereo
    log.textContent += `   clockRate: ${codec.clockRate}\n`; // clock rate in Hz
    log.textContent += `   sdpFmtpLine: ${codec.sdpFmtpLine}\n`; // mime media type and subtype
  });
}

Ergebnis

Spezifikationen

Specification
WebRTC: Real-Time Communication in Browsers
# dom-rtcrtpreceiver-getcapabilities

Browser-Kompatibilität

Report problems with this compatibility data on GitHub
desktopmobile
Chrome
Edge
Firefox
Opera
Safari
Chrome Android
Firefox for Android
Opera Android
Safari on iOS
Samsung Internet
WebView Android
WebView on iOS
getCapabilities() static method

Legend

Tip: you can click/tap on a cell for more information.

Full support
Full support