Skip to content

Commit

Permalink
[giow] (0) Rename startOffsetTime to startDate and try to clarify its…
Browse files Browse the repository at this point in the history 
… examples.

Affected topics: Video and Audio

git-svn-id: http://svn.whatwg.org/webapps@7045 340c8d12-0b0e-0410-8428-c7bf67bfef74
  • Loading branch information
@Hixie
Hixie committed Apr 3, 2012
1 parent 60bd780 commit 19c616c
Show file tree
Hide file tree
Showing 3 changed files with 176 additions and 107 deletions.
93 changes: 58 additions & 35 deletions complete.html
View file
Expand Up @@ -240,7 +240,7 @@

<header class=head id=head><p><a class=logo href=http://www.whatwg.org/><img alt=WHATWG height=101 src=/images/logo width=101></a></p>
<hgroup><h1 class=allcaps>HTML</h1>
<h2 class="no-num no-toc">Living Standard &mdash; Last Updated 2 April 2012</h2>
<h2 class="no-num no-toc">Living Standard &mdash; Last Updated 3 April 2012</h2>
</hgroup><dl><dt><strong>Web developer edition:</strong></dt>
<dd><strong><a href=http://developers.whatwg.org/>http://developers.whatwg.org/</a></strong></dd>
<dt>Multiple-page version:</dt>
Expand Down Expand Up @@ -27900,7 +27900,7 @@ <h4 id=media-elements><span class=secno>4.8.10 </span>Media elements</h4>
attribute double <a href=#dom-media-currenttime title=dom-media-currentTime>currentTime</a>;
readonly attribute double <a href=#dom-media-initialtime title=dom-media-initialTime>initialTime</a>;
readonly attribute double <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 <span>Date</span> <a href=#dom-media-startdate title=dom-media-startDate>startDate</a>;
readonly attribute boolean <a href=#dom-media-paused title=dom-media-paused>paused</a>;
attribute double <a href=#dom-media-defaultplaybackrate title=dom-media-defaultPlaybackRate>defaultPlaybackRate</a>;
attribute double <a href=#dom-media-playbackrate title=dom-media-playbackRate>playbackRate</a>;
Expand Down Expand Up @@ -29401,8 +29401,7 @@ <h5 id=offsets-into-the-media-resource><span class=secno>4.8.10.6 </span>Offsets
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>
and date, exposed using the <code title=dom-media-startDate><a href=#dom-media-startdate>startDate</a></code> attribute.</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
Expand All @@ -29422,36 +29421,60 @@ <h5 id=offsets-into-the-media-resource><span class=secno>4.8.10.6 </span>Offsets
<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>
this is generally trivial. For streaming resources that lack
explicit timelines, 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>

<div class=example>

