[html5] r5751 - [e] (0) Add best-practices sections for media elements. Fixing http://www.w3.org [...]

whatwg at whatwg.org whatwg at whatwg.org
Fri Jan 7 15:30:34 PST 2011


Author: ianh
Date: 2011-01-07 15:30:33 -0800 (Fri, 07 Jan 2011)
New Revision: 5751

Modified:
   complete.html
   index
   source
Log:
[e] (0) Add best-practices sections for media elements.
Fixing http://www.w3.org/Bugs/Public/show_bug.cgi?id=11243

Modified: complete.html
===================================================================
--- complete.html	2011-01-07 22:47:49 UTC (rev 5750)
+++ complete.html	2011-01-07 23:30:33 UTC (rev 5751)
@@ -586,7 +586,9 @@
        <li><a href=#user-interface><span class=secno>4.8.10.12 </span>User interface</a></li>
        <li><a href=#time-ranges><span class=secno>4.8.10.13 </span>Time ranges</a></li>
        <li><a href=#mediaevents><span class=secno>4.8.10.14 </span>Event summary</a></li>
-       <li><a href=#security-and-privacy-considerations><span class=secno>4.8.10.15 </span>Security and privacy considerations</a></ol></li>
+       <li><a href=#security-and-privacy-considerations><span class=secno>4.8.10.15 </span>Security and privacy considerations</a></li>
+       <li><a href=#best-practices-for-authors-using-media-elements><span class=secno>4.8.10.16 </span>Best practices for authors using media elements</a></li>
+       <li><a href=#best-practices-for-implementors-of-media-elements><span class=secno>4.8.10.17 </span>Best practices for implementors of media elements</a></ol></li>
      <li><a href=#the-canvas-element><span class=secno>4.8.11 </span>The <code>canvas</code> element</a>
       <ol>
        <li><a href=#2dcontext><span class=secno>4.8.11.1 </span>The 2D context</a>
@@ -31248,6 +31250,80 @@
   </div>
 
 
+  <h5 id=best-practices-for-authors-using-media-elements><span class=secno>4.8.10.16 </span>Best practices for authors using media elements</h5>
+
+  <p><i>This section is non-normative.</i></p>
+
+  <p>Playing audio and video resources on small devices such as
+  set-top boxes or mobile phones is often constrained by limited
+  hardware resources in the device. For example, a device might only
+  support three simultaneous videos. For this reason, it is a good
+  practice to release resources held by <a href=#media-element title="media
+  element">media elements</a> when they are done playing, either by
+  being very careful about removing all references to the element and
+  allowing it to be garbage collected, or, even better, by removing
+  the element's <code title=attr-media-src><a href=#attr-media-src>src</a></code> attribute and
+  any <code><a href=#the-source-element>source</a></code> element descendants, and invoking the
+  element's <code title=dom-media-load><a href=#dom-media-load>load()</a></code> method.</p>
+
+
+  <div class=impl>
+
+  <h5 id=best-practices-for-implementors-of-media-elements><span class=secno>4.8.10.17 </span>Best practices for implementors of media elements</h5>
+
+  <p><i>This section is non-normative.</i></p>
+
+  <p>How accurately various aspects of the <a href=#media-element>media element</a>
+  API are implemented is considered a quality-of-implementation issue.</p>
+
+  <p>For example, when implementing the <code title=attr-media-buffered>buffered</code> attribute, how precise
+  an implementation reports the ranges that have been buffered depends
+  on how carefully the user agent inspects the data. Since the API
+  reports ranges as times, but the data is obtained in byte streams, a
+  user agent receiving a variable-bit-rate stream might only be able
+  to determine precise times by actually decoding all of the data.
+  User agents aren't required to do this, however; they can instead
+  return estimates (e.g. based on the average bit rate seen so far)
+  which get revised as more information becomes available.</p>
+
+  <p>As a general rule, user agents are urged to be conservative
+  rather than optimistic. For example, it would be bad to report that
+  everything had been buffered when it had not.</p>
+
+  <p>Another quality-of-implementation issue would be playing a video
+  backwards when the codec is designed only for forward playback (e.g.
+  there aren't many key frames, and they are far apart, and the
+  intervening frames only have deltas from the previous frame). User
+  agents could do a poor job, e.g. only showing key frames; however,
+  better implementations would do more work and thus do a better job,
+  e.g. actually decoding parts of the video forwards, storing the
+  complete frames, and then playing the frames backwards.</p>
+
+  <p>Similarly, while implementations are allowed to drop buffered
+  data at any time (there is no requirement that a user agent keep all
+  the media data obtained for the lifetime of the media element), it
+  is again a quality of implementation issue: user agents with
+  sufficient resources to keep all the data around are encouraged to
+  do so, as this allows for a better user experience. For example, if
+  the user is watching a live stream, a user agent could allow the
+  user only to view the live video; however, a better user agent would
+  buffer everything and allow the user to seek through the earlier
+  material, pause it, play it forwards and backwards, etc.</p>
+
+  <hr><p>When a <a href=#media-element>media element</a> that is paused is <a href=#remove-an-element-from-a-document title="remove an element from a document">removed from a
+  document</a> and not reinserted before the next time the
+  <a href=#event-loop>event loop</a> spins, implementations that are resource
+  constrained are encouraged to take that opportunity to release all
+  hardware resources (like video planes, networking resources, and
+  data buffers) used by the <a href=#media-element>media element</a>. (User agents
+  still have to keep track of the playback position and so forth,
+  though, in case playback is later restarted.)</p>
+
+  </div>
+  
+
+
+
   <h4 id=the-canvas-element><span class=secno>4.8.11 </span>The <dfn id=canvas><code>canvas</code></dfn> element</h4>
 
   <dl class=element><dt>Categories</dt>

