RTCCodecStats - add docs

files/en-us/web/api/rtccodecstats/channels/index.md

@@ -0,0 +1,29 @@
+---
+title: "RTCCodecStats: channels property"
+short-title: channels
+slug: Web/API/RTCCodecStats/channels
+page-type: web-api-instance-property
+browser-compat: api.RTCStatsReport.type_codec.channels
+---
+
+{{APIRef("WebRTC")}}
+
+The **`channels`** property of the {{domxref("RTCCodecStats")}} dictionary is a positive number containing the number of channels supported by the codec.
+
+For audio codecs, a value of 1 specifies monaural sound while 2 indicates stereo.
+
+## Values
+
+A positive number indicating the number of channels.
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- [`RTCRtpCodecParameters.channels`](/en-US/docs/Web/API/RTCRtpCodecParameters#channels)

files/en-us/web/api/rtccodecstats/clockrate/index.md

@@ -0,0 +1,27 @@
+---
+title: "RTCCodecStats: clockRate property"
+short-title: clockRate
+slug: Web/API/RTCCodecStats/clockRate
+page-type: web-api-instance-property
+browser-compat: api.RTCStatsReport.type_codec.clockRate
+---
+
+{{APIRef("WebRTC")}}
+
+The **`clockRate`** property of the {{domxref("RTCCodecStats")}} dictionary is a positive number containing the media sampling rate in hertz (Hz).
+
+## Values
+
+A positive number indicating the media sampling rate.
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- [`RTCRtpCodecParameters.clockRate`](/en-US/docs/Web/API/RTCRtpCodecParameters#clockrate)

files/en-us/web/api/rtccodecstats/id/index.md

@@ -0,0 +1,27 @@
+---
+title: "RTCCodecStats: id property"
+short-title: id
+slug: Web/API/RTCCodecStats/id
+page-type: web-api-instance-property
+browser-compat: api.RTCStatsReport.type_codec.id
+---
+
+{{APIRef("WebRTC")}}
+
+The **`id`** property of the {{domxref("RTCCodecStats")}} dictionary is a string that uniquely identifies the object for which this object provides statistics.
+
+Using the `id`, you can correlate this statistics object with others, in order to monitor statistics over time for a given WebRTC object, such as an {{domxref("RTCPeerConnection")}}, or an {{domxref("RTCDataChannel")}}.
+
+## Value
+
+A string that uniquely identifies the object for which this `RTCCodecStats` object provides statistics.
+
+The format of the ID string is not defined by the specification, so you cannot reliably make any assumptions about the contents of the string, or assume that the format of the string will remain unchanged for a given object type.
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}

files/en-us/web/api/rtccodecstats/index.md

@@ -0,0 +1,78 @@
+---
+title: RTCCodecStats
+slug: Web/API/RTCCodecStats
+page-type: web-api-interface
+browser-compat: api.RTCStatsReport.type_codec
+---
+
+{{DefaultAPISidebar("WebRTC")}}
+
+The **`RTCCodecStats`** dictionary of the [WebRTC API](/en-US/docs/Web/API/WebRTC_API) provides statistics about a codec used by {{Glossary("RTP")}} streams that are being sent or received by the associated {{domxref("RTCPeerConnection")}} object.
+
+These statistics can be obtained by iterating the {{domxref("RTCStatsReport")}} object returned by {{domxref("RTCPeerConnection.getStats()")}} until you find an entry with the [`type`](#type) of `codec`.
+
+The codec statistics can be correlated with the inbound or outbound stream statistics (both local and remote) by matching their `codecId` property to the codec's `id`.
+For example, if [`RTCInboundRtpStreamStats.codecId`](/en-US/docs/Web/API/RTCInboundRtpStreamStats#codecid) matches an [`RTCCodecStats.id`](#id) in the same report, then we know that the codec is being used on this peer connection's inbound stream.
+If no stream `codecId` references a codec statistic, then that codec statistic object is deleted — if the codec is used again, the statistics object will be recreated with the same `id`.
+
+Codec objects may be referenced by multiple RTP streams in media sections using the same transport.
+In fact, user agents are expected to consolidate information into a single "codec" entry per payload type per transport (unless [sdpFmtpLine](#sdpfmtpline) is different when sending or receiving, in which case, different codecs will be needed for encoding and decoding).
+Note that other transports will use their own distinct `RTCCodecStats` objects.
+
+## Instance properties
+
+- {{domxref("RTCCodecStats.channels", "channels")}} {{optional_inline}}
+  - : A positive number indicating the number of channels supported by the codec.
+- {{domxref("RTCCodecStats.clockRate", "clockRate")}} {{optional_inline}}
+  - : A positive number containing the media sampling rate.
+- {{domxref("RTCCodecStats.mimeType", "mimeType")}}
+  - : A string containing the media MIME type/sub-type, such as video/VP8.
+- {{domxref("RTCCodecStats.payloadType", "payloadType")}}
+  - : A positive integer value in the range of 0 to 127 indicating the payload type used in RTP encoding or decoding.
+- {{domxref("RTCCodecStats.sdpFmtpLine", "sdpFmtpLine")}} {{optional_inline}}
+  - : A string containing the format-specific parameters of the `"a=fmtp"` line in the codec's {{Glossary("SDP")}} (if present).
+- {{domxref("RTCCodecStats.transportId", "transportId")}}
+  - : A string containing the unique identifier of the transport on which this codec is being used.
+    This can be used to match to the corresponding {{domxref("RTCTransportStats")}} object.
+
+### Common instance properties
+
+The following properties are common to all WebRTC statistics objects (see [`RTCStatsReport`](/en-US/docs/Web/API/RTCStatsReport#common_instance_properties) for more information):
+
+<!-- RTCStats -->
+
+- {{domxref("RTCCodecStats.id", "id")}}
+  - : A string that uniquely identifies the object that is being monitored to produce this set of statistics.
+- {{domxref("RTCCodecStats.timestamp", "timestamp")}}
+  - : A {{domxref("DOMHighResTimeStamp")}} object indicating the time at which the sample was taken for this statistics object.
+- {{domxref("RTCCodecStats.type", "type")}}
+  - : A string with the value `"codec"`, indicating the type of statistics the object contains.
+
+## Examples
+
+Given a variable `myPeerConnection`, which is an instance of {{domxref("RTCPeerConnection")}}, the code below uses `await` to wait for the statistics report, and then iterates it using `RTCStatsReport.forEach()`.
+It then filters the dictionaries for just those reports that have the type of `codec` and logs the result.
+
+```js
+const stats = await myPeerConnection.getStats();
+
+stats.forEach((report) => {
+  if (report.type === "codec") {
+    // Log the codec information
+    console.log(report);
+  }
+});
+```
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- {{domxref("RTCStatsReport")}}
+- {{domxref("RTCRtpCodecParameters")}}

files/en-us/web/api/rtccodecstats/mimetype/index.md

@@ -0,0 +1,29 @@
+---
+title: "RTCCodecStats: mimeType property"
+short-title: mimeType
+slug: Web/API/RTCCodecStats/mimeType
+page-type: web-api-instance-property
+browser-compat: api.RTCStatsReport.type_codec.mimeType
+---
+
+{{APIRef("WebRTC")}}
+
+The **`mimeType`** property of the {{domxref("RTCCodecStats")}} dictionary is a string containing the codec's {{glossary("MIME type")}} and subtype.
+
+This is of the form `"type/subtype"`, such as "video/VP8" or "audio/opus", as defined in the [IANA registry of valid MIME types](https://www.iana.org/assignments/rtp-parameters/rtp-parameters.xhtml#rtp-parameters-2).
+
+## Values
+
+A string indicating the code MIME type/subtype.
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- [`RTCRtpCodecParameters.mimeType`](/en-US/docs/Web/API/RTCRtpCodecParameters#mimetype)

files/en-us/web/api/rtccodecstats/payloadtype/index.md

@@ -0,0 +1,31 @@
+---
+title: "RTCCodecStats: payloadType property"
+short-title: payloadType
+slug: Web/API/RTCCodecStats/payloadType
+page-type: web-api-instance-property
+browser-compat: api.RTCStatsReport.type_codec.payloadType
+---
+
+{{APIRef("WebRTC")}}
+
+The **`payloadType`** property of the {{domxref("RTCCodecStats")}} dictionary is a positive integer in the range from 0 to 127 that describes the format of the {{glossary("RTP")}} payload used in RTP encoding or decoding.
+
+## Value
+
+A positive integer between 0 and 127.
+
+The mappings of values to formats is defined in RFC3550, and more specifically in [Section 6: Payload Type Definitions](https://www.rfc-editor.org/rfc/rfc3551#section-6) of RFC3551.
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- [`RTCRtpCodecParameters.payloadType`](/en-US/docs/Web/API/RTCRtpCodecParameters#payloadtype)
+- `payloadType` returned by [`RTCEncodedAudioFrame.getMetadata()`](/en-US/docs/Web/API/RTCEncodedAudioFrame/getMetadata#payloadtype)
+- `payloadType` returned by [`RTCEncodedVideoFrame.getMetadata()`](/en-US/docs/Web/API/RTCEncodedVideoFrame/getMetadata#payloadtype)

files/en-us/web/api/rtccodecstats/sdpfmtpline/index.md

@@ -0,0 +1,45 @@
+---
+title: "RTCCodecStats: sdpFmtpLine property"
+short-title: sdpFmtpLine
+slug: Web/API/RTCCodecStats/sdpFmtpLine
+page-type: web-api-instance-property
+browser-compat: api.RTCStatsReport.type_codec.sdpFmtpLine
+---
+
+{{APIRef("WebRTC")}}
+
+The **`sdpFmtpLine`** property of the {{domxref("RTCCodecStats")}} dictionary is a string containing the format-specific parameters of the codec.
+
+These are the values in the `"a=fmtp"` line in the codec's {{Glossary("SDP")}} (if present) after the payload type number (see [section 5.8 of the IETF specification for JSEP](https://datatracker.ietf.org/doc/html/draft-ietf-rtcweb-jsep-24#section-5.8)).
+
+## Values
+
+A string containing the format-specific parameters of the codec.
+
+## Description
+
+The `"a=fmtp"` line in the codec's {{Glossary("SDP")}} line has the following format, where the payload type (see {{domxref("RTCCodecStats.payloadType")}}) and parameters depend on the codec:
+
+```plain
+a=fmtp:<payload_type_number> param1=value1; ...; paramN=valueN
+```
+
+For example, the following line would indicate that the "opus" codec, which has a `payloadType` 99, has the format-specific parameters `maxplaybackrate` and `stereo`:
+
+```plain
+a=fmtp:99 maxplaybackrate=16000; stereo=1;
+```
+
+For this codec, the value in `sdpFmtpLine` would be `maxplaybackrate=16000; stereo=1;`.
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- [`RTCRtpCodecParameters.sdpFmtpLine`](/en-US/docs/Web/API/RTCRtpCodecParameters#sdpfmtpline)

files/en-us/web/api/rtccodecstats/timestamp/index.md

@@ -0,0 +1,25 @@
+---
+title: "RTCCodecStats: timestamp property"
+short-title: timestamp
+slug: Web/API/RTCCodecStats/timestamp
+page-type: web-api-instance-property
+browser-compat: api.RTCStatsReport.type_codec.timestamp
+---
+
+{{APIRef("WebRTC")}}
+
+The **`timestamp`** property of the {{domxref("RTCCodecStats")}} dictionary is a {{domxref("DOMHighResTimeStamp")}} object specifying the time at which the data in the object was sampled.
+
+## Value
+
+A {{domxref("DOMHighResTimeStamp")}} value indicating the time at which the activity described by the statistics in this object was recorded, in milliseconds elapsed since the beginning of January 1, 1970, UTC.
+
+The value should be accurate to within a few milliseconds but may not be entirely precise, either because of hardware or operating system limitations or because of [fingerprinting](/en-US/docs/Glossary/Fingerprinting) protection in the form of reduced clock precision or accuracy.
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}

files/en-us/web/api/rtccodecstats/transportid/index.md

@@ -0,0 +1,25 @@
+---
+title: "RTCCodecStats: transportId property"
+short-title: transportId
+slug: Web/API/RTCCodecStats/transportId
+page-type: web-api-instance-property
+browser-compat: api.RTCStatsReport.type_codec.transportId
+---
+
+{{APIRef("WebRTC")}}
+
+The **`transportId`** property of the {{domxref("RTCCodecStats")}} dictionary is a string that contains the unique identifier of the corresponding transport on which this codec is being used.
+
+You can correlate the codec and associated transport statistics by matching the `RTCCodecStats.transportId` with an {{domxref("RTCTransportStats.id")}} value.
+
+## Value
+
+A string that uniquely identifies a matching {{domxref("RTCTransportStats")}} object using its `id`.
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}

files/en-us/web/api/rtccodecstats/type/index.md

@@ -0,0 +1,27 @@
+---
+title: "RTCCodecStats: type property"
+short-title: type
+slug: Web/API/RTCCodecStats/type
+page-type: web-api-instance-property
+browser-compat: api.RTCStatsReport.type_codec.type
+---
+
+{{APIRef("WebRTC")}}
+
+The **`type`** property of the {{domxref("RTCCodecStats")}} dictionary is a string with the value `"codec"`.
+
+Different statistics are obtained by iterating the {{domxref("RTCStatsReport")}} object returned by a call to {{domxref("RTCPeerConnection.getStats()")}}.
+The type indicates the set of statistics available through the object in a particular iteration step.
+A value of `"codec"` indicates that the statistics available in the current step are those defined in {{domxref("RTCCodecStats")}}.
+
+## Value
+
+A string with the value `"codec"`.
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}

files/jsondata/GroupData.json

@@ -2121,6 +2121,7 @@
         "RTCInboundRtpStreamStats",
         "RTCIceCandidateStats",
         "RTCAudioSourceStats",
+        "RTCCodecStats",
         "RTCOutboundRtpStreamStats",
         "RTCPeerConnectionStats",
         "RTCRemoteOutboundRtpStreamStats"