RTCRtpReceiver: getCapabilities() static method

kind

A string indicating the type of media for which the browser's receiver capabilities are requested. The supported media kinds are: audio and video.

A new object that indicates what capabilities the browser has for receiving the specified media kind over an 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:

codecs

An array of objects, each describing the basic capabilities of a single media codec supported by the RTCRtpReceiver.

Note: The array contains special entries that represent the underlying components of the transport — these may be ignored if you're only interested in the actual codecs used for the media itself. These are described below in the section The codecs array.

Each codec object has the following properties:

channels Optional

A positive integer value indicating the maximum number of channels supported by the codec; for example, a codec that supports only mono sound would have a value of 1; stereo codecs would have a 2, etc.

clockRate

A positive integer specifying the codec's clock rate in Hertz (Hz). The IANA maintains a list of codecs and their parameters, including their clock rates.

mimeType

A string indicating the codec's MIME media type and subtype. The MIME type strings used by RTP differ from those used elsewhere. See RFC 3555, section 4 for the complete IANA registry of these types. Also see Codecs used by WebRTC for details about potential codecs that might be referenced here.

sdpFmtpLine Optional

A string giving the format specific parameters field from the a=fmtp line in the SDP which corresponds to the codec, if such a line exists. If there is no parameters field, this property is left out.

headerExtensions

An array of objects, each providing the URI of a header extension supported for the current kind of media. Each object has the following property:

uri

A string, specifying the URI of a header extension. The URI is formatted as described in RFC 5285.

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

capabilities = RTCRtpReceiver.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 RTCRtpReceiver.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 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:

RED (REDundant Audio Data)

The media type of an RED entry may vary due to there being several versions of it, but it will end with red, such as video/red or video/fwdred. The base RED standard can be found in RFC 2198. There may be multiple entries for RED if different forms are supported; each will have a unique media type in that case.

FEC (Forward Error Correction)

An FEC component handles error correction data; its media type may also vary due to there being advanced versions of the standard available, but it will always end with fec. One possible value is video/ulpfec (a generic error connection model). There may also be multiple FEC entries if more than one form is supported.

RTX (Retransmission)

This component is responsible for retransmission of data; it's media type should be video/rtx. There will only be one entry for RTX, and it will not have an sdpFmtpLine property.

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

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

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

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

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

The function below returns a Boolean indicating whether or not the device supports receiving H.264 video on a WebRTC connection.

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

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

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

Result