Modified: index
===================================================================
--- index	2011-01-07 22:47:49 UTC (rev 5750)
+++ index	2011-01-07 23:30:33 UTC (rev 5751)
@@ -594,7 +594,9 @@
        <li><a href=#user-interface><span class=secno>4.8.10.12 </span>User interface</a></li>
        <li><a href=#time-ranges><span class=secno>4.8.10.13 </span>Time ranges</a></li>
        <li><a href=#mediaevents><span class=secno>4.8.10.14 </span>Event summary</a></li>
-       <li><a href=#security-and-privacy-considerations><span class=secno>4.8.10.15 </span>Security and privacy considerations</a></ol></li>
+       <li><a href=#security-and-privacy-considerations><span class=secno>4.8.10.15 </span>Security and privacy considerations</a></li>
+       <li><a href=#best-practices-for-authors-using-media-elements><span class=secno>4.8.10.16 </span>Best practices for authors using media elements</a></li>
+       <li><a href=#best-practices-for-implementors-of-media-elements><span class=secno>4.8.10.17 </span>Best practices for implementors of media elements</a></ol></li>
      <li><a href=#the-canvas-element><span class=secno>4.8.11 </span>The <code>canvas</code> element</a>
       <ol>
        <li><a href=#2dcontext><span class=secno>4.8.11.1 </span>The 2D context</a>
@@ -31230,6 +31232,80 @@
   </div>
 
 
+  <h5 id=best-practices-for-authors-using-media-elements><span class=secno>4.8.10.16 </span>Best practices for authors using media elements</h5>
+
+  <p><i>This section is non-normative.</i></p>
+
+  <p>Playing audio and video resources on small devices such as
+  set-top boxes or mobile phones is often constrained by limited
+  hardware resources in the device. For example, a device might only
+  support three simultaneous videos. For this reason, it is a good
+  practice to release resources held by <a href=#media-element title="media
+  element">media elements</a> when they are done playing, either by
+  being very careful about removing all references to the element and
+  allowing it to be garbage collected, or, even better, by removing
+  the element's <code title=attr-media-src><a href=#attr-media-src>src</a></code> attribute and
+  any <code><a href=#the-source-element>source</a></code> element descendants, and invoking the
+  element's <code title=dom-media-load><a href=#dom-media-load>load()</a></code> method.</p>
+
+
+  <div class=impl>
+
+  <h5 id=best-practices-for-implementors-of-media-elements><span class=secno>4.8.10.17 </span>Best practices for implementors of media elements</h5>
+
+  <p><i>This section is non-normative.</i></p>
+
+  <p>How accurately various aspects of the <a href=#media-element>media element</a>
+  API are implemented is considered a quality-of-implementation issue.</p>
+
+  <p>For example, when implementing the <code title=attr-media-buffered>buffered</code> attribute, how precise
+  an implementation reports the ranges that have been buffered depends
+  on how carefully the user agent inspects the data. Since the API
+  reports ranges as times, but the data is obtained in byte streams, a
+  user agent receiving a variable-bit-rate stream might only be able
+  to determine precise times by actually decoding all of the data.
+  User agents aren't required to do this, however; they can instead
+  return estimates (e.g. based on the average bit rate seen so far)
+  which get revised as more information becomes available.</p>
+
+  <p>As a general rule, user agents are urged to be conservative
+  rather than optimistic. For example, it would be bad to report that
+  everything had been buffered when it had not.</p>
+
+  <p>Another quality-of-implementation issue would be playing a video
+  backwards when the codec is designed only for forward playback (e.g.
+  there aren't many key frames, and they are far apart, and the
+  intervening frames only have deltas from the previous frame). User
+  agents could do a poor job, e.g. only showing key frames; however,
+  better implementations would do more work and thus do a better job,
+  e.g. actually decoding parts of the video forwards, storing the
+  complete frames, and then playing the frames backwards.</p>
+
+  <p>Similarly, while implementations are allowed to drop buffered
+  data at any time (there is no requirement that a user agent keep all
+  the media data obtained for the lifetime of the media element), it
+  is again a quality of implementation issue: user agents with
+  sufficient resources to keep all the data around are encouraged to
+  do so, as this allows for a better user experience. For example, if
+  the user is watching a live stream, a user agent could allow the
+  user only to view the live video; however, a better user agent would
+  buffer everything and allow the user to seek through the earlier
+  material, pause it, play it forwards and backwards, etc.</p>
+
+  <hr><p>When a <a href=#media-element>media element</a> that is paused is <a href=#remove-an-element-from-a-document title="remove an element from a document">removed from a
+  document</a> and not reinserted before the next time the
+  <a href=#event-loop>event loop</a> spins, implementations that are resource
+  constrained are encouraged to take that opportunity to release all
+  hardware resources (like video planes, networking resources, and
+  data buffers) used by the <a href=#media-element>media element</a>. (User agents
+  still have to keep track of the playback position and so forth,
+  though, in case playback is later restarted.)</p>
+
+  </div>
+  
+
+
+
   <h4 id=the-canvas-element><span class=secno>4.8.11 </span>The <dfn id=canvas><code>canvas</code></dfn> element</h4>
 
   <dl class=element><dt>Categories</dt>

