Skip to content

Commit

Permalink
Define how to expose sender and receiver errors
Browse files Browse the repository at this point in the history 
fixes w3c#146
  • Loading branch information
@fippo
fippo committed Oct 17, 2023
1 parent 3ab7dbd commit 660f030
Showing 1 changed file with 177 additions and 28 deletions.
205 changes: 177 additions & 28 deletions index.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -1273,35 +1273,184 @@ <h3>Modifications to existing procedures</h3>
</p>
</section>
</section>
<section class="informative">
<h2>Event summary</h2>
<section id="encoder-decoder-errors">
<h2>Exposing encoder and decoder errors to the application</h2>
<p>
The following events fire on {{RTCIceTransport}} objects:</p>
<table class="simple">
<thead>
<tr>
<th>Event name</th>
<th>Interface</th>
<th>Fired when...</th>
</tr>
</thead>
<tbody>
<tr>
<th scope=row><dfn data-dfn-for="RTCIceTransport" data-dfn-type=event>icecandidatepairadd</dfn></th>
<td>{{RTCIceCandidatePairEvent}}</td>
<td>
The [= ICE agent =] has formed a candidate pair and is making it available to the script.
</td>
</tr>
<tr>
<th scope=row><dfn data-dfn-for="RTCIceTransport" data-dfn-type=event>icecandidatepairremove</dfn></th>
<td>{{RTCIceCandidatePairEvent}}</td>
<td>
The [= ICE agent =] has picked a candidate pair to remove, and unless the operation is canceled by invoking the <code>preventDefault()</code> method on the event, it will be removed.
</td>
</tr>
</tbody>
</table>
The encoding and decoding of (primarily video) frames can occasionally fail for a number of reasons.
In those cases the user agent may fallback from a hardware encoder/decoder to a software decoder with
lower performance or may loose to a hardware encoder/decoder without being able to fallback to software.
In such cases the application needs to be informed and take action such as renegotiation a different
set of codecs.
<p class="note">This excludes issues like the loss of packets/slices in a frame or not receiving
a decodable frame for a certain amount of time that are typically handled by sending RTCP feedback
such as NACK or PLI to the other side.
</p>
</p>
<section id="encoder-decoder-errors-extensions">
<h3>
{{RTCRtpSender}} and RTCRtpReceiver interface extensions
</h3>
<div>
<pre class="idl">[Exposed=Window]
partial interface RTCRtpSender {
attribute EventHandler error;
};
partial interface RTCRtpReceiver {
attribute EventHandler error;
};</pre>
</div>
</section>
<section id="encoder-errors-interface">
<h2>
RTCRtpSender {{RTCRtpSender/error}} definition
</h2>
<p>
The {{RTCRtpSender/error}} event uses the {{RTCRtpSenderErrorEvent}} interface.
</p>
<div>
<pre class="idl">[Exposed=Window]
interface RTCRtpSenderErrorEvent : Event {
constructor(DOMString type, RTCRtpSenderErrorEventInit eventInitDict);
readonly attribute unsigned long? spatialIndex;
readonly attribute unsigned long rtpTimestamp;
readonly attribute unsigned short errorCode;
readonly attribute USVString errorText;
};</pre>
</div>
<div>
<pre class="idl">
dictionary RTCRtpSenderErrorEventInit : EventInit {
unsigned long? spatialIndex;
unsigned long rtpTimestamp;
unsigned short errorCode;
USVString errorText;
};</pre>
<section id="rtcrtpsendererroreventinit">
<h4>Dictionary <dfn>RTCRtpSenderErrorEventInit</dfn> Members</h4>
<dl data-link-for="RTCRtpSenderErrorEventInit" data-dfn-for="RTCRtpSenderErrorEventInit"
class="dictionary-members">
<dt>
<dfn>spatialIndex</dfn> of type <span class="idlAttrType">unsigned long</span>, optional
</dt>
<dd>
<p>
When simulcast is used, this is the spatial index of the layer on which the error occured.
Unset when simulcast is not used, unset for SVC.
</p>
</dd>
<dt>
<dfn>rtpTimestamp</dfn> of type <span class="idlAttrType">unsigned long</span>, required
</dt>
<dd>
<p>
The RTP timestamp that would have been associated with the frame if it had been sent over the network.
</p>
</dd>
<dt>
<dfn>errorCode</dfn> of type <span class="idlAttrType">unsigned short</span>, required
</dt>
<dd>
<p>
An implementation-specific numeric error code used to differentiate error causes.
</p>
</dd>
<dt>
<dfn>errorText</dfn> of type <span class="idlAttrType">USVString</span>, required
</dt>
<dd>
<p>
An implementation-specific human-readable description of the error.
</p>
</dd>
</dl>
</section>
</div>
</section>
<section id="decoder-errors-interface">
<h2>
RTCRtpReceiver {{RTCRtpReceiver/error}} definition
</h2>
<p>
The {{RTCRtpReceiver/error}} event uses the {{RTCRtpReceiverErrorEvent}} interface.
</p>
<div>
<pre class="idl">[Exposed=Window]
interface RTCRtpReceiverErrorEvent : Event {
constructor(DOMString type, RTCRtpReceiverErrorEventInit eventInitDict);
readonly attribute unsigned long rtpTimestamp;
readonly attribute unsigned short errorCode;
readonly attribute USVString errorText;
};</pre>
</div>
<div>
<pre class="idl">
dictionary RTCRtpReceiverErrorEventInit : EventInit {
unsigned long rtpTimestamp;
unsigned short errorCode;
USVString errorText;
};</pre>
<section id="rtcrtpreceivererroreventinit">
<h4>Dictionary <dfn>RTCRtpReceiverErrorEventInit</dfn> Members</h4>
<dl data-link-for="RTCRtpReceiverErrorEventInit" data-dfn-for="RTCRtpReceiverErrorEventInit"
class="dictionary-members">
<dt>
<dfn>rtpTimestamp</dfn> of type <span class="idlAttrType">unsigned long</span>, required
</dt>
<dd>
<p>
The RTP timestamp of the frame that caused the decode error.
</p>
</dd>
<dt>
<dfn>errorCode</dfn> of type <span class="idlAttrType">unsigned short</span>, required
</dt>
<dd>
<p>
An implementation-specific numeric error code used to differentiate error causes.
</p>
</dd>
<dt>
<dfn>errorText</dfn> of type <span class="idlAttrType">USVString</span>, required
</dt>
<dd>
<p>
An implementation-specific human-readable description of the error.
</p>
</dd>
</dl>
</section>
</div>
</section>
<section class="informative">
<h2>Event summary</h2>
<p>
The following events fire on {{RTCRtpSender}} and {{RTCRtpReceiver}} objects:</p>
<table class="simple">
<thead>
<tr>
<th>Event name</th>
<th>Interface</th>
<th>Fired when...</th>
</tr>
</thead>
<tbody>
<tr>
<th scope=row><dfn data-dfn-for="RTCRtpSender" data-dfn-type=event></dfn>error</th>
<td>{{RTCRtpSenderErrorEventInit}}</td>
<td>
The encoder associated with the RTP sender encountered an error.
</td>
</tr>
<tr>
<th scope=row><dfn data-dfn-for="RTCRtpReceiver" data-dfn-type=event></dfn>error</th>
<td>{{RTCRtpReceiverErrorEventInit}}</td>
<td>
The decoder associated with the RTP receiver encountered an error.
</td>
</tr>
</tbody>
</table>
</section>
</section>
<section class="informative" id="security-considerations">
<h2>
Expand Down

0 comments on commit 660f030

Please sign in to comment.