More clearly define “normalized TimeRanges object” (mdn#3708)

* More clearly define “normalized TimeRanges object” This change adds a definition for “normalized TimeRanges object” and links to it from the articles for the properties of HTMLMediaElement objects that return normalized TimeRanges objects. Fixes mdn#3705 * Update files/en-us/web/api/htmlmediaelement/buffered/index.html Co-authored-by: wbamberg <[email protected]> * Update files/en-us/web/api/htmlmediaelement/seekable/index.html Co-authored-by: wbamberg <[email protected]> * Drop specific back-references Co-authored-by: wbamberg <[email protected]>
ohtori · Apr 1, 2021 · 0867937 · 0867937
1 parent d227ada
commit 0867937
Show file tree

Hide file tree

Showing 3 changed files with 21 additions and 31 deletions.
diff --git a/files/en-us/web/api/htmlmediaelement/buffered/index.html b/files/en-us/web/api/htmlmediaelement/buffered/index.html
@@ -11,10 +11,7 @@
 ---
 <div>{{APIRef("HTML DOM")}}</div>
 
-<p>The <strong><code>HTMLMediaElement.buffered</code></strong> read-only property returns
-  a new {{domxref("TimeRanges")}} object that indicates the ranges of the media source
-  that the browser has buffered (if any) at the moment the <code>buffered</code> property
-  is accessed.</p>
+<p>The <strong><code>buffered</code></strong> read-only property of {{domxref("HTMLMediaElement")}} objects returns a new static <a href="/en-US/docs/Web/API/TimeRanges#normalized_timeranges_objects">normalized <code>TimeRanges</code> object</a> that represents the ranges of the media resource, if any, that the user agent has buffered at the moment the <code>buffered</code> property is accessed.</p>
 
 <div class="note"><strong>Note:</strong> This feature is not available in <a
     href="/en-US/docs/Web/API/Web_Workers_API">Web Workers</a>.</div>
@@ -26,10 +23,7 @@ <h2 id="Syntax">Syntax</h2>
 
 <h3 id="Value">Value</h3>
 
-<p>A {{domxref("TimeRanges")}} object. This object is <a
-    href="/en-US/docs/Web/API/TimeRanges">normalized</a>, which means that ranges are
-  ordered, don't overlap, aren't empty, and don't touch (adjacent ranges are folded into
-  one bigger range).</p>
+<p>A new static <a href="/en-US/docs/Web/API/TimeRanges#normalized_timeranges_objects">normalized TimeRanges object</a> that represents the ranges of the media resource, if any, that the user agent has buffered at the moment the <code>buffered</code> property is accessed.</p>
 
 <h2 id="Example">Example</h2>
 
@@ -47,16 +41,14 @@ <h2 id="Specifications">Specifications</h2>
       <th scope="col">Comment</th>
     </tr>
     <tr>
-      <td>{{SpecName('HTML WHATWG', "embedded-content.html#media-elements",
-        "HTMLMediaElement.buffered")}}</td>
+      <td>{{SpecName('HTML WHATWG', "https://html.spec.whatwg.org/multipage/media.html#dom-media-buffered", "buffered")}}</td>
       <td>{{Spec2('HTML WHATWG')}}</td>
-      <td>No change from {{SpecName('HTML5 W3C')}}</td>
+      <td></td>
     </tr>
     <tr>
-      <td>{{SpecName('HTML5 W3C', "embedded-content-0.html#htmlmediaelement",
-        "HTMLMediaElement.buffered")}}</td>
-      <td>{{Spec2('HTML5 W3C')}}</td>
-      <td>Initial definition.</td>
+      <td>{{SpecName('Media Source Extensions','#htmlmediaelement-extensions')}}</td>
+      <td>{{Spec2('Media Source Extensions')}}</td>
+      <td>Specifies a new algorithm for returning the buffered ranges of an element whose source is a {{domxref("MediaSource")}} object.</td>
     </tr>
   </tbody>
 </table>

diff --git a/files/en-us/web/api/htmlmediaelement/seekable/index.html b/files/en-us/web/api/htmlmediaelement/seekable/index.html
@@ -16,17 +16,16 @@
 ---
 <div>{{APIRef("HTML DOM")}}</div>
 