<p>Consider a stream from a TV broadcaster, which begins streaming
on a sunny Friday afternoon in October, and always sends connecting
user agents the media data on the same media timeline, with its
zero time set to the start of this stream. Months later, user
agents connecting to this stream will find that the first frame
they receive has a time with millions of seconds. The <code title=dom-media-startDate><a href=#dom-media-startdate>startDate</a></code> attribute would always
return the date that the broadcast started; this would allow
controllers to display real times in their scrubber (e.g. "2:30pm")
rather than a time relative to when the broadcast began ("8 months,
4 hours, 12 minutes, and 23 seconds").</p>

<p>Consider 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, with the first frame delivered always being
identified as frame zero. 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-startDate><a href=#dom-media-startdate>startDate</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-startDate><a href=#dom-media-startdate>startDate</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 both of these examples, the <code title=dom-media-seekable><a href=#dom-media-seekable>seekable</a></code> attribute would give the
ranges that the controller would want to actually display in its
UI; typically, if the servers don't support seeking to arbitrary
times, this would be the range of time from the moment the user
agent connected to the stream up to the latest frame that the user
agent has obtained; however, if the user agent starts discarding
earlier information, the actual range might be shorter.</p>

</div>

<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
Expand Down Expand Up @@ -29578,7 +29601,7 @@ <h5 id=offsets-into-the-media-resource><span class=secno>4.8.10.6 </span>Offsets
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>
<p>The <dfn id=dom-media-startdate title=dom-media-startDate><code>startDate</code></dfn>
attribute must return <a href=#create-a-date-object title="create a Date object">a new
<code>Date</code> object</a> representing the current
<a href=#timeline-offset>timeline offset</a>.</p>
Expand Down
93 changes: 58 additions & 35 deletions index
View file
Expand Up @@ -240,7 +240,7 @@

<header class=head id=head><p><a class=logo href=http://www.whatwg.org/><img alt=WHATWG height=101 src=/images/logo width=101></a></p>
<hgroup><h1 class=allcaps>HTML</h1>
<h2 class="no-num no-toc">Living Standard &mdash; Last Updated 2 April 2012</h2>
<h2 class="no-num no-toc">Living Standard &mdash; Last Updated 3 April 2012</h2>
</hgroup><dl><dt><strong>Web developer edition:</strong></dt>
<dd><strong><a href=http://developers.whatwg.org/>http://developers.whatwg.org/</a></strong></dd>
<dt>Multiple-page version:</dt>
Expand Down Expand Up @@ -27900,7 +27900,7 @@ interface <dfn id=htmlaudioelement>HTMLAudioElement</dfn> : <a href=#htmlmediael
attribute double <a href=#dom-media-currenttime title=dom-media-currentTime>currentTime</a>;
readonly attribute double <a href=#dom-media-initialtime title=dom-media-initialTime>initialTime</a>;
readonly attribute double <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 <span>Date</span> <a href=#dom-media-startdate title=dom-media-startDate>startDate</a>;
readonly attribute boolean <a href=#dom-media-paused title=dom-media-paused>paused</a>;
attribute double <a href=#dom-media-defaultplaybackrate title=dom-media-defaultPlaybackRate>defaultPlaybackRate</a>;
attribute double <a href=#dom-media-playbackrate title=dom-media-playbackRate>playbackRate</a>;
Expand Down Expand Up @@ -29401,8 +29401,7 @@ interface <dfn id=htmlaudioelement>HTMLAudioElement</dfn> : <a href=#htmlmediael
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>
and date, exposed using the <code title=dom-media-startDate><a href=#dom-media-startdate>startDate</a></code> attribute.</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
Expand All @@ -29422,36 +29421,60 @@ interface <dfn id=htmlaudioelement>HTMLAudioElement</dfn> : <a href=#htmlmediael
<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>
this is generally trivial. For streaming resources that lack
explicit timelines, 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>

<div class=example>

<p>Consider a stream from a TV broadcaster, which begins streaming
on a sunny Friday afternoon in October, and always sends connecting
user agents the media data on the same media timeline, with its
zero time set to the start of this stream. Months later, user
agents connecting to this stream will find that the first frame
they receive has a time with millions of seconds. The <code title=dom-media-startDate><a href=#dom-media-startdate>startDate</a></code> attribute would always
return the date that the broadcast started; this would allow
controllers to display real times in their scrubber (e.g. "2:30pm")
rather than a time relative to when the broadcast began ("8 months,
4 hours, 12 minutes, and 23 seconds").</p>

<p>Consider 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, with the first frame delivered always being
identified as frame zero. 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-startDate><a href=#dom-media-startdate>startDate</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-startDate><a href=#dom-media-startdate>startDate</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 both of these examples, the <code title=dom-media-seekable><a href=#dom-media-seekable>seekable</a></code> attribute would give the
ranges that the controller would want to actually display in its
UI; typically, if the servers don't support seeking to arbitrary
times, this would be the range of time from the moment the user
agent connected to the stream up to the latest frame that the user
agent has obtained; however, if the user agent starts discarding
earlier information, the actual range might be shorter.</p>

</div>

<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
Expand Down Expand Up @@ -29578,7 +29601,7 @@ interface <dfn id=htmlaudioelement>HTMLAudioElement</dfn> : <a href=#htmlmediael
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>
<p>The <dfn id=dom-media-startdate title=dom-media-startDate><code>startDate</code></dfn>
attribute must return <a href=#create-a-date-object title="create a Date object">a new
<code>Date</code> object</a> representing the current
<a href=#timeline-offset>timeline offset</a>.</p>
Expand Down

0 comments on commit 19c616c

Please sign in to comment.