Modified: source
===================================================================
--- source	2011-01-07 22:47:49 UTC (rev 5750)
+++ source	2011-01-07 23:30:33 UTC (rev 5751)
@@ -34280,6 +34280,84 @@
   </div>
 
 
+  <h5>Best practices for authors using media elements</h5>
+
+  <!--END dev-html--><p><i>This section is non-normative.</i></p><!--START dev-html-->
+
+  <p>Playing audio and video resources on small devices such as
+  set-top boxes or mobile phones is often constrained by limited
+  hardware resources in the device. For example, a device might only
+  support three simultaneous videos. For this reason, it is a good
+  practice to release resources held by <span title="media
+  element">media elements</span> when they are done playing, either by
+  being very careful about removing all references to the element and
+  allowing it to be garbage collected, or, even better, by removing
+  the element's <code title="attr-media-src">src</code> attribute and
+  any <code>source</code> element descendants, and invoking the
+  element's <code title="dom-media-load">load()</code> method.</p>
+
+
+  <div class="impl">
+
+  <h5>Best practices for implementors of media elements</h5>
+
+  <!--END dev-html--><p><i>This section is non-normative.</i></p><!--START dev-html-->
+
+  <p>How accurately various aspects of the <span>media element</span>
+  API are implemented is considered a quality-of-implementation issue.</p>
+
+  <p>For example, when implementing the <code
+  title="attr-media-buffered">buffered</code> attribute, how precise
+  an implementation reports the ranges that have been buffered depends
+  on how carefully the user agent inspects the data. Since the API
+  reports ranges as times, but the data is obtained in byte streams, a
+  user agent receiving a variable-bit-rate stream might only be able
+  to determine precise times by actually decoding all of the data.
+  User agents aren't required to do this, however; they can instead
+  return estimates (e.g. based on the average bit rate seen so far)
+  which get revised as more information becomes available.</p>
+
+  <p>As a general rule, user agents are urged to be conservative
+  rather than optimistic. For example, it would be bad to report that
+  everything had been buffered when it had not.</p>
+
+  <p>Another quality-of-implementation issue would be playing a video
+  backwards when the codec is designed only for forward playback (e.g.
+  there aren't many key frames, and they are far apart, and the
+  intervening frames only have deltas from the previous frame). User
+  agents could do a poor job, e.g. only showing key frames; however,
+  better implementations would do more work and thus do a better job,
+  e.g. actually decoding parts of the video forwards, storing the
+  complete frames, and then playing the frames backwards.</p>
+
+  <p>Similarly, while implementations are allowed to drop buffered
+  data at any time (there is no requirement that a user agent keep all
+  the media data obtained for the lifetime of the media element), it
+  is again a quality of implementation issue: user agents with
+  sufficient resources to keep all the data around are encouraged to
+  do so, as this allows for a better user experience. For example, if
+  the user is watching a live stream, a user agent could allow the
+  user only to view the live video; however, a better user agent would
+  buffer everything and allow the user to seek through the earlier
+  material, pause it, play it forwards and backwards, etc.</p>
+
+  <hr>
+
+  <p>When a <span>media element</span> that is paused is <span
+  title="remove an element from a document">removed from a
+  document</span> and not reinserted before the next time the
+  <span>event loop</span> spins, implementations that are resource
+  constrained are encouraged to take that opportunity to release all
+  hardware resources (like video planes, networking resources, and
+  data buffers) used by the <span>media element</span>. (User agents
+  still have to keep track of the playback position and so forth,
+  though, in case playback is later restarted.)</p>
+
+  </div>
+  
+
+
+
   <h4>The <dfn id="canvas"><code>canvas</code></dfn> element</h4>
 
   <dl class="element">




More information about the Commit-Watchers mailing list