Skip to content

Commit

Permalink
Merge pull request #203 from w3c/mv-jitterbuffertarget
Browse files Browse the repository at this point in the history 
Move jitterBufferTarget to main spec
  • Loading branch information
@jan-ivar
jan-ivar committed Apr 11, 2024
2 parents 7081c0d + be3ec6f commit c687715
Showing 1 changed file with 0 additions and 136 deletions.
136 changes: 0 additions & 136 deletions index.html
View file
Expand Up @@ -362,142 +362,6 @@ <h3>Methods</h3>
</dl>
</section>
</section>
<section id="rtcrtpreceiver-jitterbuffertarget">
<h3>
Adjusting the receiver's jitter buffer
</h3>
<p>
The {{RTCRtpReceiver}}
interface is defined in [[WEBRTC]]. This document extends that interface
by adding an additional attribute to adjust the receiver's jitter buffer.
</p>
<section id="rtcrtpreceiver-jitterbuffertarget-modifications">
<h2>Modification to existing procedures</h2>
<p>
Let {{RTCRtpReceiver}} objects have a <dfn data-dfn-for=RTCRtpReceiver>[[\JitterBufferTarget]]</dfn> internal slot initially
initialized to <code>null</code>.
</p>
</section>
<section id="rtcrtpreceiver-jitterbuffertarget-rtcrtpreceiver-interface">
<h2>{{RTCRtpReceiver}} interface extensions</h2>
<pre class="idl">partial interface RTCRtpReceiver {
attribute DOMHighResTimeStamp? jitterBufferTarget;
};</pre>
</section>
<section id="rtcrtpreceiver-jitterbuffertarget-attributes">
<h2>Attributes</h2>
<dl data-link-for="RTCRtpReceiver" data-dfn-for="RTCRtpReceiver"
class="attributes">
<dt><dfn>jitterBufferTarget</dfn> of type <span
class="idlAttrType">DOMHighResTimeStamp</span>, nullable</dt>
<dd>
<p>This attribute allows the application to specify a target duration
of time in milliseconds of media for the {{RTCRtpReceiver}}'s jitter
buffer to hold. This influences the amount of buffering done by the
<a>user agent</a>, which in turn affects retransmissions and packet loss
recovery. Altering the target value allows applications to control the
tradeoff between playout delay and the risk of running out of audio or
video frames due to network jitter.

<p>The <a>user agent</a> MUST have a <dfn>minimum allowed target</dfn> and a
<dfn>maximum allowed target</dfn> reflecting what the <a>user agent</a> is
able or willing to provide based on network conditions and memory
constraints, which can change at any time.</p>
<div class="note">
<p>This is a target value. The resulting change in delay can be gradually
observed over time. The receiver's average jitter buffer delay can be
measured as the delta
{{RTCInboundRtpStreamStats/jitterBufferDelay}} divided by the delta
{{RTCInboundRtpStreamStats/jitterBufferEmittedCount}}.
</p>
<p>
An average delay is expected even if DTX is used. For example, if
DTX is used and packets start flowing after silence, larger targets can
influence the <a>user agent</a> to buffer these packets rather than
playing them out.
</p>
</div>
<p>On getting, this attribute MUST return the value of the
{{RTCRtpReceiver/[[JitterBufferTarget]]}} internal slot.</p>
<p>On setting, the <a>user agent</a> MUST run the following steps:</p>
<ol>
<li>
<p>Let <var>receiver</var> be the
{{RTCRtpReceiver}} object on which the setter is
invoked.</p>
</li>
<li>
<p>Let <var>target</var> be the argument to the setter.</p>
</li>
<li>
<p>If <var>target</var> is negative or larger than 4000 milliseconds, then
[=exception/throw=] a {{RangeError}}.</p>
</li>
<li>
<p>Set <var>receiver</var>'s {{RTCRtpReceiver/[[JitterBufferTarget]]}}
to <var>target</var>.</p>
</li>
<li>
<p>Let <var>track</var> be <var>receiver</var>'s
{{RTCRtpReceiver/[[ReceiverTrack]]}}.</p>
</li>
<li>
<p>In parallel, begin executing the following steps:</p>
<ol>
<li>
<p>Update the underlying system about the new <var>target</var>,
or that there is no application preference if <var>target</var> is
<code>null</code>.</p>
<p>
If <var>track</var> is synchronized with another
{{RTCRtpReceiver}}'s track for
<a data-cite="RFC5888#section-7">audio/video synchronization</a>,
then the <a>user agent</a> SHOULD use the larger of the two receivers'
{{RTCRtpReceiver/[[JitterBufferTarget]]}} for both receivers.
</p>
<p>
When the underlying system is applying a jitter buffer target, it will
continuously make sure that the actual jitter buffer target is clamped
within the <a>minimum allowed target</a> and <a>maximum allowed
target</a>.
<p class="note">
If the <a>user agent</a> ends up using a target different from the
requested one (e.g. due to network conditions or physical memory
constraints), this is not reflected in the
{{RTCRtpReceiver/[[JitterBufferTarget]]}} internal slot.
</p>
</p>
</li>
<li>
<p>Modifying the jitter buffer target of the underlying system SHOULD
affect the internal audio or video buffering gradually in order not
to hurt user experience. Audio samples or video frames SHOULD
be accelerated or decelerated before playout, similarly to how
it is done for
<a data-cite="RFC5888#section-7">
audio/video synchronization</a> or in response to congestion
control.</p>
<p>The acceleration or deceleration rate may vary depending on
network conditions or the type of audio received (e.g. speech
or background noise). It MAY take several seconds to achieve 1
second of buffering but SHOULD not take more than 30 seconds
assuming packets are being received. The speed MAY be
different for audio and video.</p>
<p class="note">
For audio, acceleration and deceleration can be measured
with {{RTCInboundRtpStreamStats/insertedSamplesForDeceleration}}
and {{RTCInboundRtpStreamStats/removedSamplesForAcceleration}}.
For video, this may result in the same frame being rendered
multiple times or frames may be dropped.
</p>
</li>
</ol>
</li>
</ol>
</dd>
</dl>
</section>
</section>
<section id="rtcrtpencodingparameters">
<h3>
RTCRtpEncodingParameters extensions
Expand Down

0 comments on commit c687715

Please sign in to comment.