docs.rodeo

MDN Web Docs mirror

RTCRtpSender: getCapabilities() static method

{{APIRef("WebRTC")}} 

The static method RTCRtpSender.getCapabilities() returns an object describing the codec and header extension capabilities supported by the {{domxref("RTCRtpSender")}} .

You can, similarly, obtain the capabilities of {{domxref("RTCRtpReceiver")}}  objects on the device by calling the static function {{domxref("RTCRtpReceiver.getCapabilities_static", "RTCRtpReceiver.getCapabilities()")}} .

Syntax

RTCRtpSender.getCapabilities(kind)

Parameters

Return value

A new object that indicates what capabilities the browser has for sending the specified media kind over an {{domxref("RTCPeerConnection")}} . If the browser doesn’t have any support for the given media kind, the returned value is null.

The returned object has the following properties:

Description

As a static function, this is always called using the form:

capabilities = RTCRtpSender.getCapabilities("audio");

The returned set of capabilities is the most optimistic possible list. It is entirely possible that certain combinations of options may fail to work when you actually try to use them.

Calling RTCRtpSender.getCapabilities() doesn’t prime the browser in any way to handle media. Nothing is loaded, fetched, or otherwise prepared. It’s a means of determining what might be usable before starting to try to access media.

Because the set of capabilities available tend to be stable for a length of time (people don’t install and uninstall codecs and the like very often), the media capabilities can in whole or in part provide a cross-origin method for identifying a user. For that reason, in privacy-sensitive contexts, the browser may choose to obscure the capabilities; this might be done, for example, by leaving out rarely-used codec configurations.

The codecs array

The codecs array is an array of objects that describes a single codec and its basic capabilities. The browser will only report distinct capability combinations separately. If two sets of capabilities can be described as one, they will be. That means that, for instance, if there are two entries for the H.264 codec (as identified by the mimeType being “video/H264”), there are other values in the capabilities objects indicating how they’re different in some way.

There are three special entries that should always be present, representing underlying components of the transport. Those components are:

These entries should be ignored if only codecs related to the media are of interest.

Examples

Feature support

You can use Object.hasOwn() to check that RTCRtpSender.getCapabilities() is supported:

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

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

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

{{ EmbedLiveSample('Feature support', '100%', '30px') }} 

Checking support for a particular codec

The function below returns a true or false indicating whether or not the device supports sending H.264 video on an {{domxref("RTCRtpSender")}} .

[!NOTE] Since RTCRtpSender.getCapabilities() actually only indicates probable support. So below H.264 support might still fail even after getting a positive response from this function.

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

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

Getting all capabilities

This code example shows how we might get all supported codecs and headers. The HTML defines a selection list for the two kinds of capabilities, and a log area.

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

The JavaScript defines a function to log the capabilities for a particular “kind”. This is called initially with the value audio. A listener updates the value when the selection list kind is changed.

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
  });
}

Result

{{ EmbedLiveSample('Getting all capabilities', '100%', '500px') }} 

Specifications

{{Specifications}} 

Browser compatibility

{{Compat}} 

In this article

View on MDN