RTCRtpSender: getCapabilities() statische Methode

kind

Ein String, der den Medientyp angibt, für den die Sende-Fähigkeiten des Browsers abgefragt werden. Die unterstützten Medientypen sind: audio und video.

Ein neues Objekt, das angibt, welche Fähigkeiten der Browser für das Senden des angegebenen Medientyps über eine RTCPeerConnection hat. Wenn der Browser keine Unterstützung für den angegebenen Medien-kind hat, ist der zurückgegebene Wert null.

Das zurückgegebene Objekt hat die folgenden Eigenschaften:

codecs

Ein Array von Objekten, die jeweils die grundlegenden Fähigkeiten eines einzelnen Medien-Codecs beschreiben, der vom RTCRtpSender unterstützt wird.

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 weiter unten im Abschnitt Das Codecs-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 hätte ein Codec, der nur Mono-Sound unterstützt, einen Wert von 1; Stereo-Codecs hätten eine 2 usw.

clockRate

Ein positiver ganzzahliger Wert, der die Taktfrequenz des Codecs in Hertz (Hz) angibt. Die IANA verwaltet 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 anderswo verwendet werden. Siehe RFC 3555, Abschnitt 4 für das vollständige IANA-Register dieser Typen. Außerdem sehen Sie Codecs, die von WebRTC verwendet werden für Details über mögliche Codecs, die hier referenziert werden könnten.

sdpFmtpLine Optional

Ein String, der das format-spezifische Parameterfeld aus der a=fmtp-Zeile in der SDP angibt, die dem Codec entspricht, falls eine solche Zeile existiert. Wenn kein Parameterfeld vorhanden ist, wird diese Eigenschaft weggelassen.

headerExtensions

Ein Array von Objekten, die jeweils die URI einer Header-Erweiterung angeben, die für den aktuellen kind von Medien 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.

Als eine statische Funktion wird diese immer in der Form aufgerufen:

capabilities = RTCRtpSender.getCapabilities("audio");

Der zurückgegebene Satz an Fähigkeiten ist die optimistischste mögliche Liste. Es ist durchaus möglich, dass bestimmte Kombinationen von Optionen fehlschlagen, wenn Sie versuchen, sie tatsächlich zu verwenden.

Der Aufruf von RTCRtpSender.getCapabilities() bereitet den Browser in keiner Weise darauf vor, Medien zu verarbeiten. Es wird nichts geladen, abgerufen oder anderweitig vorbereitet. Es ist ein Mittel, um festzustellen, was möglicherweise verwendbar ist, bevor Sie versuchen, Medien zuzugreifen.

Da die verfügbaren Fähigkeiten dazu neigen, über einen längeren Zeitraum stabil zu sein (Menschen installieren und deinstallieren Codecs und Ähnliches nicht sehr oft), können die Medienfähigkeiten ganz oder teilweise eine Cross-Origin-Methode zur Identifizierung eines Benutzers bieten. Aus diesem Grund kann der Browser in datenschutzsensiblen Kontexten wählen, die Fähigkeiten zu verschleiern; dies könnte beispielsweise dadurch erfolgen, dass selten genutzte Codec-Konfigurationen weggelassen werden.

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

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 Basis-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 ebenfalls variieren, da es fortschrittliche Versionen des Standards gibt, aber er wird immer mit fec enden. Ein möglicher Wert ist video/ulpfec (ein generisches Fehlerverbindungmodell). 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 Ü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 dem Medium zusammenhängen, von Interesse sind.

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

<p id="log"></p>

const log = document.querySelector("#log");

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

Die folgende Funktion gibt ein true oder false zurück, das angibt, ob das Gerät das Senden von H.264-Video auf einem RTCRtpSender unterstützt.

function canSendH264() {
  let capabilities = RTCRtpSender.getCapabilities("video");

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

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 Funktionen und einen Logbereich.

<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, um die Fähigkeiten für eine bestimmte "Art" zu protokollieren. Diese wird anfangs mit dem Wert audio aufgerufen. Ein Listener aktualisiert den Wert, wenn sich die Auswahl kind ändert.

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

logMediaCapabilities("audio");

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

function logMediaCapabilities(kind) {
  const capabilities = RTCRtpSender.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