- From: poot <cvsmail@w3.org>
- Date: Wed, 18 Aug 2010 10:18:43 +0900 (JST)
- To: public-html-diffs@w3.org
hixie: Define the Media Timeline for <video> -- the timeline along which currentTime, duration, etc, are defined. (whatwg r5310) http://dev.w3.org/cvsweb/html5/spec/Overview.html?r1=1.4231&r2=1.4232&f=h http://html5.org/tools/web-apps-tracker?from=5309&to=5310 =================================================================== RCS file: /sources/public/html5/spec/Overview.html,v retrieving revision 1.4231 retrieving revision 1.4232 diff -u -d -r1.4231 -r1.4232 --- Overview.html 16 Aug 2010 23:08:55 -0000 1.4231 +++ Overview.html 18 Aug 2010 01:13:26 -0000 1.4232 @@ -311,7 +311,7 @@ <h1>HTML5</h1> <h2 class="no-num no-toc" id="a-vocabulary-and-associated-apis-for-html-and-xhtml">A vocabulary and associated APIs for HTML and XHTML</h2> - <h2 class="no-num no-toc" id="editor-s-draft-16-august-2010">Editor's Draft 16 August 2010</h2> + <h2 class="no-num no-toc" id="editor-s-draft-18-august-2010">Editor's Draft 18 August 2010</h2> <dl><dt>Latest Published Version:</dt> <dd><a href="http://www.w3.org/TR/html5/">http://www.w3.org/TR/html5/</a></dd> <dt>Latest Editor's Draft:</dt> @@ -417,7 +417,7 @@ Group</a> is the W3C working group responsible for this specification's progress along the W3C Recommendation track. - This specification is the 16 August 2010 Editor's Draft. + This specification is the 18 August 2010 Editor's Draft. </p><!-- UNDER NO CIRCUMSTANCES IS THE PRECEDING PARAGRAPH TO BE REMOVED OR EDITED WITHOUT TALKING TO IAN FIRST --><!-- relationship to other work (required) --><p>Work on this specification is also done at the <a href="http://www.whatwg.org/">WHATWG</a>. The W3C HTML working group actively pursues convergence with the WHATWG, as required by the <a href="http://www.w3.org/2007/03/HTML-WG-charter">W3C HTML working group charter</a>.</p><!-- UNDER NO CIRCUMSTANCES IS THE FOLLOWING PARAGRAPH TO BE REMOVED OR EDITED WITHOUT TALKING TO IAN FIRST --><!-- required patent boilerplate --><p>This document was produced by a group operating under the <a href="http://www.w3.org/Consortium/Patent-Policy-20040205/">5 @@ -20635,8 +20635,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>; @@ -20985,6 +20986,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> @@ -21380,19 +21398,38 @@ <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 @@ -21400,6 +21437,12 @@ </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 @@ -21414,9 +21457,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> @@ -21719,7 +21763,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> @@ -21742,53 +21787,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 @@ -21796,16 +21884,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 @@ -21821,19 +21923,47 @@ 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> - </div><p>The <dfn id="attr-media-loop" title="attr-media-loop"><code>loop</code></dfn> + <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><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.<div class="impl"> @@ -22536,9 +22666,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 @@ -22713,8 +22845,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><h5 id="mediaevents"><span class="secno">4.8.9.12 </span>Event summary</h5><p class="XXX annotation"><b>Status: </b><i>Last call for comments</i><p><i>This section is non-normative.</i><p>The following events fire on <a href="#media-element" title="media element">media elements</a> as part of the processing model described above:<table><thead><tr><th>Event name
Received on Wednesday, 18 August 2010 01:14:23 UTC