Skip to content

Commit

Permalink
Convert noteblocks for web/api folder (part 11) (#35135)
Browse files Browse the repository at this point in the history
This PR converts the noteblocks for the 'web/api' folder to GFM syntax, using a [conversion script](https://github.com/queengooborg/mdn-toolkit/blob/main/upgrade-noteblock.js). This is part 11.
  • Loading branch information
queengooborg committed Jul 26, 2024
1 parent 802b606 commit 4f35a82
Show file tree
Hide file tree
Showing 100 changed files with 264 additions and 132 deletions.
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,8 @@ communicate with the TURN server. The possible values are:
- `udp`
- : UDP (User Datagram Protocol) is being used to communicate with the TURN server.

> **Note:** This property is only present on
> [!NOTE]
> This property is only present on
> {{domxref("RTCIceCandidateStats")}} objects that represent local candidates.
## Specifications
Expand Down
3 changes: 2 additions & 1 deletion files/en-us/web/api/rtcicecandidatestats/url/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,8 @@ candidate described by the `RTCIceCandidateStats` was obtained. This is the
same URL that would be received in the {{domxref("RTCPeerConnection.icecandidate_event", "icecandidate")}} event's
{{domxref("RTCPeerConnectionIceEvent.url", "url")}} property.

> **Note:** This property does not exist for remote candidates.
> [!NOTE]
> This property does not exist for remote candidates.
## Specifications

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,8 @@ From that time forward, the best matching pair of candidates will always be avai

As ICE negotiation continues, any time a pair of candidates is discovered that is better than the currently-selected pair, the new pair is selected, replacing the previous pairing, and the `selectedcandidatepairchange` event is fired again.

> **Note:** It's possible for one of the configurations in the selected candidate pair to remain unchanged when a new pairing is chosen.
> [!NOTE]
> It's possible for one of the configurations in the selected candidate pair to remain unchanged when a new pairing is chosen.
## Examples

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -33,7 +33,8 @@ By using the FEC parity information to attempt to reconstruct damaged packets, i
possible to avoid the need to retransmit damaged packets, which in turn helps to
reduce lag, or the need to skip damaged frames entirely.

> **Note:** This counter may also be incremented when FEC packets arrive
> [!NOTE]
> This counter may also be incremented when FEC packets arrive
> in-band along with media content; this can happen with Opus, for example.
## Usage notes
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,8 @@ The **`lastPacketReceivedTimestamp`** property of the {{domxref("RTCInboundRtpSt

A {{domxref("DOMHighResTimeStamp")}} which specifies the time at which the most recently received packet arrived on this RTP stream.

> **Note:** This value differs from the {{domxref("RTCInboundRtpStreamStats.timestamp", "timestamp")}},
> [!NOTE]
> This value differs from the {{domxref("RTCInboundRtpStreamStats.timestamp", "timestamp")}},
> which represents the time at which the statistics object was created.
## Specifications
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -14,15 +14,17 @@ comprised of key/value pairs in which each key is a string representation of a
Differentiated Services Code Point and the value is the number of packets received for
that DCSP.

> **Note:** Not all operating systems make data available on a per-DSCP
> [!NOTE]
> Not all operating systems make data available on a per-DSCP
> basis, so this property shouldn't be relied upon on those systems.
## Value

A record comprised of string/value pairs. Each key is the string representation of a
single Differentiated Services Code Point (DSCP)'s ID number.

> **Note:** Due to network bleaching and remapping, the numbers seen on
> [!NOTE]
> Due to network bleaching and remapping, the numbers seen on
> this record are not necessarily going to match the values as they were when the data
> was sent.
Expand Down
3 changes: 2 additions & 1 deletion files/en-us/web/api/rtcinboundrtpstreamstats/qpsum/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,8 @@ An unsigned 64-bit integer value which indicates the sum of the quantization par
larger to indicate higher compression factors, the larger this sum is, the more heavily
compressed the stream generally has been.

> **Note:** This value is only available for video media.
> [!NOTE]
> This value is only available for video media.
## Usage notes

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -30,7 +30,8 @@ be an indication of an unreliable network.

This is a very technical part of how video codecs work. For details, see {{RFC(4585, "6.3.2")}}.

> **Note:** This value is only present for video media.
> [!NOTE]
> This value is only present for video media.
## Specifications

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,8 @@ source.
An integer value indicating the total number of video frames that this sender has
encoded so far for this stream.

> **Note:** This property is only valid for video streams.
> [!NOTE]
> This property is only valid for video streams.
## Specifications

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -13,15 +13,17 @@ of the {{domxref("RTCOutboundRtpStreamStats")}} dictionary is a record comprised
key/value pairs in which each key is a string representation of a Differentiated
Services Code Point and the value is the number of packets sent for that DCSP.

> **Note:** Not all operating systems make data available on a per-DSCP
> [!NOTE]
> Not all operating systems make data available on a per-DSCP
> basis, so this property shouldn't be relied upon on those systems.
## Value

A record comprised of string/value pairs. Each key is the string representation of a
single Differentiated Services Code Point (DSCP)'s ID number.

> **Note:** Due to network bleaching and remapping, the numbers seen on
> [!NOTE]
> Due to network bleaching and remapping, the numbers seen on
> this record are not necessarily going to match the values as they were when the data
> was sent.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,8 @@ the remote peer's {{domxref("RTCRtpReceiver")}}. These are sent by the receiver'
decoder to notify the sender's encoder that an undefined amount of coded video data,
which may span frame boundaries, has been lost.

> **Note:** This property is only used for video streams.
> [!NOTE]
> This property is only used for video streams.
## Usage notes

Expand Down
3 changes: 2 additions & 1 deletion files/en-us/web/api/rtcoutboundrtpstreamstats/qpsum/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,8 @@ In general, the higher this number is, the more heavily compressed the video dat
An unsigned 64-bit integer value which indicates the sum of the quantization parameter (QP) value for every frame sent so far on the track described by the {{domxref("RTCOutboundRtpStreamStats")}} object.
Since the value of QP is typically larger to indicate higher compression factors, the larger this sum is, the more heavily compressed the stream generally has been.

> **Note:** This value is only available for video media.
> [!NOTE]
> This value is only available for video media.
## Usage notes

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,8 @@ an indication of an unreliable network.

This is a very technical part of how video codecs work. For details, see {{RFC(4585, "6.3.2")}}.

> **Note:** This value is only present for video media.
> [!NOTE]
> This value is only present for video media.
## Specifications

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -72,7 +72,8 @@ addIceCandidate(candidate, successCallback, failureCallback) // deprecated

Additional information can be found in {{domxref("RTCIceCandidate.candidate")}}.

> **Note:** For backward compatibility with older versions of the WebRTC specification, the constructor also accepts this string directly as an argument.
> [!NOTE]
> For backward compatibility with older versions of the WebRTC specification, the constructor also accepts this string directly as an argument.
- `sdpMid` {{optional_inline}}

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,8 @@ browser-compat: api.RTCPeerConnection.addstream_event

The obsolete **`addstream`** event is sent to an {{domxref("RTCPeerConnection")}} when new media, in the form of a {{domxref("MediaStream")}} object, has been added to it.

> **Warning:** This event has been removed from the WebRTC specification. You should instead watch for the {{domxref("RTCPeerConnection.track_event", "track")}} event, which is sent for each media track added to the `RTCPeerConnection`.
> [!WARNING]
> This event has been removed from the WebRTC specification. You should instead watch for the {{domxref("RTCPeerConnection.track_event", "track")}} event, which is sent for each media track added to the `RTCPeerConnection`.
You can, similarly, watch for streams to be removed from the connection by monitoring the {{domxref("RTCPeerConnection.removestream_event", "removestream")}} event.

Expand Down
6 changes: 4 additions & 2 deletions files/en-us/web/api/rtcpeerconnection/addtrack/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,8 @@ browser-compat: api.RTCPeerConnection.addTrack

The **`addTrack()`** method of the {{domxref("RTCPeerConnection")}} interface adds a new media track to the set of tracks which will be transmitted to the other peer.

> **Note:** Adding a track to a connection triggers renegotiation by firing a {{DOMxRef("RTCPeerConnection/negotiationneeded_event", "negotiationneeded")}} event.
> [!NOTE]
> Adding a track to a connection triggers renegotiation by firing a {{DOMxRef("RTCPeerConnection/negotiationneeded_event", "negotiationneeded")}} event.
> See [Starting negotiation](/en-US/docs/Web/API/WebRTC_API/Signaling_and_video_calling#starting_negotiation) for details.
## Syntax
Expand All @@ -37,7 +38,8 @@ Any tracks that are added to the same stream on the local end of the connection

The {{domxref("RTCRtpSender")}} object which will be used to transmit the media data.

> **Note:** Every `RTCRtpSender` is paired with an {{domxref("RTCRtpReceiver")}} to make up an {{domxref("RTCRtpTransceiver")}}.
> [!NOTE]
> Every `RTCRtpSender` is paired with an {{domxref("RTCRtpReceiver")}} to make up an {{domxref("RTCRtpTransceiver")}}.
> The associated receiver is muted (indicating that it is not able to deliver packets) until and unless one or more streams are added to the receiver by the remote peer.
### Exceptions
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,8 @@ That way, the offer contains all of the candidates.
A boolean value that is `true` if the remote peer can accept trickled ICE candidates and `false` if it cannot.
If no remote peer has been established, this value is `null`.

> **Note:** This property's value is determined once the local peer has called {{domxref("RTCPeerConnection.setRemoteDescription()")}};
> [!NOTE]
> This property's value is determined once the local peer has called {{domxref("RTCPeerConnection.setRemoteDescription()")}};
> the provided description is used by the ICE agent to determine whether or not the remote peer supports trickled ICE candidates.
## Examples
Expand Down
3 changes: 2 additions & 1 deletion files/en-us/web/api/rtcpeerconnection/createanswer/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -59,7 +59,8 @@ A {{jsxref("Promise")}} whose fulfillment handler is called with an object confo
Here is a segment of code taken from the code that goes with the article [Signaling and video calling](/en-US/docs/Web/API/WebRTC_API/Signaling_and_video_calling).
This code comes from the handler for the message sent to carry an offer to another peer across the signaling channel.

> **Note:** Keep in mind that this is part of the signaling process, the transport layer for which is an implementation detail that's entirely up to you.
> [!NOTE]
> Keep in mind that this is part of the signaling process, the transport layer for which is an implementation detail that's entirely up to you.
> In this case, a [WebSocket](/en-US/docs/Web/API/WebSockets_API) connection is used to send a {{Glossary("JSON")}} message with a `type` field with the value "video-answer" to the other peer, carrying the answer to the device which sent the offer to connect.
> The contents of the object being passed to the `sendToServer()` function, along with everything else in the promise fulfillment handler, depend entirely on your design
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -56,7 +56,8 @@ createDataChannel(label, options)
permitted values are 0 to 65534.
If you don't include this option, the user agent will select an ID for you.

> **Note:** These options represent the script-settable subset of the properties on the {{domxref("RTCDataChannel")}} interface.
> [!NOTE]
> These options represent the script-settable subset of the properties on the {{domxref("RTCDataChannel")}} interface.
### Return value

Expand Down
3 changes: 2 additions & 1 deletion files/en-us/web/api/rtcpeerconnection/createoffer/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -77,7 +77,8 @@ Your rejection handler should examine the received exception to determine which

Here we see a handler for the {{DOMxRef("RTCPeerConnection/negotiationneeded_event", "negotiationneeded")}} event which creates the offer and sends it to the remote system over a signaling channel.

> **Note:** Keep in mind that this is part of the signaling process, the transport layer for which is an implementation detail that's entirely up to you.
> [!NOTE]
> Keep in mind that this is part of the signaling process, the transport layer for which is an implementation detail that's entirely up to you.
> In this case, a [WebSocket](/en-US/docs/Web/API/WebSockets_API) connection is used to send a {{Glossary("JSON")}} message with a `type` field with the value "video-offer" to the other peer.
> The contents of the object being passed to the `sendToServer()` function, along with everything else in the promise fulfillment handler, depend entirely on your design.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,8 @@ Also included is a list of any ICE candidates that may already have been generat
To change the `currentLocalDescription`, call {{domxref("RTCPeerConnection.setLocalDescription()")}}, which triggers a series of events which leads to this value being set.
For details on what exactly happens and why the change isn't necessarily instantaneous, see [Pending and current descriptions](/en-US/docs/Web/API/WebRTC_API/Connectivity#pending_and_current_descriptions) in the WebRTC Connectivity page.

> **Note:** Unlike {{domxref("RTCPeerConnection.localDescription")}}, this value represents the actual current state of the local end of the connection;
> [!NOTE]
> Unlike {{domxref("RTCPeerConnection.localDescription")}}, this value represents the actual current state of the local end of the connection;
> `localDescription` may specify a description which the connection is currently in the process of switching over to.
## Value
Expand Down Expand Up @@ -46,7 +47,8 @@ if (sd) {

{{Compat}}

> **Note:** The addition of `currentLocalDescription` and {{domxref("RTCPeerConnection.pendingLocalDescription", "pendingLocalDescription")}} to the WebRTC spec is relatively recent.
> [!NOTE]
> The addition of `currentLocalDescription` and {{domxref("RTCPeerConnection.pendingLocalDescription", "pendingLocalDescription")}} to the WebRTC spec is relatively recent.
> In browsers which don't support them, just use {{domxref("RTCPeerConnection.localDescription", "localDescription")}}.
## See also
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,8 @@ Also included is a list of any ICE candidates that may already have been generat
To change the `currentRemoteDescription`, call {{domxref("RTCPeerConnection.setRemoteDescription()")}}, which triggers a series of events which leads to this value being set.
For details on what exactly happens and why the change isn't necessarily instantaneous, see [Pending and current descriptions](/en-US/docs/Web/API/WebRTC_API/Connectivity#pending_and_current_descriptions) in the WebRTC Connectivity page.

> **Note:** Unlike {{domxref("RTCPeerConnection.remoteDescription")}}, this value represents the actual current state of the local end of the connection;
> [!NOTE]
> Unlike {{domxref("RTCPeerConnection.remoteDescription")}}, this value represents the actual current state of the local end of the connection;
> `remoteDescription` may specify a description which the connection is currently in the process of switching over to.
## Value
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,8 @@ browser-compat: api.RTCPeerConnection.datachannel_event

A **`datachannel`** event is sent to an {{domxref("RTCPeerConnection")}} instance when an {{domxref("RTCDataChannel")}} has been added to the connection, as a result of the remote peer calling {{domxref("RTCPeerConnection.createDataChannel()")}}.

> **Note:** This event is _not_ dispatched when the local end of the connection creates the channel.
> [!NOTE]
> This event is _not_ dispatched when the local end of the connection creates the channel.
This event is not cancelable and does not bubble.

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,8 @@ This signifies that the value of the connection's {{domxref("RTCPeerConnection.i

When ICE first starts to gather connection candidates, the value changes from `new` to `gathering` to indicate that the process of collecting candidate configurations for the connection has begun. When the value changes to `complete`, all of the transports that make up the `RTCPeerConnection` have finished gathering ICE candidates.

> **Note:** While you can determine that ICE candidate gathering is complete by watching for `icegatheringstatechange` events and checking for the value of {{domxref("RTCPeerConnection.iceGatheringState", "iceGatheringState")}} to become `complete`, you can also have your handler for the {{domxref("RTCPeerConnection.icecandidate_event", "icecandidate")}} event look to see if its {{domxref("RTCPeerConnectionIceEvent.candidate", "candidate")}} property is `null`. This also indicates that collection of candidates is finished.
> [!NOTE]
> While you can determine that ICE candidate gathering is complete by watching for `icegatheringstatechange` events and checking for the value of {{domxref("RTCPeerConnection.iceGatheringState", "iceGatheringState")}} to become `complete`, you can also have your handler for the {{domxref("RTCPeerConnection.icecandidate_event", "icecandidate")}} event look to see if its {{domxref("RTCPeerConnectionIceEvent.candidate", "candidate")}} property is `null`. This also indicates that collection of candidates is finished.
This event is not cancelable and does not bubble.

Expand Down
3 changes: 2 additions & 1 deletion files/en-us/web/api/rtcpeerconnection/peeridentity/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,8 @@ A JavaScript {{jsxref("Promise")}} which resolves to an {{domxref("RTCIdentityAs
If an error occurs while attempting to validate an incoming identity assertion (that is, the information describing a peer's identity), the promise is rejected.
If there isn't already a target peer identity, `peerIdentity` is set to a newly created promise and the process begins again, until the process succeeds or no further attempts to authenticate occur.

> **Note:** The promise returned by {{domxref("RTCPeerConnection.setRemoteDescription", "setRemoteDescription()")}} cannot resolve until any target peer identity that's been set is validated.
> [!NOTE]
> The promise returned by {{domxref("RTCPeerConnection.setRemoteDescription", "setRemoteDescription()")}} cannot resolve until any target peer identity that's been set is validated.
> If the identity hasn't been validated yet, the promise returned by `setRemoteDescription()` will be rejected.
> If there's no target peer identity, `setRemoteDescription()` doesn't need to wait for validation to occur before it resolves.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -42,7 +42,8 @@ if (sd) {

{{Compat}}

> **Note:** The addition of `pendingLocalDescription` and {{domxref("RTCPeerConnection.currentLocalDescription", "currentLocalDescription")}} to the WebRTC spec is relatively recent.
> [!NOTE]
> The addition of `pendingLocalDescription` and {{domxref("RTCPeerConnection.currentLocalDescription", "currentLocalDescription")}} to the WebRTC spec is relatively recent.
> In browsers which don't support them, only {{domxref("RTCPeerConnection.localDescription", "localDescription")}} is available.
## See also
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -43,7 +43,8 @@ if (sd) {

{{Compat}}

> **Note:** The addition of `pendingRemoteDescription` and {{domxref("RTCPeerConnection.currentRemoteDescription", "currentRemoteDescription")}} to the WebRTC spec is relatively recent.
> [!NOTE]
> The addition of `pendingRemoteDescription` and {{domxref("RTCPeerConnection.currentRemoteDescription", "currentRemoteDescription")}} to the WebRTC spec is relatively recent.
> In browsers which don't support them, only {{domxref("RTCPeerConnection.remoteDescription", "remoteDescription")}} is available.
## See also
Expand Down
Loading

0 comments on commit 4f35a82

Please sign in to comment.