ThesetCodecPreferences() method of theRTCRtpTransceiver interface is used to set the codecs that the transceiver allows for decodingreceived data, in order of decreasing preference.

The preferences set using this method influence what codecs are negotiated with the remote peer for encoding the data that it sends, including those used for retransmission, redundancy, and forward error correction.Codecs that are not included in the preferences list will not be part of the negotiation.Note that the preferences used by this transceiver forsending content depend on the preferences of the remote peer.

The recommended way to set codec preferences is to first get the array of codecs that are actually supported for decoding received data, then reorder them your in decreasing preference order.This ensures that the array is ordered as required, does not contain any unsupported codecs, and also that it also contains codecs that are needed for retransmission, redundancy, and forward error correction.

The specified set of codecs will be used for all future connections that include this transceiver until this method is called again.

When preparing to open anRTCPeerConnection the codecs should be set usingsetCodecPreferences()before calling eitherRTCPeerConnection.createOffer() orcreateAnswer(), as these initiate the negotiation (and will use codec parameters from theuser agent's default configuration by default).

The codecs can be changed when you have an ongoing communication, but you need to first callsetCodecPreferences() and then kick off a new negotiation.A WebRTC application will already have code for this in thenegotiationneeded event handler.Note however that at time of writing the event is not automatically fired when you callsetCodecPreferences(), so you will have to callonnegotiationneeded yourself.

A guide to codecs supported by WebRTC—and each codec's positive and negative characteristics—can be found inCodecs used by WebRTC.

Syntax

setCodecPreferences(codecs)

Parameters

codecs

An array of objects, each providing the parameters for one of the transceiver's supportedmedia codecs, ordered by preference.Ifcodecs is empty, the codec configurations are all returned to the user agent's defaults.

Note:Any codecs not included incodecs will not be considered during the process of negotiating a connection.This lets you prevent the use of codecs you don't wish to use.

Each codec object in the array has the following properties:

channelsOptional

A positive integer indicating the number of channels supported by the codec.For example, for audio codecs a value of 1 specifies monaural sound, while 2 indicates stereo.

clockRate

A positive integer specifying the codec's clock rate in Hertz (Hz).The clock rate is the rate at which the codec's RTP timestamp advances.Most codecs have specific values or ranges of values they permit.The IANA maintains alist of codecs and their parameters, including their clock rates.

mimeType

A string indicating the codec's MIME media type and subtype, specified as a string of the form"type/subtype".The MIME type strings used by RTP differ from those used elsewhere.IANA maintains aregistry of valid MIME types.Also seeCodecs used by WebRTC for details about potential codecs that might be referenced here.

sdpFmtpLineOptional

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

Return value

None (undefined).

Exceptions

InvalidAccessErrorDOMException

Thecodecs list includes one or more codecs which are not supported by theRTCRtpReceiver associated with the transceiver.

InvalidModificationErrorDOMException

Thecodecs list only contains entries for RTX, RED, FEC or Comfort Noise, or is an empty set.The codecs must always contain a codec for the media.

Examples

Creating the array of preferred codecs

The recommended way to set codec preferences is to first get the array of codecs that are actually supported for decoding received data, then reorder the list in decreasing preference order.

It is important to start with the list of codecs that are supported (and not a hard coded list of your preferred codecs), because you if you include any that aren't supported by the associatedRTCRtpReceiver the browser will throw anInvalidAccessError exception when you call thesetCodecPreferences() method.In addition, the array has to include appropriate codecs for retransmission, redundancy, and forward error correction, and starting with the list of supported codecs ensures that these are present.

You can get the codecs supported for decoding data using theRTCRtpReceiver.getCapabilities() static method as shown:

const availReceiveCodecs = transceiver.receiver.getCapabilities("video").codecs;

To reorder the codecs array to our preferred order, we can use the sorting function below to sort on MIME type (this comes fromsetCodecPreferences is now in all browsers! on blog.mozilla.org (2024)).

function sortByMimeTypes(codecs, preferredOrder) {  return codecs.sort((a, b) => {    const indexA = preferredOrder.indexOf(a.mimeType);    const indexB = preferredOrder.indexOf(b.mimeType);    const orderA = indexA >= 0 ? indexA : Number.MAX_VALUE;    const orderB = indexB >= 0 ? indexB : Number.MAX_VALUE;    return orderA - orderB;  });}

The method takes the list of supported codecs, and an array containing the preferred MIME types, in decreasing order, and returns the array sorted in place.The code below shows how this is used, assuming that you have already set up a peer connection (peerConnection):

// Get supported codecs the sort using preferred codecsconst supportedCodecs = RTCRtpReceiver.getCapabilities("video").codecs;const preferredCodecs = ["video/H264", "video/VP8", "video/VP9"];const sortedCodecs = sortByMimeTypes(supportedCodecs, preferredCodecs);// Get transceiver for connection and set the preferencesconst [transceiver] = peerConnection.getTransceivers();transceiver.setCodecPreferences(sortedCodecs); // <---

Specifications

Browser compatibility

See also

• setCodecPreferences is now in all browsers! on blog.mozilla.org (2024)
• WebRTC API
• Codecs used by WebRTC
• Introduction to the Real-time Transport Protocol (RTP)
• Web media technologies