-<p>The <strong><code>seekable</code></strong> read-only property of the
-  {{domxref("HTMLMediaElement")}} returns a {{domxref('TimeRanges')}} object that
-  contains the time ranges that the user is able to seek to, if any.</p>
+
+<p>The <strong><code>seekable</code></strong> read-only property of {{domxref("HTMLMediaElement")}} objects returns a new static <a href="/en-US/docs/Web/API/TimeRanges#normalized_timeranges_objects">normalized <code>TimeRanges</code> object</a> that represents the ranges of the media resource, if any, that the user agent is able to seek to at the time <code>seekable</code> property is accessed.</p>
 
 <h2 id="Syntax">Syntax</h2>
 
 <pre class="brush: js">var seekable = audioOrVideo.seekable;</pre>
 
 <h3 id="Value">Value</h3>
 
-<p>A {{domxref('TimeRanges')}} object.</p>
+<p>A new static <a href="/en-US/docs/Web/API/TimeRanges#normalized_timeranges_objects">normalized TimeRanges object</a> that represents the ranges of the media resource, if any, that the user agent is able to seek to at the time <code>seekable</code> property is accessed.</p>
 
 <h2 id="Examples">Examples</h2>
 
@@ -49,19 +48,14 @@ <h2 id="Specifications">Specifications</h2>
       <th scope="col">Comment</th>
     </tr>
     <tr>
-      <td>{{SpecName('HTML WHATWG', "the-video-element.html#dom-media-seekable", "HTMLMediaElement")}}</td>
+      <td>{{SpecName('HTML WHATWG', "the-video-element.html#dom-media-seekable", "seekable")}}</td>
       <td>{{Spec2('HTML WHATWG')}}</td>
-      <td>No change from {{SpecName('HTML5 W3C')}}</td>
-    </tr>
-    <tr>
-      <td>{{SpecName('HTML5 W3C', "embedded-content-0.html#dom-media-seekable", "HTMLMediaElement")}}</td>
-      <td>{{Spec2('HTML5 W3C')}}</td>
-      <td>Initial definition.</td>
+      <td></td>
     </tr>
     <tr>
-      <td>{{SpecName('Media Source Extensions','#htmlmediaelement-extensions','HTMLMediaElement extensions, like for seekable')}}</td>
+      <td>{{SpecName('Media Source Extensions','#htmlmediaelement-extensions')}}</td>
       <td>{{Spec2('Media Source Extensions')}}</td>
-      <td>Specifies a new algorithm for returning the seekable time range of a media
+      <td>Specifies a new algorithm for returning the seekable time ranges of a media
         element whose source is a {{domxref("MediaSource")}} object.</td>
     </tr>
   </tbody>

diff --git a/files/en-us/web/api/timeranges/index.html b/files/en-us/web/api/timeranges/index.html
@@ -11,11 +11,15 @@
 ---
 <div>{{APIRef("DOM")}}</div>
 
-<p>The <code>TimeRanges</code> interface is used to represent a set of time ranges, primarily for the purpose of tracking which portions of media have been buffered when loading it for use by the {{HTMLElement("audio")}} and {{HTMLElement("video")}} elements.</p>
+<p>When loading a media resource for use by an {{HTMLElement("audio")}} or {{HTMLElement("video")}} element, the <strong><code>TimeRanges</code></strong> interface is used for representing the time ranges of the media resource that have been buffered, the time ranges that have been played, and the time ranges that are seekable.</p>
 
-<p>A <code>TimeRanges</code> object includes one or more ranges of time, each specified by a starting and ending time offset. You reference each time range by using the <code>start()</code> and <code>end()</code> methods, passing the index number of the time range you want to retrieve.</p>
+<p>A <code>TimeRanges</code> object includes one or more ranges of time, each specified by a starting time offset and an ending time offset. You reference each time range by using the <code>start()</code> and <code>end()</code> methods, passing the index number of the time range you want to retrieve.</p>
 
-<p>The term "<a href="https://www.w3.org/TR/html52/semantics-embedded-content.html#normalized-timeranges-object">normalized TimeRanges object</a>" indicates that ranges in such an object are ordered, don't overlap, aren't empty, and don't touch (adjacent ranges are folded into one bigger range).</p>
+<h2>Normalized TimeRanges objects</h2>
+
+<p>Several members of {{domxref("HTMLMediaElement")}} objects return a <strong>normalized TimeRanges object</strong> — which <a href="https://html.spec.whatwg.org/multipage/media.html#normalised-timeranges-object">the spec describes</a> as having the following characteristics:</p>
+
+<p><em>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).</em></p>
 
 <h2 id="Properties">Properties</h2>