Skip to content

Editorial: formalize TimeRanges #12454

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
annevk merged 1 commit into from
May 14, 2026
+76 −40
Merged

Editorial: formalize TimeRanges #12454

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
116 changes: 76 additions & 40 deletions source
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -39605,11 +39605,11 @@ interface <dfn interface>MediaError</dfn> {

<div algorithm>
<p>The <dfn attribute for="HTMLMediaElement"><code
data-x="dom-media-buffered">buffered</code></dfn> attribute must return a new static
<span>normalized <code>TimeRanges</code> object</span> that represents the ranges of the
<span>media resource</span>, if any, that the user agent has buffered, at the time the attribute
is evaluated. User agents must accurately determine the ranges available, even for media streams
where this can only be determined by tedious inspection.</p>
data-x="dom-media-buffered">buffered</code></dfn> getter steps are to return a new
<span>normalized <code>TimeRanges</code> object</span> that represents the ranges of
<span>this</span>'s <span>media resource</span>, if any, that the user agent has buffered. User
agents must accurately determine the ranges available, even for media streams where this can
only be determined by tedious inspection.</p>
</div>

<p class="note">Typically this will be a single range anchored at the zero point, but if, e.g. the
Expand Down Expand Up @@ -40499,10 +40499,10 @@ interface <dfn interface>MediaError</dfn> {

<div algorithm>
<p>The <dfn attribute for="HTMLMediaElement"><code data-x="dom-media-played">played</code></dfn>
attribute must return a new static <span>normalized <code>TimeRanges</code> object</span> that
represents the ranges of points on the <span>media timeline</span> of the <span>media
resource</span> reached through the usual monotonic increase of the <span>current playback
position</span> during normal playback, if any, at the time the attribute is evaluated.</p>
getter steps are to return a new <span>normalized <code>TimeRanges</code> object</span> that
represents the ranges of points on the <span>media timeline</span> of <span>this</span>'s
<span>media resource</span> reached through the usual monotonic increase of <span>this</span>'s
<span>current playback position</span> during normal playback, if any.</p>
</div>

<p class="warning">Returning a new object each time is a bad pattern for attribute getters and is
Expand Down Expand Up @@ -41170,10 +41170,10 @@ interface <dfn interface>MediaError</dfn> {

<div algorithm>
<p>The <dfn attribute for="HTMLMediaElement"><code
data-x="dom-media-seekable">seekable</code></dfn> attribute must return a new static
<span>normalized <code>TimeRanges</code> object</span> that represents the ranges of the
<span>media resource</span>, if any, that the user agent is able to seek to, at the time the
attribute is evaluated.</p>
data-x="dom-media-seekable">seekable</code></dfn> getter steps are to return a new
<span>normalized <code>TimeRanges</code> object</span> that represents the ranges of
<span>this</span>'s <span>media resource</span>, if any, that the user agent is able to seek
to.</p>
</div>

<p class="note">If the user agent can seek to anywhere in the <span>media resource</span>, e.g.
Expand Down Expand Up @@ -43577,52 +43577,88 @@ interface <dfn interface>TimeRanges</dfn> {

<div w-nodev>

<p>A <code>TimeRanges</code> object has <dfn data-x="timeranges-ranges">ranges</dfn>, a
<span>list</span> of zero or more <span data-x="timeranges-range">time ranges</span>.</p>

<p>A <dfn data-x="timeranges-range">time range</dfn> is a <span>struct</span> with the following
<span data-x="struct item">items</span>:</p>

<ul>
<li><p>A <dfn data-x="timeranges-range-start">start</dfn>, a number, in seconds.</p></li>

<li><p>An <dfn data-x="timeranges-range-end">end</dfn>, a number, in seconds.</p></li>
</ul>

<div algorithm>
<p>The <dfn attribute for="TimeRanges"><code data-x="dom-TimeRanges-length">length</code></dfn>
IDL attribute must return the number of ranges represented by the object.</p>
getter steps are to return <span>this</span>'s <span data-x="timeranges-ranges">ranges</span>'s
<span data-x="list size">size</span>.</p>
</div>

<div algorithm>
<p>The <dfn method for="TimeRanges"><code
data-x="dom-TimeRanges-start">start(<var>index</var>)</code></dfn> method must return the position
of the start of the <var>index</var>th range represented by the object, in seconds measured from
the start of the timeline that the object covers.</p>
data-x="dom-TimeRanges-start">start(<var>index</var>)</code></dfn> method steps are:</p>

<ol>
<li><p>If <var>index</var> is greater than or equal to <span>this</span>'s <span
data-x="timeranges-ranges">ranges</span>'s <span data-x="list size">size</span>, then throw an
<span>"<code>IndexSizeError</code>"</span> <code>DOMException</code>.</p></li>

<li><p>Return <span>this</span>'s <span
data-x="timeranges-ranges">ranges</span>[<var>index</var>]'s <span
data-x="timeranges-range-start">start</span>.</p></li>
</ol>
</div>

<div algorithm>
<p>The <dfn method for="TimeRanges"><code
data-x="dom-TimeRanges-end">end(<var>index</var>)</code></dfn> method must return the position of
the end of the <var>index</var>th range represented by the object, in seconds measured from the
start of the timeline that the object covers.</p>
</div>
data-x="dom-TimeRanges-end">end(<var>index</var>)</code></dfn> method steps are:</p>

<ol>
<li><p>If <var>index</var> is greater than or equal to <span>this</span>'s <span
data-x="timeranges-ranges">ranges</span>'s <span data-x="list size">size</span>, then throw an
<span>"<code>IndexSizeError</code>"</span> <code>DOMException</code>.</p></li>

<p>These methods must throw <span>"<code>IndexSizeError</code>"</span> <code>DOMException</code>s
if called with an <var ignore>index</var> argument greater than or equal to the number of ranges
represented by the object.</p>
<li><p>Return <span>this</span>'s <span
data-x="timeranges-ranges">ranges</span>[<var>index</var>]'s <span
data-x="timeranges-range-end">end</span>.</p></li>
</ol>
</div>

<div algorithm>
<p>When a <code>TimeRanges</code> object is said to be a <dfn
id="normalised-timeranges-object" export><!-- en-GB -->normalized <code>TimeRanges</code> object</dfn>,
the ranges it represents must obey the following criteria:</p>
<p>A <code>TimeRanges</code> object is a <dfn id="normalised-timeranges-object" export><!-- en-GB
-->normalized <code>TimeRanges</code> object</dfn> if the following are true for each <span
data-x="timeranges-range">time range</span> in its <span
data-x="timeranges-ranges">ranges</span>:</p>

<ul>
<li>The start of a range must be greater than the end of all earlier ranges.</li>
<li><p>Its <span data-x="timeranges-range-start">start</span> is greater than the <span
data-x="timeranges-range-end">end</span> of all earlier <span data-x="timeranges-range">time
ranges</span>.</p></li>

<li>The start of a range must be less than or equal to the end of that same range.</li>
<li><p>Its <span data-x="timeranges-range-start">start</span> is less than or equal to its <span
data-x="timeranges-range-end">end</span>.</p></li>
</ul>
</div>

<p>In other words, the ranges in such an object are ordered, don't overlap, and don't touch
(adjacent ranges are folded into one bigger range). A range can be empty (referencing just a
single moment in time), e.g. to indicate that only one frame is currently buffered in the case
that the user agent has discarded the entire <span>media resource</span> except for the current
frame, when a <span>media element</span> is paused.</p>

<p>Ranges in a <code>TimeRanges</code> object must be inclusive.</p>

<p class="example">Thus, the end of a range would be equal to the start of a following adjacent
(touching but not overlapping) range. Similarly, a range covering a whole timeline anchored at
zero would have a start equal to zero and an end equal to the duration of the timeline.</p>
<p>In other words, the <span data-x="timeranges-range">time ranges</span> in such an object are
ordered, don't overlap, and don't touch (adjacent ones are folded into one bigger <span
data-x="timeranges-range">time range</span>). A <span data-x="timeranges-range">time range</span>
can be empty (referencing just a single moment in time), e.g., to indicate that only one frame is
currently buffered in the case that the user agent has discarded the entire <span>media
resource</span> except for the current frame, when a <span>media element</span> is paused.</p>

<p>A <span data-x="timeranges-range">time range</span>'s <span
data-x="timeranges-range-start">start</span> and <span data-x="timeranges-range-end">end</span>
are inclusive.</p>

<p class="example">Thus, the <span data-x="timeranges-range-end">end</span> of a <span
data-x="timeranges-range">time range</span> would be equal to the <span
data-x="timeranges-range-start">start</span> of a following adjacent (touching but not
overlapping) <span data-x="timeranges-range">time range</span>. Similarly, a <span
data-x="timeranges-range">time range</span> covering a whole timeline anchored at zero would have
a <span data-x="timeranges-range-start">start</span> equal to zero and an <span
data-x="timeranges-range-end">end</span> equal to the duration of the timeline.</p>

<p>The timelines used by the objects returned by the <code
data-x="dom-media-buffered">buffered</code>, <code data-x="dom-media-seekable">seekable</code>, and
Expand Down
Loading