[html5] r5310 - [agiow] (1) Define the Media Timeline for <video> -- the timeline along which cu [...]
whatwg at whatwg.org
whatwg at whatwg.org
Tue Aug 17 18:13:22 PDT 2010
Author: ianh
Date: 2010-08-17 18:13:20 -0700 (Tue, 17 Aug 2010)
New Revision: 5310
Modified:
complete.html
index
source
Log:
[agiow] (1) Define the Media Timeline for <video> -- the timeline along which currentTime, duration, etc, are defined.
Modified: complete.html
===================================================================
--- complete.html 2010-08-17 06:47:43 UTC (rev 5309)
+++ complete.html 2010-08-18 01:13:20 UTC (rev 5310)
@@ -209,7 +209,7 @@
<header class=head id=head><p><a class=logo href=http://www.whatwg.org/ rel=home><img alt=WHATWG src=/images/logo></a></p>
<hgroup><h1>Web Applications 1.0</h1>
- <h2 class="no-num no-toc">Draft Standard — 17 August 2010</h2>
+ <h2 class="no-num no-toc">Draft Standard — 18 August 2010</h2>
</hgroup><p>You can take part in this work. <a href=http://www.whatwg.org/mailing-list>Join the working group's discussion list.</a></p>
<p><strong>Web designers!</strong> We have a <a href=http://blog.whatwg.org/faq/>FAQ</a>, a <a href=http://forums.whatwg.org/>forum</a>, and a <a href=http://www.whatwg.org/mailing-list#help>help mailing list</a> for you!</p>
<!--<p class="impl"><strong>Implementors!</strong> We have a <a href="http://www.whatwg.org/mailing-list#implementors">mailing list</a> for you too!</p>-->
@@ -24090,8 +24090,9 @@
// playback state
attribute float <a href=#dom-media-currenttime title=dom-media-currentTime>currentTime</a>;
- readonly attribute float <a href=#dom-media-starttime title=dom-media-startTime>startTime</a>;
+ readonly attribute float <a href=#dom-media-initialtime title=dom-media-initialTime>initialTime</a>;
readonly attribute float <a href=#dom-media-duration title=dom-media-duration>duration</a>;
+ readonly attribute <span>Date</span> <a href=#dom-media-startoffsettime title=dom-media-startOffsetTime>startOffsetTime</a>;
readonly attribute boolean <a href=#dom-media-paused title=dom-media-paused>paused</a>;
attribute float <a href=#dom-media-defaultplaybackrate title=dom-media-defaultPlaybackRate>defaultPlaybackRate</a>;
attribute float <a href=#dom-media-playbackrate title=dom-media-playbackRate>playbackRate</a>;
@@ -24513,6 +24514,23 @@
<li><p>Set the <a href=#current-playback-position>current playback position</a> to
0.</li>
+ <li><p>Set the <a href=#initial-playback-position>initial playback position</a> to
+ 0.</li>
+
+ <li><p>Set the <a href=#timeline-offset>timeline offset</a> to Not-a-Number
+ (NaN).</li>
+
+ <li>
+
+ <p>Update the <code title=dom-media-duration><a href=#dom-media-duration>duration</a></code>
+ attribute to Not-a-Number (NaN).</p>
+
+ <p class=note>The user agent <a href=#durationChange>will
+ not</a> fire a <code title=event-media-durationchange><a href=#event-media-durationchange>durationchange</a></code> event
+ for this particular change of the duration.</p>
+
+ </li>
+
<li><p><a href=#queue-a-task>Queue a task</a> to <a href=#fire-a-simple-event>fire a simple
event</a> named <code title=event-media-emptied><a href=#event-media-emptied>emptied</a></code> at the <a href=#media-element>media
element</a>.</li>
@@ -24919,26 +24937,51 @@
<p>This indicates that the resource is usable. The user agent
must follow these substeps:</p>
- <ol><li><p>Set the <a href=#current-playback-position>current playback position</a> to the
- <a href=#earliest-possible-position>earliest possible position</a>.</li>
+ <ol><li>
- <li><p>Set the <code title=dom-media-readyState><a href=#dom-media-readystate>readyState</a></code> attribute to
- <code title=dom-media-HAVE_METADATA><a href=#dom-media-have_metadata>HAVE_METADATA</a></code>.</li>
+ <p><a href=#defineTimeline>Establish the media timeline</a> for the purposes
+ of the <a href=#current-playback-position>current playback position</a>, the
+ <a href=#earliest-possible-position>earliest possible position</a>, and the <a href=#initial-playback-position>initial
+ playback position</a>, based on the <a href=#media-data>media
+ data</a>.</p>
- <li><p>For <code><a href=#video>video</a></code> elements, set the <code title=dom-video-videoWidth><a href=#dom-video-videowidth>videoWidth</a></code> and <code title=dom-video-videoHeight><a href=#dom-video-videoheight>videoHeight</a></code>
- attributes.</li>
+ </li>
<li>
- <p>Set the <code title=dom-media-duration><a href=#dom-media-duration>duration</a></code>
- attribute to the duration of the resource.</p>
+ <p>Update the <a href=#timeline-offset>timeline offset</a> to the date and
+ time that corresponds to the zero time in the <a href=#media-timeline>media
+ timeline</a> established in the previous step, if any. If
+ no explicit time and date is given by the <a href=#media-resource>media
+ resource</a>, the <a href=#timeline-offset>timeline offset</a> must be set
+ to Not-a-Number (NaN).</p>
+ </li>
+
+ <li><p>Set the <a href=#current-playback-position>current playback position</a> to the
+ <a href=#earliest-possible-position>earliest possible position</a>.</li>
+
+ <li>
+
+ <p>Update the <code title=dom-media-duration><a href=#dom-media-duration>duration</a></code>
+ attribute with the time of the last frame of the resource, if
+ known, on the <a href=#media-timeline>media timeline</a> established above.
+ If it is not known (e.g. a stream that is in principle
+ infinite), update the <code title=dom-media-duration><a href=#dom-media-duration>duration</a></code> attribute to the
+ value positive Infinity.</p>
+
<p class=note>The user agent <a href=#durationChange>will</a> <a href=#queue-a-task>queue a task</a> to
<a href=#fire-a-simple-event>fire a simple event</a> named <code title=event-media-durationchange><a href=#event-media-durationchange>durationchange</a></code> at the
element at this point.</p>
</li>
+ <li><p>Set the <code title=dom-media-readyState><a href=#dom-media-readystate>readyState</a></code> attribute to
+ <code title=dom-media-HAVE_METADATA><a href=#dom-media-have_metadata>HAVE_METADATA</a></code>.</li>
+
+ <li><p>For <code><a href=#video>video</a></code> elements, set the <code title=dom-video-videoWidth><a href=#dom-video-videowidth>videoWidth</a></code> and <code title=dom-video-videoHeight><a href=#dom-video-videoheight>videoHeight</a></code>
+ attributes.</li>
+
<li id=fire-loadedmetadata>
<p><a href=#queue-a-task>Queue a task</a> to <a href=#fire-a-simple-event>fire a simple
@@ -24953,9 +24996,10 @@
<li>
- <p>If either the <a href=#media-resource>media resource</a> or the address
- of the <var title="">current media resource</var> indicate a
- particular start time, then <a href=#dom-media-seek title=dom-media-seek>seek</a> to that time. Ignore any
+ <p>If either the <a href=#media-resource>media resource</a> or the address of
+ the <var title="">current media resource</var> indicate a
+ particular start time, then set the <a href=#initial-playback-position>initial playback
+ position</a> to that time and then seek <a href=#dom-media-seek title=dom-media-seek>seek</a> to that time. Ignore any
resulting exceptions (if the position is out of range, it is
effectively ignored).</p>
@@ -25285,7 +25329,8 @@
<dd>
<p>Returns the length of the <a href=#media-resource>media resource</a>, in
- seconds.</p>
+ seconds, assuming that the start of the <a href=#media-resource>media
+ resource</a> is at time zero.</p>
<p>Returns NaN if the duration isn't available.<p>
@@ -25308,53 +25353,96 @@
</dd>
- <dt><var title="">media</var> . <code title=dom-media-startTime><a href=#dom-media-starttime>startTime</a></code></dt>
+ <dt><var title="">media</var> . <code title=dom-media-initialTime><a href=#dom-media-initialtime>initialTime</a></code></dt>
<dd>
- <p>Returns the <a href=#earliest-possible-position>earliest possible position</a>, in
- seconds. This is the time for the start of the current clip. It
- might not be zero if the clip's timeline is not zero-based, or if
- the resource is a streaming resource (in which case it gives the
- earliest time that the user agent is able to seek back to).</p>
+ <p>Returns the <a href=#initial-playback-position>initial playback position</a>, that is, time
+ to which the <a href=#media-resource>media resource</a> was automatically seeked
+ when it was loaded. Returns zero if the <a href=#initial-playback-position>initial playback
+ position</a> is still unknown.</p>
</dd>
</dl><div class=impl>
- <p>The <dfn id=dom-media-duration title=dom-media-duration><code>duration</code></dfn>
- attribute must return the length of the <a href=#media-resource>media resource</a>,
- in seconds. If no <a href=#media-data>media data</a> is available, then the
- attributes must return the Not-a-Number (NaN) value. If the
- <a href=#media-resource>media resource</a> is known to be unbounded (e.g. a
- streaming radio), then the attribute must return the positive
- Infinity value.</p>
+ <p>A <a href=#media-resource>media resource</a> has a <dfn id=media-timeline>media timeline</dfn>
+ that maps times (in seconds) to positions in the <a href=#media-resource>media
+ resource</a>. The origin of a timeline is its earliest defined
+ position. The duration of a timeline is its last defined
+ position.</p>
- <p>The user agent must determine the duration of the <a href=#media-resource>media
- resource</a> before playing any part of the <a href=#media-data>media
- data</a> and before setting <code title=dom-media-readyState><a href=#dom-media-readystate>readyState</a></code> to a value equal to
- or greater than <code title=dom-media-HAVE_METADATA><a href=#dom-media-have_metadata>HAVE_METADATA</a></code>, even if doing
- so requires seeking to multiple parts of the resource.</p>
+ <p><dfn id=defineTimeline title="establish the media
+ timeline">Establishing the media timeline</dfn>: If the <a href=#media-resource>media
+ resource</a> somehow specifies an explicit timeline whose origin
+ is not negative, then the <a href=#media-timeline>media timeline</a> should be that
+ timeline. (Whether the <a href=#media-resource>media resource</a> can specify a
+ timeline or not depends on the <a href=#media-resource title="media resource">media
+ resource's</a> format.) If the <a href=#media-resource>media resource</a>
+ specifies an explicit start time <em>and date</em>, then that time
+ and date should be considered the zero point in the <a href=#media-timeline>media
+ timeline</a>; the <a href=#timeline-offset>timeline offset</a> will be the time
+ and date, exposed using the <code title=dom-media-startOffsetTime><a href=#dom-media-startoffsettime>startOffsetTime</a></code>
+ attribute.</p>
- <p id=durationChange>When the length of the <a href=#media-resource>media
- resource</a> changes (e.g. from being unknown to known, or from a
- previously established length to a new length) the user agent must
- <a href=#queue-a-task>queue a task</a> to <a href=#fire-a-simple-event>fire a simple event</a> named
- <code title=event-media-durationchange><a href=#event-media-durationchange>durationchange</a></code> at the
- <a href=#media-element>media element</a>.</p>
+ <p>If the <a href=#media-resource>media resource</a> has a discontinuous timeline,
+ the user agent must extend the timeline used at the start of the
+ resource across the entire resource, so that the <a href=#media-timeline>media
+ timeline</a> of the <a href=#media-resource>media resource</a> increases
+ linearly starting from the <a href=#earliest-possible-position>earliest possible position</a>
+ (as defined below), even if the underlying <a href=#media-data>media data</a>
+ has out-of-order or even overlapping time codes.</p>
- <p class=example>If an "infinite" stream ends for some reason,
- then the duration would change from positive Infinity to the time of
- the last frame or sample in the stream, and the <code title=event-media-durationchange><a href=#event-media-durationchange>durationchange</a></code> event would be
- fired. Similarly, if the user agent initially estimated the
- <a href=#media-resource>media resource</a>'s duration instead of determining it
- precisely, and later revises the estimate based on new information,
- then the duration would change and the <code title=event-media-durationchange><a href=#event-media-durationchange>durationchange</a></code> event would be
- fired.</p>
+ <p class=example>For example, if two clips have been concatenated
+ into one video file, but the video format exposes the original times
+ for the two clips, the video data might expose a timeline that goes,
+ say, 00:15..00:29 and then 00:05..00:38. However, the user agent
+ would not expose those times; it would instead expose the times as
+ 00:15..00:29 and 00:29..01:02, as a single video.</p>
+ <p>In the absence of an explicit timeline, the zero time on the
+ <a href=#media-timeline>media timeline</a> should correspond to the first frame of
+ the <a href=#media-resource>media resource</a>. For static audio and video files
+ this is generally trivial. For streaming resources, if the user
+ agent will be able to seek to an earlier point than the first frame
+ originally provided by the server, then the zero time should
+ correspond to the earliest seekable time of the <a href=#media-resource>media
+ resource</a>; otherwise, it should correspond to the first frame
+ received from the server (the point in the <a href=#media-resource>media
+ resource</a> at which the user agent began receiving the
+ stream).</p>
+
+ <p class=example>Another example would be a stream that carries a
+ video with several concatenated fragments, broadcast by a server
+ that does not allow user agents to request specific times but
+ instead just streams the video data in a predetermined order. If a
+ user agent connects to this stream and receives fragments defined as
+ covering timestamps 2010-03-20 23:15:00 UTC to 2010-03-21 00:05:00
+ UTC and 2010-02-12 14:25:00 UTC to 2010-02-12 14:35:00 UTC, it would
+ expose this with a <a href=#media-timeline>media timeline</a> starting at 0s and
+ extending to 3,600s (one hour). Assuming the streaming server
+ disconnected at the end of the second clip, the <code title=dom-media-duration><a href=#dom-media-duration>duration</a></code> attribute would then
+ return 3,600. The <code title=dom-media-startOffsetTime><a href=#dom-media-startoffsettime>startOffsetTime</a></code> attribute
+ would return a <code>Date</code> object with a time corresponding to
+ 2010-03-20 23:15:00 UTC. However, if a different user agent
+ connected five minutes later, <em>it</em> would (presumably) receive
+ fragments covering timestamps 2010-03-20 23:20:00 UTC to 2010-03-21
+ 00:05:00 UTC and 2010-02-12 14:25:00 UTC to 2010-02-12 14:35:00 UTC,
+ and would expose this with a <a href=#media-timeline>media timeline</a> starting at
+ 0s and extending to 3,300s (fifty five minutes). In this case, the
+ <code title=dom-media-startOffsetTime><a href=#dom-media-startoffsettime>startOffsetTime</a></code>
+ attribute would return a <code>Date</code> object with a time
+ corresponding to 2010-03-20 23:20:00 UTC.</p>
+
+ <p>In any case, the user agent must ensure that the <a href=#earliest-possible-position>earliest
+ possible position</a> (as defined below) using the established
+ <a href=#media-timeline>media timeline</a>, is greater than or equal to zero.</p>
+
<p><a href=#media-element title="media element">Media elements</a> have a
- <dfn id=current-playback-position>current playback position</dfn>, which must initially be
- zero. The current position is a time.</p>
+ <dfn id=current-playback-position>current playback position</dfn>, which must initially (i.e. in
+ the absence of <a href=#media-data>media data</a>) be zero seconds. The
+ <a href=#current-playback-position>current playback position</a> is a time on the <a href=#media-timeline>media
+ timeline</a>.</p>
<p>The <dfn id=dom-media-currenttime title=dom-media-currentTime><code>currentTime</code></dfn>
attribute must, on getting, return the <a href=#current-playback-position>current playback
@@ -25362,16 +25450,30 @@
must <a href=#dom-media-seek title=dom-media-seek>seek</a> to the new value
(which might raise an exception).</p>
+ <p><a href=#media-element title="media element">Media elements</a> have an
+ <dfn id=initial-playback-position>initial playback position</dfn>, which must initially (i.e. in
+ the absence of <a href=#media-data>media data</a>) be zero seconds. The
+ <a href=#initial-playback-position>initial playback position</a> is updated when a <a href=#media-resource>media
+ resource</a> is loaded. The <a href=#initial-playback-position>initial playback
+ position</a> is a time on the <a href=#media-timeline>media timeline</a>.</p>
+
+ <p>The <dfn id=dom-media-initialtime title=dom-media-initialTime>initialTime<code></code></dfn>
+ attribute must, on getting, return the <a href=#initial-playback-position>initial playback
+ position</a>, expressed in seconds.</p>
+
<p>If the <a href=#media-resource>media resource</a> is a streaming resource, then
the user agent might be unable to obtain certain parts of the
- resource after it has expired from its buffer. Similarly, some <a href=#media-resource title="media resource">media resources</a> might have a timeline
- that doesn't start at zero. The <dfn id=earliest-possible-position>earliest possible
- position</dfn> is the earliest position in the stream or resource
- that the user agent can ever obtain again.</p>
+ resource after it has expired from its buffer. Similarly, some <a href=#media-resource title="media resource">media resources</a> might have a
+ <a href=#media-timeline>media timeline</a> that doesn't start at zero. The
+ <dfn id=earliest-possible-position>earliest possible position</dfn> is the earliest position in
+ the stream or resource that the user agent can ever obtain
+ again. It is also a time on the <a href=#media-timeline>media timeline</a>.</p>
- <p>The <dfn id=dom-media-starttime title=dom-media-startTime><code>startTime</code></dfn>
- attribute must, on getting, return the <a href=#earliest-possible-position>earliest possible
- position</a>, expressed in seconds.</p>
+ <p class=note>The <a href=#earliest-possible-position>earliest possible position</a> is not
+ explicitly exposed in the API; it corresponds to the start time of
+ the first range in the <code title=dom-media-seekable><a href=#dom-media-seekable>seekable</a></code> attribute's
+ <code><a href=#timeranges>TimeRanges</a></code> object, if any, or the <a href=#current-playback-position>current
+ playback position</a> otherwise.</p>
<p>When the <a href=#earliest-possible-position>earliest possible position</a> changes, then:
if the <a href=#current-playback-position>current playback position</a> is before the
@@ -25387,21 +25489,49 @@
known</a>, the <a href=#current-playback-position>current playback position</a> can never be
less than the <a href=#earliest-possible-position>earliest possible position</a>.</p>
- <p>User agents must act as if the timeline of the <a href=#media-resource>media
- resource</a> increases linearly starting from the <a href=#earliest-possible-position>earliest
- possible position</a>, even if the underlying <a href=#media-data>media
- data</a> has out-of-order or even overlapping time codes.</p>
+ <p>The <dfn id=dom-media-duration title=dom-media-duration><code>duration</code></dfn>
+ attribute must return the time of the end of the <a href=#media-resource>media
+ resource</a>, in seconds, on the <a href=#media-timeline>media timeline</a>. If
+ no <a href=#media-data>media data</a> is available, then the attributes must
+ return the Not-a-Number (NaN) value. If the <a href=#media-resource>media
+ resource</a> is known to be unbounded (e.g. a streaming radio),
+ then the attribute must return the positive Infinity value.</p>
- <p class=example>For example, if two clips have been concatenated
- into one video file, but the video format exposes the original times
- for the two clips, the video data might expose a timeline that goes,
- say, 00:15..00:29 and then 00:05..00:38. However, the user agent
- would not expose those times; it would instead expose the times as
- 00:15..00:29 and 00:29..01:02, as a single video.</p>
+ <p>The user agent must determine the duration of the <a href=#media-resource>media
+ resource</a> before playing any part of the <a href=#media-data>media
+ data</a> and before setting <code title=dom-media-readyState><a href=#dom-media-readystate>readyState</a></code> to a value equal to
+ or greater than <code title=dom-media-HAVE_METADATA><a href=#dom-media-have_metadata>HAVE_METADATA</a></code>, even if doing
+ so requires fetching multiple parts of the resource.</p>
+ <p id=durationChange>When the length of the <a href=#media-resource>media
+ resource</a> changes to a known value (e.g. from being unknown to
+ known, or from a previously established length to a new length) the
+ user agent must <a href=#queue-a-task>queue a task</a> to <a href=#fire-a-simple-event>fire a simple
+ event</a> named <code title=event-media-durationchange><a href=#event-media-durationchange>durationchange</a></code> at the
+ <a href=#media-element>media element</a>. (The event is not fired when the
+ duration is reset as part of loading a new media resource.)</p>
+
+ <p class=example>If an "infinite" stream ends for some reason,
+ then the duration would change from positive Infinity to the time of
+ the last frame or sample in the stream, and the <code title=event-media-durationchange><a href=#event-media-durationchange>durationchange</a></code> event would
+ be fired. Similarly, if the user agent initially estimated the
+ <a href=#media-resource>media resource</a>'s duration instead of determining it
+ precisely, and later revises the estimate based on new information,
+ then the duration would change and the <code title=event-media-durationchange><a href=#event-media-durationchange>durationchange</a></code> event would
+ be fired.</p>
+
+ <p>Some video files also have an explicit date and time
+ corresponding to the zero time in the <a href=#media-timeline>media timeline</a>,
+ known as the <dfn id=timeline-offset>timeline offset</dfn>. Initially, the
+ <a href=#timeline-offset>timeline offset</a> must be set to Not-a-Number (NaN).</p>
+
+ <p>The <dfn id=dom-media-startoffsettime title=dom-media-startOffsetTime><code>startOffsetTime</code></dfn>
+ attribute must return a new <code>Date</code> object representing
+ the current <a href=#timeline-offset>timeline offset</a>.</p>
+
</div>
- <p>The <dfn id=attr-media-loop title=attr-media-loop><code>loop</code></dfn>
+ <hr><p>The <dfn id=attr-media-loop title=attr-media-loop><code>loop</code></dfn>
attribute is a <a href=#boolean-attribute>boolean attribute</a> that, if specified,
indicates that the <a href=#media-element>media element</a> is to seek back to the
start of the <a href=#media-resource>media resource</a> upon reaching the end.</p>
@@ -26234,9 +26364,11 @@
<a href=#media-resource>media resource</a>, e.g. because it a simple movie file and
the user agent and the server support HTTP Range requests, then the
attribute would return an object with one range, whose start is the
- time of the first frame (typically zero), and whose end is the same
- as the time of the first frame plus the <code title=dom-media-duration><a href=#dom-media-duration>duration</a></code> attribute's value (which
- would equal the time of the last frame).</p>
+ time of the first frame (the <a href=#earliest-possible-position>earliest possible
+ position</a>, typically zero), and whose end is the same as the
+ time of the first frame plus the <code title=dom-media-duration><a href=#dom-media-duration>duration</a></code> attribute's value (which
+ would equal the time of the last frame, and might be positive
+ Infinity).</p>
<p class=note>The range might be continuously changing, e.g. if
the user agent is buffering a sliding window on an infinite
@@ -29304,8 +29436,8 @@
overlap, aren't empty, and don't touch (adjacent ranges are folded
into one bigger range).</p>
- <p>The timelines used by the objects returned by the <code title=dom-media-buffered><a href=#dom-media-buffered>buffered</a></code>, <code title=dom-media-seekable><a href=#dom-media-seekable>seekable</a></code> and <code title=dom-media-played><a href=#dom-media-played>played</a></code> IDL attributes of <a href=#media-element title="media element">media elements</a> must be the same as that
- element's <a href=#media-resource>media resource</a>'s timeline.</p>
+ <p>The timelines used by the objects returned by the <code title=dom-media-buffered><a href=#dom-media-buffered>buffered</a></code>, <code title=dom-media-seekable><a href=#dom-media-seekable>seekable</a></code> and <code title=dom-media-played><a href=#dom-media-played>played</a></code> IDL attributes of <a href=#media-element title="media element">media elements</a> must be that element's
+ <a href=#media-timeline>media timeline</a>.</p>
</div>
Modified: index
===================================================================
--- index 2010-08-17 06:47:43 UTC (rev 5309)
+++ index 2010-08-18 01:13:20 UTC (rev 5310)
@@ -213,7 +213,7 @@
<header class=head id=head><p><a class=logo href=http://www.whatwg.org/ rel=home><img alt=WHATWG src=/images/logo></a></p>
<hgroup><h1>HTML5 (including next generation additions still in development)</h1>
- <h2 class="no-num no-toc">Draft Standard — 17 August 2010</h2>
+ <h2 class="no-num no-toc">Draft Standard — 18 August 2010</h2>
</hgroup><p>You can take part in this work. <a href=http://www.whatwg.org/mailing-list>Join the working group's discussion list.</a></p>
<p><strong>Web designers!</strong> We have a <a href=http://blog.whatwg.org/faq/>FAQ</a>, a <a href=http://forums.whatwg.org/>forum</a>, and a <a href=http://www.whatwg.org/mailing-list#help>help mailing list</a> for you!</p>
<!--<p class="impl"><strong>Implementors!</strong> We have a <a href="http://www.whatwg.org/mailing-list#implementors">mailing list</a> for you too!</p>-->
@@ -24017,8 +24017,9 @@
// playback state
attribute float <a href=#dom-media-currenttime title=dom-media-currentTime>currentTime</a>;
- readonly attribute float <a href=#dom-media-starttime title=dom-media-startTime>startTime</a>;
+ readonly attribute float <a href=#dom-media-initialtime title=dom-media-initialTime>initialTime</a>;
readonly attribute float <a href=#dom-media-duration title=dom-media-duration>duration</a>;
+ readonly attribute <span>Date</span> <a href=#dom-media-startoffsettime title=dom-media-startOffsetTime>startOffsetTime</a>;
readonly attribute boolean <a href=#dom-media-paused title=dom-media-paused>paused</a>;
attribute float <a href=#dom-media-defaultplaybackrate title=dom-media-defaultPlaybackRate>defaultPlaybackRate</a>;
attribute float <a href=#dom-media-playbackrate title=dom-media-playbackRate>playbackRate</a>;
@@ -24440,6 +24441,23 @@
<li><p>Set the <a href=#current-playback-position>current playback position</a> to
0.</li>
+ <li><p>Set the <a href=#initial-playback-position>initial playback position</a> to
+ 0.</li>
+
+ <li><p>Set the <a href=#timeline-offset>timeline offset</a> to Not-a-Number
+ (NaN).</li>
+
+ <li>
+
+ <p>Update the <code title=dom-media-duration><a href=#dom-media-duration>duration</a></code>
+ attribute to Not-a-Number (NaN).</p>
+
+ <p class=note>The user agent <a href=#durationChange>will
+ not</a> fire a <code title=event-media-durationchange><a href=#event-media-durationchange>durationchange</a></code> event
+ for this particular change of the duration.</p>
+
+ </li>
+
<li><p><a href=#queue-a-task>Queue a task</a> to <a href=#fire-a-simple-event>fire a simple
event</a> named <code title=event-media-emptied><a href=#event-media-emptied>emptied</a></code> at the <a href=#media-element>media
element</a>.</li>
@@ -24846,26 +24864,51 @@
<p>This indicates that the resource is usable. The user agent
must follow these substeps:</p>
- <ol><li><p>Set the <a href=#current-playback-position>current playback position</a> to the
- <a href=#earliest-possible-position>earliest possible position</a>.</li>
+ <ol><li>
- <li><p>Set the <code title=dom-media-readyState><a href=#dom-media-readystate>readyState</a></code> attribute to
- <code title=dom-media-HAVE_METADATA><a href=#dom-media-have_metadata>HAVE_METADATA</a></code>.</li>
+ <p><a href=#defineTimeline>Establish the media timeline</a> for the purposes
+ of the <a href=#current-playback-position>current playback position</a>, the
+ <a href=#earliest-possible-position>earliest possible position</a>, and the <a href=#initial-playback-position>initial
+ playback position</a>, based on the <a href=#media-data>media
+ data</a>.</p>
- <li><p>For <code><a href=#video>video</a></code> elements, set the <code title=dom-video-videoWidth><a href=#dom-video-videowidth>videoWidth</a></code> and <code title=dom-video-videoHeight><a href=#dom-video-videoheight>videoHeight</a></code>
- attributes.</li>
+ </li>
<li>
- <p>Set the <code title=dom-media-duration><a href=#dom-media-duration>duration</a></code>
- attribute to the duration of the resource.</p>
+ <p>Update the <a href=#timeline-offset>timeline offset</a> to the date and
+ time that corresponds to the zero time in the <a href=#media-timeline>media
+ timeline</a> established in the previous step, if any. If
+ no explicit time and date is given by the <a href=#media-resource>media
+ resource</a>, the <a href=#timeline-offset>timeline offset</a> must be set
+ to Not-a-Number (NaN).</p>
+ </li>
+
+ <li><p>Set the <a href=#current-playback-position>current playback position</a> to the
+ <a href=#earliest-possible-position>earliest possible position</a>.</li>
+
+ <li>
+
+ <p>Update the <code title=dom-media-duration><a href=#dom-media-duration>duration</a></code>
+ attribute with the time of the last frame of the resource, if
+ known, on the <a href=#media-timeline>media timeline</a> established above.
+ If it is not known (e.g. a stream that is in principle
+ infinite), update the <code title=dom-media-duration><a href=#dom-media-duration>duration</a></code> attribute to the
+ value positive Infinity.</p>
+
<p class=note>The user agent <a href=#durationChange>will</a> <a href=#queue-a-task>queue a task</a> to
<a href=#fire-a-simple-event>fire a simple event</a> named <code title=event-media-durationchange><a href=#event-media-durationchange>durationchange</a></code> at the
element at this point.</p>
</li>
+ <li><p>Set the <code title=dom-media-readyState><a href=#dom-media-readystate>readyState</a></code> attribute to
+ <code title=dom-media-HAVE_METADATA><a href=#dom-media-have_metadata>HAVE_METADATA</a></code>.</li>
+
+ <li><p>For <code><a href=#video>video</a></code> elements, set the <code title=dom-video-videoWidth><a href=#dom-video-videowidth>videoWidth</a></code> and <code title=dom-video-videoHeight><a href=#dom-video-videoheight>videoHeight</a></code>
+ attributes.</li>
+
<li id=fire-loadedmetadata>
<p><a href=#queue-a-task>Queue a task</a> to <a href=#fire-a-simple-event>fire a simple
@@ -24880,9 +24923,10 @@
<li>
- <p>If either the <a href=#media-resource>media resource</a> or the address
- of the <var title="">current media resource</var> indicate a
- particular start time, then <a href=#dom-media-seek title=dom-media-seek>seek</a> to that time. Ignore any
+ <p>If either the <a href=#media-resource>media resource</a> or the address of
+ the <var title="">current media resource</var> indicate a
+ particular start time, then set the <a href=#initial-playback-position>initial playback
+ position</a> to that time and then seek <a href=#dom-media-seek title=dom-media-seek>seek</a> to that time. Ignore any
resulting exceptions (if the position is out of range, it is
effectively ignored).</p>
@@ -25212,7 +25256,8 @@
<dd>
<p>Returns the length of the <a href=#media-resource>media resource</a>, in
- seconds.</p>
+ seconds, assuming that the start of the <a href=#media-resource>media
+ resource</a> is at time zero.</p>
<p>Returns NaN if the duration isn't available.<p>
@@ -25235,53 +25280,96 @@
</dd>
- <dt><var title="">media</var> . <code title=dom-media-startTime><a href=#dom-media-starttime>startTime</a></code></dt>
+ <dt><var title="">media</var> . <code title=dom-media-initialTime><a href=#dom-media-initialtime>initialTime</a></code></dt>
<dd>
- <p>Returns the <a href=#earliest-possible-position>earliest possible position</a>, in
- seconds. This is the time for the start of the current clip. It
- might not be zero if the clip's timeline is not zero-based, or if
- the resource is a streaming resource (in which case it gives the
- earliest time that the user agent is able to seek back to).</p>
+ <p>Returns the <a href=#initial-playback-position>initial playback position</a>, that is, time
+ to which the <a href=#media-resource>media resource</a> was automatically seeked
+ when it was loaded. Returns zero if the <a href=#initial-playback-position>initial playback
+ position</a> is still unknown.</p>
</dd>
</dl><div class=impl>
- <p>The <dfn id=dom-media-duration title=dom-media-duration><code>duration</code></dfn>
- attribute must return the length of the <a href=#media-resource>media resource</a>,
- in seconds. If no <a href=#media-data>media data</a> is available, then the
- attributes must return the Not-a-Number (NaN) value. If the
- <a href=#media-resource>media resource</a> is known to be unbounded (e.g. a
- streaming radio), then the attribute must return the positive
- Infinity value.</p>
+ <p>A <a href=#media-resource>media resource</a> has a <dfn id=media-timeline>media timeline</dfn>
+ that maps times (in seconds) to positions in the <a href=#media-resource>media
+ resource</a>. The origin of a timeline is its earliest defined
+ position. The duration of a timeline is its last defined
+ position.</p>
- <p>The user agent must determine the duration of the <a href=#media-resource>media
- resource</a> before playing any part of the <a href=#media-data>media
- data</a> and before setting <code title=dom-media-readyState><a href=#dom-media-readystate>readyState</a></code> to a value equal to
- or greater than <code title=dom-media-HAVE_METADATA><a href=#dom-media-have_metadata>HAVE_METADATA</a></code>, even if doing
- so requires seeking to multiple parts of the resource.</p>
+ <p><dfn id=defineTimeline title="establish the media
+ timeline">Establishing the media timeline</dfn>: If the <a href=#media-resource>media
+ resource</a> somehow specifies an explicit timeline whose origin
+ is not negative, then the <a href=#media-timeline>media timeline</a> should be that
+ timeline. (Whether the <a href=#media-resource>media resource</a> can specify a
+ timeline or not depends on the <a href=#media-resource title="media resource">media
+ resource's</a> format.) If the <a href=#media-resource>media resource</a>
+ specifies an explicit start time <em>and date</em>, then that time
+ and date should be considered the zero point in the <a href=#media-timeline>media
+ timeline</a>; the <a href=#timeline-offset>timeline offset</a> will be the time
+ and date, exposed using the <code title=dom-media-startOffsetTime><a href=#dom-media-startoffsettime>startOffsetTime</a></code>
+ attribute.</p>
- <p id=durationChange>When the length of the <a href=#media-resource>media
- resource</a> changes (e.g. from being unknown to known, or from a
- previously established length to a new length) the user agent must
- <a href=#queue-a-task>queue a task</a> to <a href=#fire-a-simple-event>fire a simple event</a> named
- <code title=event-media-durationchange><a href=#event-media-durationchange>durationchange</a></code> at the
- <a href=#media-element>media element</a>.</p>
+ <p>If the <a href=#media-resource>media resource</a> has a discontinuous timeline,
+ the user agent must extend the timeline used at the start of the
+ resource across the entire resource, so that the <a href=#media-timeline>media
+ timeline</a> of the <a href=#media-resource>media resource</a> increases
+ linearly starting from the <a href=#earliest-possible-position>earliest possible position</a>
+ (as defined below), even if the underlying <a href=#media-data>media data</a>
+ has out-of-order or even overlapping time codes.</p>
- <p class=example>If an "infinite" stream ends for some reason,
- then the duration would change from positive Infinity to the time of
- the last frame or sample in the stream, and the <code title=event-media-durationchange><a href=#event-media-durationchange>durationchange</a></code> event would be
- fired. Similarly, if the user agent initially estimated the
- <a href=#media-resource>media resource</a>'s duration instead of determining it
- precisely, and later revises the estimate based on new information,
- then the duration would change and the <code title=event-media-durationchange><a href=#event-media-durationchange>durationchange</a></code> event would be
- fired.</p>
+ <p class=example>For example, if two clips have been concatenated
+ into one video file, but the video format exposes the original times
+ for the two clips, the video data might expose a timeline that goes,
+ say, 00:15..00:29 and then 00:05..00:38. However, the user agent
+ would not expose those times; it would instead expose the times as
+ 00:15..00:29 and 00:29..01:02, as a single video.</p>
+ <p>In the absence of an explicit timeline, the zero time on the
+ <a href=#media-timeline>media timeline</a> should correspond to the first frame of
+ the <a href=#media-resource>media resource</a>. For static audio and video files
+ this is generally trivial. For streaming resources, if the user
+ agent will be able to seek to an earlier point than the first frame
+ originally provided by the server, then the zero time should
+ correspond to the earliest seekable time of the <a href=#media-resource>media
+ resource</a>; otherwise, it should correspond to the first frame
+ received from the server (the point in the <a href=#media-resource>media
+ resource</a> at which the user agent began receiving the
+ stream).</p>
+
+ <p class=example>Another example would be a stream that carries a
+ video with several concatenated fragments, broadcast by a server
+ that does not allow user agents to request specific times but
+ instead just streams the video data in a predetermined order. If a
+ user agent connects to this stream and receives fragments defined as
+ covering timestamps 2010-03-20 23:15:00 UTC to 2010-03-21 00:05:00
+ UTC and 2010-02-12 14:25:00 UTC to 2010-02-12 14:35:00 UTC, it would
+ expose this with a <a href=#media-timeline>media timeline</a> starting at 0s and
+ extending to 3,600s (one hour). Assuming the streaming server
+ disconnected at the end of the second clip, the <code title=dom-media-duration><a href=#dom-media-duration>duration</a></code> attribute would then
+ return 3,600. The <code title=dom-media-startOffsetTime><a href=#dom-media-startoffsettime>startOffsetTime</a></code> attribute
+ would return a <code>Date</code> object with a time corresponding to
+ 2010-03-20 23:15:00 UTC. However, if a different user agent
+ connected five minutes later, <em>it</em> would (presumably) receive
+ fragments covering timestamps 2010-03-20 23:20:00 UTC to 2010-03-21
+ 00:05:00 UTC and 2010-02-12 14:25:00 UTC to 2010-02-12 14:35:00 UTC,
+ and would expose this with a <a href=#media-timeline>media timeline</a> starting at
+ 0s and extending to 3,300s (fifty five minutes). In this case, the
+ <code title=dom-media-startOffsetTime><a href=#dom-media-startoffsettime>startOffsetTime</a></code>
+ attribute would return a <code>Date</code> object with a time
+ corresponding to 2010-03-20 23:20:00 UTC.</p>
+
+ <p>In any case, the user agent must ensure that the <a href=#earliest-possible-position>earliest
+ possible position</a> (as defined below) using the established
+ <a href=#media-timeline>media timeline</a>, is greater than or equal to zero.</p>
+
<p><a href=#media-element title="media element">Media elements</a> have a
- <dfn id=current-playback-position>current playback position</dfn>, which must initially be
- zero. The current position is a time.</p>
+ <dfn id=current-playback-position>current playback position</dfn>, which must initially (i.e. in
+ the absence of <a href=#media-data>media data</a>) be zero seconds. The
+ <a href=#current-playback-position>current playback position</a> is a time on the <a href=#media-timeline>media
+ timeline</a>.</p>
<p>The <dfn id=dom-media-currenttime title=dom-media-currentTime><code>currentTime</code></dfn>
attribute must, on getting, return the <a href=#current-playback-position>current playback
@@ -25289,16 +25377,30 @@
must <a href=#dom-media-seek title=dom-media-seek>seek</a> to the new value
(which might raise an exception).</p>
+ <p><a href=#media-element title="media element">Media elements</a> have an
+ <dfn id=initial-playback-position>initial playback position</dfn>, which must initially (i.e. in
+ the absence of <a href=#media-data>media data</a>) be zero seconds. The
+ <a href=#initial-playback-position>initial playback position</a> is updated when a <a href=#media-resource>media
+ resource</a> is loaded. The <a href=#initial-playback-position>initial playback
+ position</a> is a time on the <a href=#media-timeline>media timeline</a>.</p>
+
+ <p>The <dfn id=dom-media-initialtime title=dom-media-initialTime>initialTime<code></code></dfn>
+ attribute must, on getting, return the <a href=#initial-playback-position>initial playback
+ position</a>, expressed in seconds.</p>
+
<p>If the <a href=#media-resource>media resource</a> is a streaming resource, then
the user agent might be unable to obtain certain parts of the
- resource after it has expired from its buffer. Similarly, some <a href=#media-resource title="media resource">media resources</a> might have a timeline
- that doesn't start at zero. The <dfn id=earliest-possible-position>earliest possible
- position</dfn> is the earliest position in the stream or resource
- that the user agent can ever obtain again.</p>
+ resource after it has expired from its buffer. Similarly, some <a href=#media-resource title="media resource">media resources</a> might have a
+ <a href=#media-timeline>media timeline</a> that doesn't start at zero. The
+ <dfn id=earliest-possible-position>earliest possible position</dfn> is the earliest position in
+ the stream or resource that the user agent can ever obtain
+ again. It is also a time on the <a href=#media-timeline>media timeline</a>.</p>
- <p>The <dfn id=dom-media-starttime title=dom-media-startTime><code>startTime</code></dfn>
- attribute must, on getting, return the <a href=#earliest-possible-position>earliest possible
- position</a>, expressed in seconds.</p>
+ <p class=note>The <a href=#earliest-possible-position>earliest possible position</a> is not
+ explicitly exposed in the API; it corresponds to the start time of
+ the first range in the <code title=dom-media-seekable><a href=#dom-media-seekable>seekable</a></code> attribute's
+ <code><a href=#timeranges>TimeRanges</a></code> object, if any, or the <a href=#current-playback-position>current
+ playback position</a> otherwise.</p>
<p>When the <a href=#earliest-possible-position>earliest possible position</a> changes, then:
if the <a href=#current-playback-position>current playback position</a> is before the
@@ -25314,21 +25416,49 @@
known</a>, the <a href=#current-playback-position>current playback position</a> can never be
less than the <a href=#earliest-possible-position>earliest possible position</a>.</p>
- <p>User agents must act as if the timeline of the <a href=#media-resource>media
- resource</a> increases linearly starting from the <a href=#earliest-possible-position>earliest
- possible position</a>, even if the underlying <a href=#media-data>media
- data</a> has out-of-order or even overlapping time codes.</p>
+ <p>The <dfn id=dom-media-duration title=dom-media-duration><code>duration</code></dfn>
+ attribute must return the time of the end of the <a href=#media-resource>media
+ resource</a>, in seconds, on the <a href=#media-timeline>media timeline</a>. If
+ no <a href=#media-data>media data</a> is available, then the attributes must
+ return the Not-a-Number (NaN) value. If the <a href=#media-resource>media
+ resource</a> is known to be unbounded (e.g. a streaming radio),
+ then the attribute must return the positive Infinity value.</p>
- <p class=example>For example, if two clips have been concatenated
- into one video file, but the video format exposes the original times
- for the two clips, the video data might expose a timeline that goes,
- say, 00:15..00:29 and then 00:05..00:38. However, the user agent
- would not expose those times; it would instead expose the times as
- 00:15..00:29 and 00:29..01:02, as a single video.</p>
+ <p>The user agent must determine the duration of the <a href=#media-resource>media
+ resource</a> before playing any part of the <a href=#media-data>media
+ data</a> and before setting <code title=dom-media-readyState><a href=#dom-media-readystate>readyState</a></code> to a value equal to
+ or greater than <code title=dom-media-HAVE_METADATA><a href=#dom-media-have_metadata>HAVE_METADATA</a></code>, even if doing
+ so requires fetching multiple parts of the resource.</p>
+ <p id=durationChange>When the length of the <a href=#media-resource>media
+ resource</a> changes to a known value (e.g. from being unknown to
+ known, or from a previously established length to a new length) the
+ user agent must <a href=#queue-a-task>queue a task</a> to <a href=#fire-a-simple-event>fire a simple
+ event</a> named <code title=event-media-durationchange><a href=#event-media-durationchange>durationchange</a></code> at the
+ <a href=#media-element>media element</a>. (The event is not fired when the
+ duration is reset as part of loading a new media resource.)</p>
+
+ <p class=example>If an "infinite" stream ends for some reason,
+ then the duration would change from positive Infinity to the time of
+ the last frame or sample in the stream, and the <code title=event-media-durationchange><a href=#event-media-durationchange>durationchange</a></code> event would
+ be fired. Similarly, if the user agent initially estimated the
+ <a href=#media-resource>media resource</a>'s duration instead of determining it
+ precisely, and later revises the estimate based on new information,
+ then the duration would change and the <code title=event-media-durationchange><a href=#event-media-durationchange>durationchange</a></code> event would
+ be fired.</p>
+
+ <p>Some video files also have an explicit date and time
+ corresponding to the zero time in the <a href=#media-timeline>media timeline</a>,
+ known as the <dfn id=timeline-offset>timeline offset</dfn>. Initially, the
+ <a href=#timeline-offset>timeline offset</a> must be set to Not-a-Number (NaN).</p>
+
+ <p>The <dfn id=dom-media-startoffsettime title=dom-media-startOffsetTime><code>startOffsetTime</code></dfn>
+ attribute must return a new <code>Date</code> object representing
+ the current <a href=#timeline-offset>timeline offset</a>.</p>
+
</div>
- <p>The <dfn id=attr-media-loop title=attr-media-loop><code>loop</code></dfn>
+ <hr><p>The <dfn id=attr-media-loop title=attr-media-loop><code>loop</code></dfn>
attribute is a <a href=#boolean-attribute>boolean attribute</a> that, if specified,
indicates that the <a href=#media-element>media element</a> is to seek back to the
start of the <a href=#media-resource>media resource</a> upon reaching the end.</p>
@@ -26161,9 +26291,11 @@
<a href=#media-resource>media resource</a>, e.g. because it a simple movie file and
the user agent and the server support HTTP Range requests, then the
attribute would return an object with one range, whose start is the
- time of the first frame (typically zero), and whose end is the same
- as the time of the first frame plus the <code title=dom-media-duration><a href=#dom-media-duration>duration</a></code> attribute's value (which
- would equal the time of the last frame).</p>
+ time of the first frame (the <a href=#earliest-possible-position>earliest possible
+ position</a>, typically zero), and whose end is the same as the
+ time of the first frame plus the <code title=dom-media-duration><a href=#dom-media-duration>duration</a></code> attribute's value (which
+ would equal the time of the last frame, and might be positive
+ Infinity).</p>
<p class=note>The range might be continuously changing, e.g. if
the user agent is buffering a sliding window on an infinite
@@ -29231,8 +29363,8 @@
overlap, aren't empty, and don't touch (adjacent ranges are folded
into one bigger range).</p>
- <p>The timelines used by the objects returned by the <code title=dom-media-buffered><a href=#dom-media-buffered>buffered</a></code>, <code title=dom-media-seekable><a href=#dom-media-seekable>seekable</a></code> and <code title=dom-media-played><a href=#dom-media-played>played</a></code> IDL attributes of <a href=#media-element title="media element">media elements</a> must be the same as that
- element's <a href=#media-resource>media resource</a>'s timeline.</p>
+ <p>The timelines used by the objects returned by the <code title=dom-media-buffered><a href=#dom-media-buffered>buffered</a></code>, <code title=dom-media-seekable><a href=#dom-media-seekable>seekable</a></code> and <code title=dom-media-played><a href=#dom-media-played>played</a></code> IDL attributes of <a href=#media-element title="media element">media elements</a> must be that element's
+ <a href=#media-timeline>media timeline</a>.</p>
</div>
Modified: source
===================================================================
--- source 2010-08-17 06:47:43 UTC (rev 5309)
+++ source 2010-08-18 01:13:20 UTC (rev 5310)
@@ -25802,8 +25802,9 @@
// playback state
attribute float <span title="dom-media-currentTime">currentTime</span>;
- readonly attribute float <span title="dom-media-startTime">startTime</span>;
+ readonly attribute float <span title="dom-media-initialTime">initialTime</span>;
readonly attribute float <span title="dom-media-duration">duration</span>;
+ readonly attribute <span>Date</span> <span title="dom-media-startOffsetTime">startOffsetTime</span>;
readonly attribute boolean <span title="dom-media-paused">paused</span>;
attribute float <span title="dom-media-defaultPlaybackRate">defaultPlaybackRate</span>;
attribute float <span title="dom-media-playbackRate">playbackRate</span>;
@@ -26296,6 +26297,24 @@
<li><p>Set the <span>current playback position</span> to
0.</p></li>
+ <li><p>Set the <span>initial playback position</span> to
+ 0.</p></li>
+
+ <li><p>Set the <span>timeline offset</span> to Not-a-Number
+ (NaN).</p></li>
+
+ <li>
+
+ <p>Update the <code title="dom-media-duration">duration</code>
+ attribute to Not-a-Number (NaN).</p>
+
+ <p class="note">The user agent <a href="#durationChange">will
+ not</a> fire a <code
+ title="event-media-durationchange">durationchange</code> event
+ for this particular change of the duration.</p>
+
+ </li>
+
<li><p><span>Queue a task</span> to <span>fire a simple
event</span> named <code
title="event-media-emptied">emptied</code> at the <span>media
@@ -26802,24 +26821,40 @@
<ol>
- <li><p>Set the <span>current playback position</span> to the
- <span>earliest possible position</span>.</p></li>
+ <li>
- <li><p>Set the <code
- title="dom-media-readyState">readyState</code> attribute to
- <code
- title="dom-media-HAVE_METADATA">HAVE_METADATA</code>.</p></li>
+ <p><span>Establish the media timeline</span> for the purposes
+ of the <span>current playback position</span>, the
+ <span>earliest possible position</span>, and the <span>initial
+ playback position</span>, based on the <span>media
+ data</span>.</p>
- <li><p>For <code>video</code> elements, set the <code
- title="dom-video-videoWidth">videoWidth</code> and <code
- title="dom-video-videoHeight">videoHeight</code>
- attributes.</p></li>
+ </li>
<li>
- <p>Set the <code title="dom-media-duration">duration</code>
- attribute to the duration of the resource.</p>
+ <p>Update the <span>timeline offset</span> to the date and
+ time that corresponds to the zero time in the <span>media
+ timeline</span> established in the previous step, if any. If
+ no explicit time and date is given by the <span>media
+ resource</span>, the <span>timeline offset</span> must be set
+ to Not-a-Number (NaN).</p>
+ </li>
+
+ <li><p>Set the <span>current playback position</span> to the
+ <span>earliest possible position</span>.</p></li>
+
+ <li>
+
+ <p>Update the <code title="dom-media-duration">duration</code>
+ attribute with the time of the last frame of the resource, if
+ known, on the <span>media timeline</span> established above.
+ If it is not known (e.g. a stream that is in principle
+ infinite), update the <code
+ title="dom-media-duration">duration</code> attribute to the
+ value positive Infinity.</p>
+
<p class="note">The user agent <a
href="#durationChange">will</a> <span>queue a task</span> to
<span>fire a simple event</span> named <code
@@ -26828,6 +26863,16 @@
</li>
+ <li><p>Set the <code
+ title="dom-media-readyState">readyState</code> attribute to
+ <code
+ title="dom-media-HAVE_METADATA">HAVE_METADATA</code>.</p></li>
+
+ <li><p>For <code>video</code> elements, set the <code
+ title="dom-video-videoWidth">videoWidth</code> and <code
+ title="dom-video-videoHeight">videoHeight</code>
+ attributes.</p></li>
+
<li id="fire-loadedmetadata">
<p><span>Queue a task</span> to <span>fire a simple
@@ -26843,9 +26888,10 @@
<li>
- <p>If either the <span>media resource</span> or the address
- of the <var title="">current media resource</var> indicate a
- particular start time, then <span
+ <p>If either the <span>media resource</span> or the address of
+ the <var title="">current media resource</var> indicate a
+ particular start time, then set the <span>initial playback
+ position</span> to that time and then seek <span
title="dom-media-seek">seek</span> to that time. Ignore any
resulting exceptions (if the position is out of range, it is
effectively ignored).</p>
@@ -27255,7 +27301,8 @@
<dd>
<p>Returns the length of the <span>media resource</span>, in
- seconds.</p>
+ seconds, assuming that the start of the <span>media
+ resource</span> is at time zero.</p>
<p>Returns NaN if the duration isn't available.<p>
@@ -27278,15 +27325,14 @@
</dd>
- <dt><var title="">media</var> . <code title="dom-media-startTime">startTime</code></dt>
+ <dt><var title="">media</var> . <code title="dom-media-initialTime">initialTime</code></dt>
<dd>
- <p>Returns the <span>earliest possible position</span>, in
- seconds. This is the time for the start of the current clip. It
- might not be zero if the clip's timeline is not zero-based, or if
- the resource is a streaming resource (in which case it gives the
- earliest time that the user agent is able to seek back to).</p>
+ <p>Returns the <span>initial playback position</span>, that is, time
+ to which the <span>media resource</span> was automatically seeked
+ when it was loaded. Returns zero if the <span>initial playback
+ position</span> is still unknown.</p>
</dd>
@@ -27294,43 +27340,86 @@
<div class="impl">
- <p>The <dfn title="dom-media-duration"><code>duration</code></dfn>
- attribute must return the length of the <span>media resource</span>,
- in seconds. If no <span>media data</span> is available, then the
- attributes must return the Not-a-Number (NaN) value. If the
- <span>media resource</span> is known to be unbounded (e.g. a
- streaming radio), then the attribute must return the positive
- Infinity value.</p>
+ <p>A <span>media resource</span> has a <dfn>media timeline</dfn>
+ that maps times (in seconds) to positions in the <span>media
+ resource</span>. The origin of a timeline is its earliest defined
+ position. The duration of a timeline is its last defined
+ position.</p>
- <p>The user agent must determine the duration of the <span>media
- resource</span> before playing any part of the <span>media
- data</span> and before setting <code
- title="dom-media-readyState">readyState</code> to a value equal to
- or greater than <code
- title="dom-media-HAVE_METADATA">HAVE_METADATA</code>, even if doing
- so requires seeking to multiple parts of the resource.</p>
+ <p><dfn id="defineTimeline" title="establish the media
+ timeline">Establishing the media timeline</dfn>: If the <span>media
+ resource</span> somehow specifies an explicit timeline whose origin
+ is not negative, then the <span>media timeline</span> should be that
+ timeline. (Whether the <span>media resource</span> can specify a
+ timeline or not depends on the <span title="media resource">media
+ resource's</span> format.) If the <span>media resource</span>
+ specifies an explicit start time <em>and date</em>, then that time
+ and date should be considered the zero point in the <span>media
+ timeline</span>; the <span>timeline offset</span> will be the time
+ and date, exposed using the <code
+ title="dom-media-startOffsetTime">startOffsetTime</code>
+ attribute.</p>
- <p id="durationChange">When the length of the <span>media
- resource</span> changes (e.g. from being unknown to known, or from a
- previously established length to a new length) the user agent must
- <span>queue a task</span> to <span>fire a simple event</span> named
- <code title="event-media-durationchange">durationchange</code> at the
- <span>media element</span>.</p>
+ <p>If the <span>media resource</span> has a discontinuous timeline,
+ the user agent must extend the timeline used at the start of the
+ resource across the entire resource, so that the <span>media
+ timeline</span> of the <span>media resource</span> increases
+ linearly starting from the <span>earliest possible position</span>
+ (as defined below), even if the underlying <span>media data</span>
+ has out-of-order or even overlapping time codes.</p>
- <p class="example">If an "infinite" stream ends for some reason,
- then the duration would change from positive Infinity to the time of
- the last frame or sample in the stream, and the <code
- title="event-media-durationchange">durationchange</code> event would be
- fired. Similarly, if the user agent initially estimated the
- <span>media resource</span>'s duration instead of determining it
- precisely, and later revises the estimate based on new information,
- then the duration would change and the <code
- title="event-media-durationchange">durationchange</code> event would be
- fired.</p>
+ <p class="example">For example, if two clips have been concatenated
+ into one video file, but the video format exposes the original times
+ for the two clips, the video data might expose a timeline that goes,
+ say, 00:15..00:29 and then 00:05..00:38. However, the user agent
+ would not expose those times; it would instead expose the times as
+ 00:15..00:29 and 00:29..01:02, as a single video.</p>
+ <p>In the absence of an explicit timeline, the zero time on the
+ <span>media timeline</span> should correspond to the first frame of
+ the <span>media resource</span>. For static audio and video files
+ this is generally trivial. For streaming resources, if the user
+ agent will be able to seek to an earlier point than the first frame
+ originally provided by the server, then the zero time should
+ correspond to the earliest seekable time of the <span>media
+ resource</span>; otherwise, it should correspond to the first frame
+ received from the server (the point in the <span>media
+ resource</span> at which the user agent began receiving the
+ stream).</p>
+
+ <p class="example">Another example would be a stream that carries a
+ video with several concatenated fragments, broadcast by a server
+ that does not allow user agents to request specific times but
+ instead just streams the video data in a predetermined order. If a
+ user agent connects to this stream and receives fragments defined as
+ covering timestamps 2010-03-20 23:15:00 UTC to 2010-03-21 00:05:00
+ UTC and 2010-02-12 14:25:00 UTC to 2010-02-12 14:35:00 UTC, it would
+ expose this with a <span>media timeline</span> starting at 0s and
+ extending to 3,600s (one hour). Assuming the streaming server
+ disconnected at the end of the second clip, the <code
+ title="dom-media-duration">duration</code> attribute would then
+ return 3,600. The <code
+ title="dom-media-startOffsetTime">startOffsetTime</code> attribute
+ would return a <code>Date</code> object with a time corresponding to
+ 2010-03-20 23:15:00 UTC. However, if a different user agent
+ connected five minutes later, <em>it</em> would (presumably) receive
+ fragments covering timestamps 2010-03-20 23:20:00 UTC to 2010-03-21
+ 00:05:00 UTC and 2010-02-12 14:25:00 UTC to 2010-02-12 14:35:00 UTC,
+ and would expose this with a <span>media timeline</span> starting at
+ 0s and extending to 3,300s (fifty five minutes). In this case, the
+ <code title="dom-media-startOffsetTime">startOffsetTime</code>
+ attribute would return a <code>Date</code> object with a time
+ corresponding to 2010-03-20 23:20:00 UTC.</p>
+
+ <p>In any case, the user agent must ensure that the <span>earliest
+ possible position</span> (as defined below) using the established
+ <span>media timeline</span>, is greater than or equal to zero.</p>
+
<p><span title="media element">Media elements</span> have a
- <dfn>current playback position</dfn>, which must initially be
- zero. The current position is a time.</p>
+ <dfn>current playback position</dfn>, which must initially (i.e. in
+ the absence of <span>media data</span>) be zero seconds. The
+ <span>current playback position</span> is a time on the <span>media
+ timeline</span>.</p>
<p>The <dfn
title="dom-media-currentTime"><code>currentTime</code></dfn>
@@ -27339,17 +27428,33 @@
must <span title="dom-media-seek">seek</span> to the new value
(which might raise an exception).</p>
+ <p><span title="media element">Media elements</span> have an
+ <dfn>initial playback position</dfn>, which must initially (i.e. in
+ the absence of <span>media data</span>) be zero seconds. The
+ <span>initial playback position</span> is updated when a <span>media
+ resource</span> is loaded. The <span>initial playback
+ position</span> is a time on the <span>media timeline</span>.</p>
+
+ <p>The <dfn
+ title="dom-media-initialTime">initialTime<code></code></dfn>
+ attribute must, on getting, return the <span>initial playback
+ position</span>, expressed in seconds.</p>
+
<p>If the <span>media resource</span> is a streaming resource, then
the user agent might be unable to obtain certain parts of the
resource after it has expired from its buffer. Similarly, some <span
- title="media resource">media resources</span> might have a timeline
- that doesn't start at zero. The <dfn>earliest possible
- position</dfn> is the earliest position in the stream or resource
- that the user agent can ever obtain again.</p>
+ title="media resource">media resources</span> might have a
+ <span>media timeline</span> that doesn't start at zero. The
+ <dfn>earliest possible position</dfn> is the earliest position in
+ the stream or resource that the user agent can ever obtain
+ again. It is also a time on the <span>media timeline</span>.</p>
- <p>The <dfn title="dom-media-startTime"><code>startTime</code></dfn>
- attribute must, on getting, return the <span>earliest possible
- position</span>, expressed in seconds.</p>
+ <p class="note">The <span>earliest possible position</span> is not
+ explicitly exposed in the API; it corresponds to the start time of
+ the first range in the <code
+ title="dom-media-seekable">seekable</code> attribute's
+ <code>TimeRanges</code> object, if any, or the <span>current
+ playback position</span> otherwise.</p>
<p>When the <span>earliest possible position</span> changes, then:
if the <span>current playback position</span> is before the
@@ -27369,20 +27474,56 @@
known</a>, the <span>current playback position</span> can never be
less than the <span>earliest possible position</span>.</p>
- <p>User agents must act as if the timeline of the <span>media
- resource</span> increases linearly starting from the <span>earliest
- possible position</span>, even if the underlying <span>media
- data</span> has out-of-order or even overlapping time codes.</p>
+ <p>The <dfn title="dom-media-duration"><code>duration</code></dfn>
+ attribute must return the time of the end of the <span>media
+ resource</span>, in seconds, on the <span>media timeline</span>. If
+ no <span>media data</span> is available, then the attributes must
+ return the Not-a-Number (NaN) value. If the <span>media
+ resource</span> is known to be unbounded (e.g. a streaming radio),
+ then the attribute must return the positive Infinity value.</p>
- <p class="example">For example, if two clips have been concatenated
- into one video file, but the video format exposes the original times
- for the two clips, the video data might expose a timeline that goes,
- say, 00:15..00:29 and then 00:05..00:38. However, the user agent
- would not expose those times; it would instead expose the times as
- 00:15..00:29 and 00:29..01:02, as a single video.</p>
+ <p>The user agent must determine the duration of the <span>media
+ resource</span> before playing any part of the <span>media
+ data</span> and before setting <code
+ title="dom-media-readyState">readyState</code> to a value equal to
+ or greater than <code
+ title="dom-media-HAVE_METADATA">HAVE_METADATA</code>, even if doing
+ so requires fetching multiple parts of the resource.</p>
+ <p id="durationChange">When the length of the <span>media
+ resource</span> changes to a known value (e.g. from being unknown to
+ known, or from a previously established length to a new length) the
+ user agent must <span>queue a task</span> to <span>fire a simple
+ event</span> named <code
+ title="event-media-durationchange">durationchange</code> at the
+ <span>media element</span>. (The event is not fired when the
+ duration is reset as part of loading a new media resource.)</p>
+
+ <p class="example">If an "infinite" stream ends for some reason,
+ then the duration would change from positive Infinity to the time of
+ the last frame or sample in the stream, and the <code
+ title="event-media-durationchange">durationchange</code> event would
+ be fired. Similarly, if the user agent initially estimated the
+ <span>media resource</span>'s duration instead of determining it
+ precisely, and later revises the estimate based on new information,
+ then the duration would change and the <code
+ title="event-media-durationchange">durationchange</code> event would
+ be fired.</p>
+
+ <p>Some video files also have an explicit date and time
+ corresponding to the zero time in the <span>media timeline</span>,
+ known as the <dfn>timeline offset</dfn>. Initially, the
+ <span>timeline offset</span> must be set to Not-a-Number (NaN).</p>
+
+ <p>The <dfn
+ title="dom-media-startOffsetTime"><code>startOffsetTime</code></dfn>
+ attribute must return a new <code>Date</code> object representing
+ the current <span>timeline offset</span>.</p>
+
</div>
+ <hr>
+
<p>The <dfn title="attr-media-loop"><code>loop</code></dfn>
attribute is a <span>boolean attribute</span> that, if specified,
indicates that the <span>media element</span> is to seek back to the
@@ -28388,10 +28529,12 @@
<span>media resource</span>, e.g. because it a simple movie file and
the user agent and the server support HTTP Range requests, then the
attribute would return an object with one range, whose start is the
- time of the first frame (typically zero), and whose end is the same
- as the time of the first frame plus the <code
+ time of the first frame (the <span>earliest possible
+ position</span>, typically zero), and whose end is the same as the
+ time of the first frame plus the <code
title="dom-media-duration">duration</code> attribute's value (which
- would equal the time of the last frame).</p>
+ would equal the time of the last frame, and might be positive
+ Infinity).</p>
<p class="note">The range might be continuously changing, e.g. if
the user agent is buffering a sliding window on an infinite
@@ -32011,8 +32154,8 @@
title="dom-media-buffered">buffered</code>, <code
title="dom-media-seekable">seekable</code> and <code
title="dom-media-played">played</code> IDL attributes of <span
- title="media element">media elements</span> must be the same as that
- element's <span>media resource</span>'s timeline.</p>
+ title="media element">media elements</span> must be that element's
+ <span>media timeline</span>.</p>
</div>
More information about the Commit-Watchers
mailing list