View snapshots are sometimes taken at the wrong scale
[WebKit-https.git] / Websites / webkit.org / specs / HTML_Timed_Media_Elements.html
1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
2 <html>
3 <head>
4         <title> Proposed HTML Timed Media Elements </title> 
5
6         <link href="./mediaelement.css" rel="stylesheet" type="text/css"> 
7
8         <style type="text/css">
9                 h4 + .element { margin-top: -2.5em; padding-top: 2em; }
10                 h4 + p + .element { margin-top: -5em; padding-top: 4em; }
11                 .element { background: #EFE; color: #000; margin: 0 0 1em -1em; padding: 0 1em 0.25em 0.75em; border-left: solid #9F9 0.25em; -padding: 0; /* that last decl is for IE6. Try removing it, it's hilarious! */ }
12                 .proposal { border: blue solid; padding: 1em; }
13                 table.matrix, table.matrix td { border: none; text-align: right; }
14                 table.matrix { margin-left: 2em; }
15
16                 .history table { width: 100%; }
17                 .history, .history td, .history th { border: solid thin; font-size: x-small }
18                 td.hauthor, td.hdate { width: 10%; }
19                 td.hversion { width: 5%; text-align: center; }
20                 td.hchange { width: 100%; }
21                 
22                 .event-definition table { border: solid thin #000; width: 95%; }
23                 .event-definition tr:last-child td { border: none; }
24                 .event-definition th { text-align: left; font-weight: bold; border: none; border-right: 1px dashed #ccc; border-bottom: 1px dashed #ccc; white-space: nowrap; background-color: #F7F5D7; padding-left: 8px; padding-right: 8px; }
25                 .event-definition td { width: 100%; font-family: monospace; font-weight: normal; padding-left: 1em; background-color: transparent; padding-right: 1em; border: none; }
26
27                 /* needed to override wiki CSS */
28                 a, a:link { text-decoration: underline;}
29                 th { color: #000; }
30                 
31                 .obsolete {
32                   font-size: larger;
33                   color: red;
34                 }
35         </style>
36
37 </head>
38
39 <body class="draft">
40
41         <div class="head">
42                 <h1> HTML Timed Media Elements </h1> <h2 class="no-num no-toc" id="working"> Working Draft &mdash; 19 March 2007 </h2> 
43                 <p class="copyright">&copy; Copyright 2007 Apple Inc. All rights reserved.</p>
44
45         </div>
46         <h2 class="no-num no-toc" id="abstract"> Abstract </h2> 
47
48         <p>This specification introduces features to HTML and the DOM for native support of timed media,
49         including but not limited to video and audio. </p>
50         
51         <h2 class="no-num no-toc" id="status"> Status of this document </h2> 
52
53         <p class="obsolete"><strong>This document is obsolete. Media Elements are now specified in the <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/video.html" title="4.8.6 The video element &mdash; HTML5 (including next generation additions still in development)">HTML5 specification</a>.</strong></p>
54         
55         <h2 class="no-num no-toc"id="contents"> Table of contents </h2>
56
57         <!--begin-toc-->
58         <ul class="toc">
59                 <li><a href="#introduction"><span class="secno">1.</span> Introduction</a> 
60                         
61                 <li><a href="#elements"><span class=secno>2.</span> Elements</a>
62                         <ul class=toc>
63
64                                 <li><a href="#the-video-element"><span class=secno>2.1.</span> 
65                                 The <code title=element-video>video </code>element</a>
66                                 <ul class=toc>
67                                         <li><a href="#video-element-attributes"><span class=secno>2.1.1.</span> Element attributes</a>
68                                         <li><a href="#video-dom-attributes"><span class=secno>2.1.2.</span>DOM attributes</a>
69                                 </ul>
70
71                                 <li><a href="#the-audio-element"><span class=secno>2.2.</span> 
72                                 The <code title=element-audio>audio</code> element</a>
73
74                                 <li><a href="#the-common-attributes"><span class=secno>2.3.</span>  
75                                 Attributes and methods common to <code title=element-video>video</code> and 
76                                 <code title=element-audio>audio</code> elements</a>
77
78                                         <ul class=toc>
79                                                 <li><a href="#common-element-attributes"><span class=secno>2.3.1.</span> Element attributes</a>
80                                                 <li><a href="#common-dom-attributes"><span class=secno>2.3.2.</span> DOM attributes and methods</a>
81                                                 <ul class=toc>
82                                                         <li><a href="#time-attributes"><span class=secno>2.3.2.1.</span> Time</a>
83                                                         <li><a href="#playback-attributes"><span class=secno>2.3.2.2.</span> Playback</a>
84                                                         <li><a href="#audio-attributes"><span class=secno>2.3.2.3.</span> Audio</a>
85                                                         <li><a href="#looping-attributes"><span class=secno>2.3.2.4.</span> Looping</a>
86                                                         <li><a href="#characteristics-attributes"><span class=secno>2.3.2.5.</span> Characteristics</a>
87                                                         <li><a href="#state-attributes"><span class=secno>2.3.2.6.</span> State</a>
88                                                         <li><a href="#time-triggers"><span class=secno>2.3.2.7.</span> Time triggers</a>
89                                                 </ul>
90                                         </ul>
91                         </ul>
92
93                 <li><a href="#events"><span class=secno>3.</span> Events</a>
94                         <ul class=toc>
95                                 <li><a href="#load-events"><span class=secno>3.1.</span> 
96                                 Media loading events</a>
97
98                                 <li><a href="#playback-events"><span class=secno>3.1.</span> 
99                                 Media playback events</a>
100                         </ul>
101
102                 <li><a href="#window-additions"><span class=secno>4.</span> WindowHTML Additions</a>
103
104                 <li class=no-num><a href="#references">References</a>
105                 
106                 <li class=no-num><a href="#acknowledgements">Acknowledgements</a>
107
108         </ul>
109         <!--end-toc-->
110
111         <hr>
112         <h2 id="introduction"><span class="secno">1.</span> Introduction</h2> 
113         <p><em>This section is non-normative.</em></p>
114
115         <p>While the World Wide Web has already been enriched by a variety of audio and video media,
116         support for timed media in user agents is currently provided by a variety of implementations
117         with their own peculiar sets of interfaces and behaviors. This proposal outlines a set of
118         standard interfaces and behaviors for timed media that can be supported by a variety of
119         implementations and applied to multiple audiovisual formats, with the goal of conferring upon
120         these types of media the benefits of native support, such as styling for presentation, improved
121         accessibility, and the opportunity to achieve greater uniformity of behavior.</p>
122
123         <p>Certain intrinsic characteristics of timed media and of its presentation must influence the
124         specifics of such a proposal:
125
126         <ul>
127                 <li> A presentation of timed media may encompass one or more media substreams, e.g. video
128                 and audio, that are rendered in concert with each other over time.
129
130                 <li> Resources containing timed media may be very large in size, even indefinitely large,
131                 and loaded and presented incrementally over time.
132
133                 <li> A variety of protocols can be used to load timed media for presentation, and the rules
134                 for use of these protocols vary. Some are intelligent about the timing characteristics of
135                 media streams and others are not. Some are file-based protocols and others are not. Some
136                 permit random access in the byte domain or in the time domain and others provide sequential
137                 access only.
138
139                 <li> Various states of timed media elements are subject to change, e.g. they can be ready to
140                 play or not ready to play, they can be playing or not, they can be actively loading data or
141                 not.
142
143                 <li> The properties of timed media elements can change with the availability of additional
144                 data according to the media formats and protocols in use, e.g. their total duration, their
145                 natural width and height, and even the number and type of media substreams they encompass.
146         </ul>
147
148         <p>In sum timed media is inherently dynamic, not only in its presentation but also in its
149         behavior. The current proposal is intended to provide standard mechanisms for controlling and
150         responding to this dynamism, while deferring to the user agent the choice of degree of dynamism
151         that's useful and supportable.</p>
152
153         
154         <h2 id="elements"><span class="secno">2.</span> New Elements</h2> 
155         
156         <h4 id=the-video-element><span class=secno>2.1.</span> The <dfn id=video title=element-video>
157         <code>video</code></dfn> element</h4>
158
159         <dl class=element>
160
161                 <dd><a href="http://www.whatwg.org/specs/web-apps/current-work/#strictly">Strictly inline-level</a> 
162                 <a href="http://www.whatwg.org/specs/web-apps/current-work/#embedded0">embedded content</a>. 
163
164                 <dt>Contexts in which this element may be used: 
165
166                 <dd>As the only <a href="http://www.whatwg.org/specs/web-apps/current-work/#embedded0">embedded content</a> 
167                 child of a <code><a href="http://www.whatwg.org/specs/web-apps/current-work/#figure0">figure</a></code> element. 
168
169                 <dd>Where <a href="http://www.whatwg.org/specs/web-apps/current-work/#strictly">
170                 strictly inline-level content</a> is allowed.
171
172                 <dt>Content model: 
173
174                 <dd>When used as the child of a 
175                 <code><a href="http://www.whatwg.org/specs/web-apps/current-work/#figure0">figure</a></code>
176                 element, or, when used as a 
177                 <em><code><a href="http://www.whatwg.org/specs/web-apps/current-work/#figure0">figure</a></code> fallback 
178                 <code><a href="#video">video</a></code></em>: zero or more 
179                 <a href="http://www.whatwg.org/specs/web-apps/current-work/#block-level1">block-level elements</a> 
180                 or a single
181                 <code><a href="#video">video</a></code> element, which is then considered to be a
182                 <em><code><a href="http://www.whatwg.org/specs/web-apps/current-work/#figure0">figure</a></code> fallback 
183                 <code><a href="#video">video</a></code></em>.
184
185                 <dd>Otherwise:
186                 <a href="http://www.whatwg.org/specs/web-apps/current-work/#inline-level1"> inline-level content</a>.
187
188                 <dt>Element-specific attributes: 
189                         <dd><code title="attr-media-src"><a href="#attr-src">src</a></code> (required) 
190                         <dd><code title="attr-media-type"><a href="#attr-type">type</a></code>
191                         <dd><code title="attr-video-height"><a href="#attr-height">height</a></code> 
192                         <dd><code title="attr-video-width"><a href="#attr-width">width</a></code> 
193                         <dd><code title="attr-media-autoplay"><a href="#attr-autoplay">autoplay</a></code>
194                         <dd><code title="attr-media-controller"><a href="#attr-controller">controller</a></code>
195                         
196                 <dt>Predefined classes that apply to this element: 
197                 <dd>None. 
198
199                 <dt>
200                         DOM interface: 
201                 <dd>
202 <pre class="idl">interface <dfn id=html-video-element>HTMLVideoElement : HTMLTimedMediaElement</dfn> {
203            attribute long <a href="#dom-video-height" title="video-element-height">height</a>;
204            attribute long <a href="#dom-video-width" title="video-element-width">width</a>;
205 };</pre> 
206
207                 <p class=note>An instance of <code><a
208                 href="#html-video-element">HTMLVideoElement</a></code> can be obtained using
209                 the <code title=dom-video-constructor><a href="#video-constructor">Video</a></code> constructor.</p>
210
211         </dl>
212
213         <p>A <code title=element-video><a href="#video">video</a></code> element represents a video or
214         movie, with an alternate representation given by its contents.
215
216         <h6 id="video-element-attributes"><span class=secno>2.1.1.</span> Video specific element attributes</h6>
217         
218                 <p>The <dfn id=attr-height title=attr-video-height><code>height</code></dfn> and
219                 <dfn id=attr-width title=attr-video-width><code>width</code></dfn> attributes
220                 give the preferred rendered dimensions of the media file if it is to be
221                 shown in a visual medium. If only one is specified, the size the other 
222                 is scaled preserving the media resource's intrinsic aspect ratio. These attributes must be either 
223                 <a href="http://www.whatwg.org/specs/web-apps/current-work/#valid" title="valid non-negative integer">
224                 valid non-negative integers</a> or 
225                 <a href="http://www.whatwg.org/specs/web-apps/current-work/#valid3" title="valid non-negative percentage">
226                 valid non-negative percentages.</a></p>
227                 
228                 <p>See below for definitions of 
229                         <code title="attr-media-src"><a href="#attr-src">src</a></code>,
230                         <code title="attr-media-type"><a href="#attr-type">type</a></code>,
231                         <code title="attr-media-autoplay"><a href="#attr-autoplay">autoplay</a></code>, and
232                         <code title="attr-media-controller"><a href="#attr-controller">controller</a></code>
233                 </p>
234
235
236         <h6 id="video-dom-attributes"><span class=secno>2.1.2.</span> Video specific DOM attributes</h6>
237                 <p>The DOM attributes <dfn id=dom-video-height title=video-element-height>
238                 <code>height</code></dfn> and <dfn id=dom-video-width
239                 title=video-element-width><code>width</code></dfn> must return the rendered
240                 height and width of the media resource, in CSS pixels, if the media resource is being
241                 rendered and is being rendered to a visual medium, or 0 otherwise. 
242                 <a href="#refsCSS21">[CSS21]</a></p>
243         
244 <!-- ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
245
246         <h4 id=the-audio-element><span class=secno>2.2. </span>The <dfn id=audio title=element-audio>
247         <code>audio</code></dfn> element</h4>
248
249         <p><a href="http://www.whatwg.org/specs/web-apps/current-work/#strictly">Strictly 
250         inline-level</a> <a href="http://www.whatwg.org/specs/web-apps/current-work/#embedded0">embedded content</a>. 
251
252         <dl class=element>
253
254                 <dt>Contexts in which this element may be used: 
255
256                 <dd>As the only <a href="http://www.whatwg.org/specs/web-apps/current-work/#embedded0">embedded content</a> 
257                 child of a <code><a href="http://www.whatwg.org/specs/web-apps/current-work/#figure0">figure</a></code> element. 
258
259                 <dd>Where <a href="http://www.whatwg.org/specs/web-apps/current-work/#strictly">
260                 strictly inline-level content</a> is allowed.
261
262                 <dt>Content model: 
263
264                 <dd>When used as the child of a 
265                 <code><a href="http://www.whatwg.org/specs/web-apps/current-work/#figure0">figure</a></code>
266                 element, or, when used as a 
267                 <em><code><a href="http://www.whatwg.org/specs/web-apps/current-work/#figure0">figure</a></code> fallback 
268                 <code><a href="#audio">audio</a></code></em>: zero or more 
269                 <a href="http://www.whatwg.org/specs/web-apps/current-work/#block-level1">block-level elements</a> 
270                 or a single
271                 <code><a href="#audio">audio</a></code> element, which is then considered to be a
272                 <em><code><a href="http://www.whatwg.org/specs/web-apps/current-work/#figure0">figure</a></code> fallback 
273                 <code><a href="#audio">audio</a></code></em>.
274
275                 <dd>Otherwise:
276                 <a href="http://www.whatwg.org/specs/web-apps/current-work/#inline-level1"> inline-level content</a>.
277
278                 <dt>Element-specific attributes: 
279                         <dd><code title="attr-media-src"><a href="#attr-src">src</a></code> (required) 
280                         <dd><code title="attr-media-type"><a href="#attr-type">type</a></code>
281                         <dd><code title="attr-media-autoplay"><a href="#attr-autoplay">autoplay</a></code>
282                         <dd><code title="attr-media-controller"><a href="#attr-controller">controller</a></code>
283                         
284                 <dt>Predefined classes that apply to this element: 
285                 <dd>None. 
286
287                 <dt>DOM interface: 
288                 <dd> No difference from <code><a href="#html-timed-media-element">HTMLTimedMediaElement</a></code>.
289
290     <p class=note>An instance of <code><a
291      href="#html-audio-element">HTMLAudioElement</a></code> can be obtained using
292      the <code title=dom-audio-constructor><a href="#audio">Audio</a></code> constructor.</p>
293
294         </dl>
295
296         <p>Audio objects have no spatial representation. They are heard and not seen. Otherwise they have 
297         the same API as video objects.</p>
298         
299         <p>The user agent must render only the audio media contained in the resource, regardless of
300         whatever else it might contain. If the source is an MP3 file containing synchronized lyrics, for
301         example, the user agent must render only the audio and not the text.</p>
302
303
304         <p>See below for definitions of 
305                 <code title="attr-media-src"><a href="#attr-src">src</a></code>,
306                 <code title="attr-media-type"><a href="#attr-type">type</a></code>,
307                 <code title="attr-media-autoplay"><a href="#attr-autoplay">autoplay</a></code>, and
308                 <code title="attr-media-controller"><a href="#attr-controller">controller</a></code>
309         </p>
310
311         <p class="big-issue">Need some words about using only audio when media file has both audio and 
312         video.</p>
313
314
315 <!-- ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
316
317         <h3 id=the-common-attributes><span class=secno>2.3.</span> Attributes common to the
318         <code title=element-video>video</code> and <code title=element-audio>audio</code> elements</h3>
319
320         <h5 id=common-element-attributes><span class=secno>2.3.1.</span> 
321         Element attributes common to <code title=element-video>video</code> and 
322         <code title=element-audio>audio</code> elements.</h5>
323
324         <p>The <dfn id="attr-src" title="attr-media-src"><code>src</code></dfn> attribute
325         must contain the URI (or IRI) of the media resource.
326         
327         <p>When the src attribute is set and the specified resource has a supported type, the user agent
328         must prepare to present it according to the appropriate transfer protocol. This may entail the
329         initiation of network sessions, including but not limited to file transfers. If the presentation
330         of timed media by the user agent has been disabled, if the resource has an unsupported type, or
331         if the preparations for its presentation fail either because of a protocol failure or because
332         the format of the media is unrecognized, the user agent must fire an error event on the element
333         and display the element's fallback content, if available.</p>
334
335         <p>The user agent may choose to proceed with the presentation of media that it can render
336         only partially, for any of the following reasons:
337
338         <ul>
339                 <li> A media type is not supported, i.e. the resource contains one or more renderable substreams
340                 of types not supported by the user agent.  Example: a 3GPP file with timed text on a device that
341                 does not have a text renderer.
342
343                 <li> A media format is not supported, i.e. a renderable substream of a type that's supported by
344                 the user agent contains media that can't be decoded. Example: a user agent that supports only
345                 H.264 at baseline profile encounters an MPEG-4 file with a video track with H.264 frames encoded
346                 in main profile.
347
348                 <li> Media can't be rendered under current constraints. Here there's no problem with media types
349                 or formats but the resource can't be rendered anyway, possibly temporarily. Example: a user
350                 agent that can decode only one H.264 video stream at a time is requested to decode multiple
351                 streams simultaneously.
352         </ul>
353
354         <p>From the user's perspective, these cases look very much the same because their only obvious
355         symptom is that some or all of the media cannot be rendered. In this case, the user agent may emit
356         a <code title=event-mediarendererror><a href="#eventdef-event-mediarendererror">mediarendererror</a></code>.
357
358         <p>The <dfn id=attr-type title=attr-media-type><code>type</code></dfn>
359         attribute, if present, gives the MIME type of the media resource specified 
360         by <code title="attr-media-src"><a href="#attr-src">src</a></code>. This attribute is optional 
361         but recommended as it allows the user agent to avoid loading  information for unsupported 
362         content types. The value must be a valid MIME type <a href="#refsRFC2046">
363         [RFC2046]</a>, optionally with parameters indicating the codec(s) required to render the content
364         <a href="#refsRFC4281">[RFC4281]</a>. The <code title=attr-media-type>type</code> attribute 
365         is purely advisory and is only intended for static fallback, it is only considered when deciding
366         whether to initiate a load or not.</p>
367
368         <p>The <code title=attr-media-type>type</code> attribute can thus be used by the page author 
369         to select different content for different user agent configurations. For the following example:
370 <pre >
371 &lt;video src="big_264.mp4" type="video/mp4; codecs=mp4v.21.3"&gt;
372     &lt;video src="medium.mp4" type="video/mp4; codecs=mp4v.20.9"&gt;
373         &lt;img src="small.png" alt="alternate image for non-video browsers /&gt;
374     &lt;/video&gt;
375 &lt;/video&gt;
376 </pre>
377
378         <p>the user agent would choose the outmost &lt;video&gt; if it supports H.264 visual simple profile
379         level 1, else the inner &lt;video&gt; if it suports MPEG-4 visual simple profile level 0, else the 
380         &lt;img&gt; if it supports PNG, else the alternate text.
381
382         <p>Because the supportability and desirability of media container formats and media encoding
383         formats vary widely according to the needs and constraints of user agents, the process of static
384         fallback for HTML timed media elements allows the user agent to examine multiple descriptive
385         attributes that indicate the suitability of a given resource for loading and presentation.
386
387         <ol>
388                 <li> Examine the <code title=attr-media-type><a href="#attr-type">type</a></code> attribute,
389                 if present. If not present proceed to step 2.
390         
391                 If the <code title=attr-media-type><a href="#attr-type">type</a></code>, optionally including
392                 information about the codec(s) required to render it as described in RFC 4281, is not supported
393                 by the user agent, the element doesn't represent anything except what its contents
394                 represent and static fallback may ensue. <a href="#refsRFC4281">[RFC4281]</a>
395         
396                 <li> Begin a load of the resource specified by the 
397                 <code title=attr-media-src><a href="#attr-src">src</a></code> attribute. Note that dynamic 
398                 fallback may ensue for a variety of reasons. See the discussion of 
399                 "<code title=event-mediarendererror><a href="#eventdef-event-mediarendererror">mediarendererror</a></code>"
400                 below.
401         </ol>
402
403         <p class="big-issue">Should there be other advisory markup attributes in order to describe
404         content even more precisely, e.g. dataRate? Should CSS Media Queries be extended to support 
405         bandwidth?
406
407         <p>The <dfn id=attr-autoplay title=attr-media-autoplay><code>autoplay</code></dfn> attribute is a 
408         <a href="http://www.whatwg.org/specs/web-apps/current-work/#boolean0">boolean attribute</a>.
409         If the attribute is present, the user agent must begin playing the element as soon as it 
410         estimates that playback will not be interrupted to rebuffer.</p>
411
412         <p>The <dfn id=attr-controller title=attr-media-controller><code>controller</code></dfn> attribute is a 
413         <a href="http://www.whatwg.org/specs/web-apps/current-work/#boolean0">boolean attribute</a>.
414         If the attribute is present, the user agent must display a user interface which allows the user
415         to control the media element. The <code title="attr-video-height"><a href="#attr-height">height</a></code> 
416         attribute on the element does not include the size of the controller, it is the size of the 
417         video element only. 
418         <span class="big-issue">Should we specify the position of the controller?</span>
419         <span class="big-issue">Should we specify <em>what</em> controls it should have?</span>
420         </p>
421
422         <p>The <code title=element-video><a href="#video">video</a></code>
423         and <code title=element-audio><a href="#audio">audio</a></code>
424         elements must implement the <code><a href="#html-timed-media-element">HTMLTimedMediaElement</a></code> interface:
425         
426
427 <pre class="idl">interface <dfn id="html-timed-media-element">HTMLTimedMediaElement : HTMLElement</dfn> {
428            attribute DOMString <a href="#dom-src" title="dom-media-src">src</a>;
429            attribute DOMString <a href="#dom-type" title="dom-media-type">type</a>;
430
431   // <a href="#time-attributes">Time</a>
432            attribute float <a href="#starttime" title="dom-media-starttime">startTime</a>;
433            attribute float <a href="#endtime" title="dom-media-endtime">endTime</a>;
434            attribute float <a href="#currenttime" title="dom-media-currenttime">currentTime</a>;
435   readonly attribute float <a href="#duration" title="dom-media-duration">duration</a>;
436   readonly attribute float <a href="#availableduration" title="dom-media-availableduration">availableDuration</a>;
437
438   // <a href="#playback-attributes">Playback</a>
439            attribute float <a href="#currentrate" title="dom-media-currentrate">currentRate</a>;
440            attribute float <a href="#playrate" title="dom-media-playrate">playRate</a>;
441            attribute boolean <a href="#ispaused" title="dom-media-ispaused">isPaused</a>;
442
443   void <a href="#play" title="dom-media-play">play</a>();
444   void <a href="#pause" title="dom-media-pause">pause</a>();
445   void <a href="#step" title="dom-media-step">step</a>(in long numberOfFrames);
446
447   // <a href="#audio-attributes">Audio</a>
448            attribute float <a href="#volume" title="dom-media-volume">volume</a>;
449            attribute boolean <a href="#muted" title="dom-media-muted">muted</a>;
450  
451   // <a href="#looping-attributes">Looping</a>
452            attribute long <a href="#loopcount" title="dom-media-loopcount">loopCount</a>;
453            attribute long <a href="#currentloop" title="dom-media-currentloop">currentLoop</a>;
454            attribute float <a href="#loopstarttime" title="dom-media-loopstarttime">loopStartTime</a>;
455            attribute float <a href="#loopendtime" title="dom-media-loopendtime">loopEndTime</a>;
456
457   // <a href="#characteristics-attributes">Characteristics</a>
458            attribute boolean <a href="#hasaudio" title="dom-media-hasaudio">hasAudio</a>;
459            attribute boolean <a href="#hasvisual" title="dom-media-hasvisual">hasVisual</a>;
460
461   // <a href="#state-attributes">State</a>
462   const unsigned short <a href="#uninitialized" title="dom-media-UNINITIALIZED">UNINITIALIZED</a> = 0;
463   const unsigned short <a href="#error" title="dom-media-ERROR">ERROR</a> = 1;
464   const unsigned short <a href="#understandable" title="dom-media-UNDERSTANDABLE">UNDERSTANDABLE</a> = 2;
465   const unsigned short <a href="#presentable" title="dom-media-PRESENTABLE">PRESENTABLE</a> = 3;
466   const unsigned short <a href="#playable" title="dom-media-PLAYABLE">PLAYABLE</a> = 4;
467   const unsigned short <a href="#playthroughok" title="dom-media-PLAYTHROUGHOK">PLAYTHROUGHOK</a> = 5;
468   const unsigned short <a href="#loaded" title="dom-media-LOADED">LOADED</a> = 6;
469
470   readonly attribute long <a href="#mediastatus" title="dom-media-mediastatus">mediaStatus</a>;
471
472   // <a href="#time-triggers">Timed triggers</a>
473   void <a href="#settimetrigger" title="dom-media-settimetrigger">setTimeTrigger</a>(in float time, in TimeTriggerListener listener);
474   void <a href="#removetimetrigger" title="dom-media-removetimetrigger">removeTimeTrigger</a>(in float time, in TimeTriggerListener listener);
475
476 };</pre> 
477
478 <pre class="idl">interface <dfn id="time-trigger-listener">TimeTriggerListener</dfn> {
479   void <a href="#handletimetrigger" title="timetrigger-listener-handletimetrigger">handleTimeTrigger</a>(in float time);
480 };</pre> 
481
482
483         <h5 id=common-dom-attributes><span class=secno>2.3.2.</span> 
484         DOM attributes and methods common to <code title=element-video>video</code> and 
485         <code title=element-audio>audio</code> elements.</h5>
486
487         <p>The DOM attributes <dfn id=dom-src title=dom-media-src><code>src</code></dfn> 
488         and <dfn id=dom-type title=dom-media-type><code>type</code></dfn> 
489         each must reflect the respective content attributes of the same name.
490
491         <p>When the <code title=dom-media-src><a href="#dom-src">src</a></code>
492         attribute is set, the user agent must immediately begin to download the
493         specified resource unless the user agent cannot support <code title=element-video>
494         video</code>/<code title=element-audio>audio</code>, or its support for 
495         <code title=element-video>video</code>/<code title=element-audio>audio</code> has
496         been disabled. The <code title=dom-media-type>type</code>
497         attribute is considered at this time, so it should be cleared or reset when the
498         <code title=dom-media-src><a href="#dom-src">src</a></code> attribute it set to a media
499         resource with a different type. Fallback content must be reconsidered if the
500         user agent is unable to load and display the specified resource.
501         
502         
503         <h6 id="time-attributes"><span class=secno>2.3.2.1.</span> Time Attributes</h6>
504
505                 <p>Media durations are not always finite. For example: the duration of a "live" RTP stream
506                 is <em>indefinite</em> as long as it lasts, i.e. such streams typically proceed indefinitely
507                 without signalling their duration until the server closes the session. </p>
508                 
509                 <p>A media resource which has a <em>finite</em> duration may not have a <em>known</em>
510                 duration, or may not have a precisely known duration, for some period of time even after
511                 playback can be initiated. For example: MPEG elementary streams, including audio elementary
512                 streams such as MP3 files, must be completely scanned in order to determine their precise
513                 duration. If a user agent reports an approximate duration, it must fire a 
514                 <code title=event-durationchange><a href="#durationchange">durationchange</a></code> event 
515                 when the estimate is refined or the precise duration becomes known.</p>
516
517                 <p>Time values are represented as floating point numbers, representing a length of time in
518                 seconds. A value of +infinity, ECMAScript <code>Number.POSITIVE_INFINITY</code>, signifies
519                 an "indefinite" time. A time value of "Not A Number", ECMAScript <code>Number.NaN</code>,
520                 signifies an unknown or unspecified time value. This approach has the advantage of encouraging 
521                 script writers to cope with these situations, as opposed to the approach of defining other
522                 attributes that need to be examined to determine the validity of the duration attribute but
523                 which are easily ignored.</p>
524
525                 <p class="big-issue">It would be helpful to have utility functions to convert from a formatted
526                 time string to a double and back. Where should these go?</p>
527         
528                 <p>The DOM attribute <dfn id=availableduration title=dom-media-availableduration>
529                 <code>availableDuration</code></dfn> returns the duration of the portion of media which is 
530                 available for playing. The user agent must fire an
531                 <code title=event-availabledurationchange><a href="#availabledurationchange">availabledurationchange</a></code>
532                 when the portion of media available for playing changes.</p>
533
534                 <p>The DOM attribute <dfn id=duration title=dom-media-duration><code>duration</code></dfn> 
535                 returns the total duration of the complete media file. For some media formats, the value 
536                 returned may be an estimate. When an estimated duration is returned, the user agent will
537                 fire a <code title=event-durationchange><a href="#durationchange">durationchange</a></code>
538                 event when the estimate is refined or the precise duration becomes known.</p>
539
540                 <p>The DOM attribute <dfn id=starttime title=dom-media-starttime><code>startTime</code></dfn> 
541                 gets and sets the time at which a movie begins to play, and the time at which it stops
542                 when playing in reverse. The initial value is 0. The value must be in the range from 0
543                 to <code title=dom-media-endtime><a href="#endtime">endTime</a></code>. If the attribute is
544                 set to a value greater than <code title=dom-media-endtime><a href="#endtime">endTime</a></code>,
545                 it is clipped to <code title=dom-media-endtime><a href="#endtime">endTime</a></code>.
546                 <span class="big-issue">Or should it retain the previous value???</span>
547                 </p>
548
549                 <p>The DOM attribute <dfn id=endtime title=dom-media-endtime><code>endTime</code></dfn> 
550                 gets and sets the time at which a movie stops playing, and the time at which it begins when
551                 playing in reverse. This attribute is initially set to <code>Number.NaN</code> to signal
552                 that it has not been set. The value must be in the range from
553                 <code title=dom-media-starttime><a href="#starttime">startTime</a></code> to 
554                 <code title=dom-media-duration><a href="#duration">duration</a></code>. If the attribute
555                 is set to a value outside this range, it is clipped to the nearest legal value.
556                 <span class="big-issue">Or should it retain the previous value???</span>
557                 </p>
558
559                 <p>The DOM attribute <dfn id=currenttime title=dom-media-currentTime><code>currentTime</code></dfn>
560                 gets and sets the position of the play head in the media element's timeline.</p>
561         
562         <h6 id="playback-attributes"><span class=secno>2.3.2.2.</span> Playback Attributes</h6>
563                 <p>The DOM attribute <dfn id=currentrate title=dom-media-currentrate><code>currentRate</code></dfn> 
564                 is the rate at which a media element is currently playing.</p>
565         
566                 <p>The DOM attribute <dfn id=playrate title=dom-media-playrate><code>playRate</code></dfn>
567                 is the rate that is implicitly set on a media element when its play() method is invoked.
568                 Some media formats do not allow the play rate to be changed, for example a live RTP stream.
569                 <span class="big-issue"> What should the UA do when someone tries to set the rate on a media
570                 format that doesn't allow it? Should we specify the behavior?</span> This value is
571                 initialized to the media resource's intrinsic value, eg. the <a href=
572                 "http://developer.apple.com/documentation/QuickTime/QTFF/QTFFChap2/chapter_3_section_2.html#//apple_ref/doc/uid/TP40000939-CH204-32947">
573                 <code>"preferred rate"</code></a> of a QuickTime movie, or 1 if there is no
574                 intrinsic value. Changing the <code title=dom-media-playrate>playRate</code> when an element
575                 is already playing shall <em>not</em> change the 
576                 <code title=dom-media-currentrate>currentRate</code>. The rate change does not take effect until
577                 the <code title=dom-media-play>play()</code> method is called again.</p>
578         
579                 <p>The DOM attribute <dfn id=ispaused title=dom-media-ispaused><code>isPaused</code></dfn> 
580                 returns a value that specifies whether the element is in a paused state. An element that
581                 is not paused may have a rate of 0 if it is prerolling. <span class="big-issue">This
582                 should be clarified</span></p>
583         
584                 <p>The <dfn id=play title=dom-media-play><code>play()
585                 </code></dfn> method begins playing the element at the <code title=dom-media-playrate>
586                 <a href="#playrate">playRate</a></code>. </p>
587         
588                 <p>The <dfn id=pause title=dom-media-pause><code>pause()</code></dfn> method sets the 
589                 play rate to zero.</p>
590         
591                 <p>The <dfn id=step title=dom-media-step><code>step(<var title="">numberOfFrames</var>)
592                 </code></dfn> method steps the specified number of frames. Negative values step backwards.</p>
593
594         <h6 id="audio-attributes"><span class=secno>2.3.2.3.</span> Audio Attributes</h6>
595                 <p>The DOM attribute <dfn id=volume title=dom-media-volume><code>volume</code></dfn> 
596                 gets and sets the audio volume of the movie. Legal values are between '0' and '100',
597                 values outside of this range are clipped.</p>
598         
599                 <p>The DOM attribute <dfn id=muted title=dom-media-muted><code>muted</code></dfn> 
600                 gets and sets a value that indicates whether the audio is turned on or off.</p>
601
602         <h6 id="looping-attributes"><span class=secno>2.3.2.4.</span> Looping Attributes</h6>
603
604                 <p>The DOM attribute <dfn id=loopcount title=dom-media-loopcount><code>loopCount</code></dfn> 
605                 gets and sets the number of loop itterations that will be played before the media stops.</p>
606
607                 <p>The DOM attribute <dfn id=currentloop title=dom-media-currentloop><code>currentLoop</code></dfn> 
608                 returns the index of the current itteration of the playback of the media. For example, on the 
609                 first play through the value will be 0, the second time through it will be 1, etc. Playback
610                 stops when <code title=dom-media-currentloop><a href="#currentloop">currentloop</a></code>
611                 equals <code title=dom-media-loopcount><a href="#loopcount">loopCount</a></code>.</p>
612
613                 <p>The DOM attribute <dfn id=loopstarttime title=dom-media-loopstarttime><code>loopStartTime</code></dfn> 
614                 gets and sets the time at which a movie begins to play after looping, and the time at which
615                 it loops when playing in reverse. The initial value is 0. The value must be in the range from 0
616                 to <code title=dom-media-loopendtime><a href="#loopendtime">loopEndTime</a></code>.
617                 If the attribute is set to a value outside this range, it is clipped to the nearest legal value. 
618                 <span class="big-issue">Or should it retain the previous value???</span>
619                 </p>
620
621                 <p>The DOM attribute <dfn id=loopendtime title=dom-media-loopendtime><code>loopEndTime</code></dfn> 
622                 gets and sets the time at which a movie loops, and the time at which it begins to play 
623                 after looping when playing in reverse. This attribute is initially set to <code>Number.NaN</code> 
624                 to signal that it has not been set. The value must be in the range from the
625                 <code title=dom-media-loopstarttime><a href="#loopstarttime">loopStartTime</a></code>
626                 to <code title=dom-media-duration><a href="#duration">duration</a></code>. If the attribute
627                 is set to a value outside this range, it is clipped to the nearest legal value.
628                 <span class="big-issue">Or should it retain the previous value???</span>
629                 </p>
630
631         <h6 id="characteristics-attributes"><span class=secno>2.3.2.5.</span> Characteristics</h6>
632                 <p>The DOM attribute <dfn id=hasaudio title=dom-media-hasaudio><code>hasAudio</code></dfn> 
633                 returns a value that specifies whether the element has audio media.</p>
634
635                 <p>The DOM attribute <dfn id=hasvisual title=dom-media-hasvisual><code>hasVisual</code></dfn> 
636                 returns a value that specifies whether the element can draw on the screen. An 
637                 <code title=element-audio><a href="#audio">audio</a></code> element whose 
638                 <code title="attr-media-src">src</code>
639                 attribute specifies a media resource that contains visual media shall return false since
640                 the visual media will not be rendered.</p>
641
642         <h6 id="state-attributes"><span class=secno>2.3.2.6.</span> State</h6>
643                 <p>The DOM attribute <dfn id=mediastatus title=dom-media-mediastatus><code>mediaStatus</code></dfn> 
644                 returns the current state of the media element taking into consideration its current loading
645                 progress and its playability. As loading progresses and playability changes, appropriate
646                 events (e.g., "mediaunderstandable", "mediapresentable", "load") should be fired. However,
647                 as it may be necessary to know the current state of the media element after state
648                 transitions have already occurred, the mediaStatus attribute can be retrieved to know the
649                 media element's current status.</p>
650                 
651                 <p>When the element is created the attribute must be set to 0. It can have the following
652                 values:</p>
653
654                 <dl>
655                         <dt>0 <dfn id=uninitialized title=dom-media-UNINITIALIZED><code>UNINITIALIZED</code></dfn> 
656                                 <dd>The initial value.
657
658                         <dt>1 <dfn id=error title=dom-media-ERROR><code>ERROR</code></dfn> 
659                                 <dd>This playability state indicates that some kind of error has occurred (which
660                                 should also be signaled by an error event). One reason this state might be set is
661                                 that the media file is invalid.
662
663                         <dt>2 <dfn id=understandable title=dom-media-UNDERSTANDABLE><code>UNDERSTANDABLE</code></dfn> 
664                                 <dd>Attributes of the media element are now available for retrieval (e.g.,
665                                 <code title=dom-media-duration><a href="#duration">duration</a></code>). It however 
666                                 has not reached a state where it can render anything (e.g., an image if the media
667                                 type is visual) or an attempt to play the content should be made.
668
669                         <dt>3 <dfn id=presentable title=dom-media-PRESENTABLE><code>PRESENTABLE</code></dfn> 
670                                 <dd>The media element has loaded sufficient media data to render at the current time
671                                 (e.g., it can render the video frame at the current time). It has not however loaded
672                                 sufficient media data so that setting the 
673                                 <code title=dom-media-currentrate><a href="#currentrate">currentRate</a></code>
674                                 property to a non-zero value will render anything (video or audio) more.
675
676                         <dt>4 <dfn id=playable title=dom-media-PLAYABLE><code>PLAYABLE</code></dfn> 
677                                 <dd>The media element has loaded sufficient media data so that if the play rate was
678                                 set to a non-zero value, time will advance.
679
680                         <dt>5 <dfn id=playthroughok title=dom-media-PLAYTHROUGHOK><code>PLAYTHROUGHOK</code></dfn> 
681                                 <dd>The media element has loaded sufficient media data and playback conditions
682                                 (e.g., download rates, data rate of the media, playback rate) should allow for
683                                 uninterrupted playback (i.e., no stalls) if the current playback rate is set to the
684                                 value of playbackRate.
685
686                         <dt>6 <dfn id=loaded title=dom-media-LOADED><code>LOADED</code></dfn> 
687                                 <dd>All necessary media data for the media element is available (and no data will be
688                                 evicted). This is not strictly the same thing as all data for the media element's
689                                 file or files is local, only that all data that can be referenced during playback 
690                                 will remain available for the life span of the element. To detect if all data 
691                                 across the media element's files is available, listen for the load event.
692                 </dl>
693
694                 <p>The <code title=dom-media-mediastatus><a href="#mediastatus">mediaStatus</a></code>
695                 attribute and associated events are useful to an implementor of a custom play controller as
696                 they can wait for <code title=dom-media-PLAYTHROUGHOK><a href="#playthroughok">PLAYTHROUGHOK</a></code>
697                 or <code title=dom-media-LOADED><a href="#loaded">LOADED</a></code> to know that autoplay may start. Likewise, if
698                 during playback, the playback catches up with download, one can pause playback by checking
699                 for a state less than <code title=dom-media-PLAYABLE><a href="#playable">PLAYABLE</a></code>.</p>
700
701                 <p>The mediaStatus state values are ordered so that as the media becomes more playable, the
702                 values increase. An effect of this is that to detect if the current playability allows for
703                 querying media properties (i.e., the media element is "understandable"), one can compare the current
704                 <code title=dom-media-mediastatus><a href="#mediastatus">mediaStatus</a></code> against 
705                 <code title=dom-media-UNDERSTANDABLE><a href="#understandable">UNDERSTANDABLE</a></code>.
706                 If equal to or greater than <code title=dom-media-UNDERSTANDABLE><a href="#understandable">UNDERSTANDABLE</a></code>
707                 , then properties can be queried. 
708                 If less than <code title=dom-media-UNDERSTANDABLE><a href="#understandable">UNDERSTANDABLE</a></code>
709                 (including the <code title=dom-media-ERROR><a href="#error">ERROR</a></code> state), 
710                 properties should not be requested.</p>
711
712                 <p>The following state chart illustrates the possible <code title=dom-media-mediastatus>mediaStatus</code>
713                 state transitions.</p>
714         <img src="movie-status-states.png" alt="State chart" />
715
716                 <p>It is possible for the states reported by <code title=dom-media-mediastatus><a href="#mediastatus">mediaStatus</a></code>
717                 to regress as the result of a seek, a change in network conditions (bandwidth changes or
718                 connection drops), changes in play rate/direction, changes in looping, cache unloading, etc.
719                 Such changes from any of the presentable/playable states (i.e., 
720                 <code title=dom-media-PRESENTABLE><a href="#presentable">PRESENTABLE</a></code>, 
721                 <code title=dom-media-PLAYABLE><a href="#playable">PLAYABLE</a></code>,
722                 <code title=dom-media-PLAYTHROUGHOK><a href="#playthroughok">PLAYTHROUGHOK</a></code>)
723                 may push the media element's current media status to an earlier state,
724                 including <code title=dom-media-UNDERSTANDABLE><a href="#understandable">UNDERSTANDABLE</a></code>.
725
726                 <p>To accommodate media playback scenarios where previously loaded media data may be evicted
727                 during playback (e.g., because of limited caching by the user agent), the 
728                 <code title=dom-media-LOADED><a href="#loaded">LOADED</a></code> state (and
729                 the firing of the "load" event) may only occur if all data becomes loaded and cannot be
730                 evicted during the life of the media element.</p>
731
732
733         <h6 id="time-triggers"><span class=secno>2.3.2.7.</span> Time triggers</h6>
734                 <p>The <dfn id=settimetrigger title=dom-media-settimetrigger>
735                 <code>setTimeTrigger(<var title="">time</var>, <var title="">listener</var>)</code>
736                 </dfn> method registers a callback for when the media element plays through 
737                 <var title="">time</var>. <var title="">listener</var> must be an object implementing
738                 the <code><a href="#time-trigger-listener">TimeTriggerListener</a></code> interface, or a JavaScript 
739                 function.</p>
740         
741         
742                 <p>The <dfn id=removetimetrigger title=dom-media-removetimetrigger>
743                 <code>removeTimeTrigger(<var title="">time</var>, <var title="">listener</var>)</code>
744                 </dfn> method removes a previously registered <code><a href="#time-trigger-listener">
745                 TimeTriggerListener</a></code> from a media element.</p>
746
747         <h2 id="events"><span class="secno">3.</span> Events</h2> 
748         
749         <h3 id=load-events><span class=secno>3.1.</span> Media loading events</h3>
750
751         <div class='event-definition'>
752                 <dl>
753                         <dt><dfn id=eventdef-event-abort class=event-abort><strong>abort</strong></dfn>
754                         <dd>
755                         <table >
756                                 <tr><th><em>Type:</em><td>abort
757                                 <tr><th><em>Namespace:</em><td>TBD
758                                 <tr><th><em>Interface:</em><td><a href="http://www.w3.org/TR/DOM-Level-3-Events/events.html#Events-Event">Event</a>
759                                 <tr><th><em>Cancelable:</em><td>No
760                                 <tr><th><em>Bubbles:</em><td>Yes
761                                 <tr><th><em>Target:</em><td>Element
762                                 <tr><th><em>Context info:</em><td>None
763                         </table>
764                         <p>The <code title=event-abort>abort</code> event is fired when loading of the media
765                         element is canceled.
766                 </dl>
767         </div>
768
769         <div class='event-definition'>
770                 <dl>
771                         <dt><dfn id=eventdef-event-mediarendererror class=event-mediarendererror><strong>mediarendererror</strong></dfn>
772                         <dd>
773                         <table >
774                                 <tr><th><em>Type:</em><td>mediarendererror
775                                 <tr><th><em>Namespace:</em><td>TBD
776                                 <tr><th><em>Interface:</em><td><a href="http://www.w3.org/TR/DOM-Level-3-Events/events.html#Events-Event">Event</a>
777                                 <tr><th><em>Cancelable:</em><td>No
778                                 <tr><th><em>Bubbles:</em><td>Yes
779                                 <tr><th><em>Target:</em><td>Element
780                                 <tr><th><em>Context info:</em><td>None
781                         </table>
782                         <p>The <code title=event-mediarendererror>mediarendererror</code> event is fired if a
783                         non-fatal error occurs during media playback that prevents the media resource from being
784                         completely rendered. For example: media type is not supported, i.e. the resource
785                         contains one or more renderable substreams of types not supported by the user agent; a
786                         media format is not supported, i.e. a renderable substream of a type that's supported by
787                         the user agent contains media that can't be decoded; or media can't be rendered under
788                         current constraints. Here there's no problem with media types or formats but the
789                         resource can't be rendered anyway, possibly temporarily.
790                 </dl>
791         </div>
792
793         <div class='event-definition'>
794                 <dl>
795                         <dt><dfn id=eventdef-event-error class=event-error><strong>error</strong></dfn>
796                         <dd>
797                         <table >
798                                 <tr><th><em>Type:</em><td>error
799                                 <tr><th><em>Namespace:</em><td>TBD
800                                 <tr><th><em>Interface:</em><td><a href="http://www.w3.org/TR/DOM-Level-3-Events/events.html#Events-Event">Event</a>
801                                 <tr><th><em>Cancelable:</em><td>No
802                                 <tr><th><em>Bubbles:</em><td>Yes
803                                 <tr><th><em>Target:</em><td>Element
804                                 <tr><th><em>Context info:</em><td>None
805                         </table>
806                         <p>The <code title=event-error>error</code> event is fired if an error occurs during
807                         the loading of the media element. This event should not be fired if the loading was
808                         canceled; the abort error should be fired in that case.
809                 </dl>
810         </div>
811
812         <div class='event-definition'>
813                 <dl>
814                         <dt><dfn id=eventdef-event-load class=event-load><strong>load</strong></dfn>
815                         <dd>
816                         <table >
817                                 <tr><th><em>Type:</em><td>load
818                                 <tr><th><em>Namespace:</em><td>TBD
819                                 <tr><th><em>Interface:</em><td><a href="http://www.w3.org/TR/DOM-Level-3-Events/events.html#Events-Event">Event</a>
820                                 <tr><th><em>Cancelable:</em><td>No
821                                 <tr><th><em>Bubbles:</em><td>No
822                                 <tr><th><em>Target:</em><td>Element
823                                 <tr><th><em>Context info:</em><td>None
824                         </table>
825                         <p>The <code title=event-load>load</code> event is fired when the media resource is
826                         completely loaded by the client. It should only be fired if the data will remain
827                         available for the life span of the element. Video and audio elements should be
828                         excluded from consideration for the document "load" event.
829                 </dl>
830         </div>
831 <code title=event-load><a href=#eventdef-event-load">load</a></code>
832         <div class='event-definition'>
833                 <dl>
834                         <dt><dfn id=eventdef-event-ratechange class=event-ratechange><strong>ratechange</strong></dfn>
835                         <dd>
836                         <table >
837                                 <tr><th><em>Type:</em><td>ratechange
838                                 <tr><th><em>Namespace:</em><td>TBD
839                                 <tr><th><em>Interface:</em><td><a href="http://www.w3.org/TR/DOM-Level-3-Events/events.html#Events-Event">Event</a>
840                                 <tr><th><em>Cancelable:</em><td>No
841                                 <tr><th><em>Bubbles:</em><td>No
842                                 <tr><th><em>Target:</em><td>Element
843                                 <tr><th><em>Context info:</em><td>None
844                         </table>
845                         <p>The <code title=event-ratechange>ratechange</code> event is fired soon after the 
846                         <code title=dom-media-currentrate><a href="#currentrate">currentRate</a></code> property 
847                         is changed from its previous value. Inspect the object's currentRate property for the new rate
848                         value. To detect that playback is starting, check that the new 
849                         <code title=dom-media-currentrate><a href="#currentrate">currentRate</a></code> is
850                         non-zero; to detect that playback has paused, check that the new 
851                         <code title=dom-media-currentrate><a href="#currentrate">currentRate</a></code> is zero (0).
852                 </dl>
853         </div>
854
855         <div class='event-definition'>
856                 <dl>
857                 <dt><dfn id=eventdef-event-volumechange class=event-volumechange><strong>volumechange</strong></dfn>
858                         <dd>
859                         <table >
860                                 <tr><th><em>Type:</em><td>volumechange
861                                 <tr><th><em>Namespace:</em><td>TBD
862                                 <tr><th><em>Interface:</em><td><a href="http://www.w3.org/TR/DOM-Level-3-Events/events.html#Events-Event">Event</a>
863                                 <tr><th><em>Cancelable:</em><td>No
864                                 <tr><th><em>Bubbles:</em><td>No
865                                 <tr><th><em>Target:</em><td>Element
866                                 <tr><th><em>Context info:</em><td>None
867                         </table>
868                         <p>The <code title=event-volumechange>volumechange</code> event is fired after either
869                         the <code title=dom-media-volume><a href="#volume">volume</a></code>
870                         or the <code title=dom-media-muted><a href="#muted">muted</a></code> property has changed from its
871                         previous value. Inspect the object's properties for the new value.
872                 </dl>
873         </div>
874
875         <div class='event-definition'>
876                 <dl>
877                 <dt><dfn id=eventdef-event-durationchange class=event-durationchange><strong>durationchange</strong></dfn>
878                         <dd>
879                         <table >
880                                 <tr><th><em>Type:</em><td>durationchange
881                                 <tr><th><em>Namespace:</em><td>TBD
882                                 <tr><th><em>Interface:</em><td><a href="http://www.w3.org/TR/DOM-Level-3-Events/events.html#Events-Event">Event</a>
883                                 <tr><th><em>Cancelable:</em><td>No
884                                 <tr><th><em>Bubbles:</em><td>No
885                                 <tr><th><em>Target:</em><td>Element
886                                 <tr><th><em>Context info:</em><td>None
887                         </table>
888                         <p>The <code title=event-durationchange>durationchange</code> event is fired if the 
889                         <code title=dom-media-duration><a href="#duration">duration</a></code>
890                         property of the media element changes. One reason this might occur is when the 
891                         <code title=dom-media-duration><a href="#duration">duration</a></code> for the media element
892                         which was previously estimated becomes known during loading. It might change for 
893                         other reasons that are not defined here.
894                 </dl>
895         </div>
896
897         <div class='event-definition'>
898                 <dl>
899                 <dt><dfn id=eventdef-event-availabledurationchange class=event-availabledurationchange><strong>availabledurationchange</strong></dfn>
900                         <dd>
901                         <table >
902                                 <tr><th><em>Type:</em><td>availabledurationchange
903                                 <tr><th><em>Namespace:</em><td>TBD
904                                 <tr><th><em>Interface:</em><td><a href="http://www.w3.org/TR/DOM-Level-3-Events/events.html#Events-Event">Event</a>
905                                 <tr><th><em>Cancelable:</em><td>No
906                                 <tr><th><em>Bubbles:</em><td>No
907                                 <tr><th><em>Target:</em><td>Element
908                                 <tr><th><em>Context info:</em><td>None
909                         </table>
910                         <p>The <code title=event-availabledurationchange>availabledurationchange</code> 
911                         event is fired if the <code title=dom-media-availableduration><a href="#availableduration">availableduration</a></code>
912                         property of the media element changes. One reason this might occur is during progressive
913                         download as more media is downloaded. It might change for other reasons that are not
914                         defined here. 
915                 </dl>
916                 <p class="big-issue">How often should the availabledurationchange event fire? Too often and we
917                 waste a lot of cycles, too infrequently and the UI can get out of sync with reality.
918                 Specifying a minimum time interval, eg. "at least once a second", is wasteful in a long file
919                 when the play head is not near the available duration, but useful when the two are close...
920                 </p>
921         </div>
922
923         <div class='event-definition'>
924                 <dl>
925                 <dt><dfn id=eventdef-event-loop class=event-loop><strong>loop</strong></dfn>
926                         <dd>
927                         <table >
928                                 <tr><th><em>Type:</em><td>loop
929                                 <tr><th><em>Namespace:</em><td>TBD
930                                 <tr><th><em>Interface:</em><td><a href="http://www.w3.org/TR/DOM-Level-3-Events/events.html#Events-Event">Event</a>
931                                 <tr><th><em>Cancelable:</em><td>No
932                                 <tr><th><em>Bubbles:</em><td>No
933                                 <tr><th><em>Target:</em><td>Element
934                                 <tr><th><em>Context info:</em><td>None
935                         </table>
936                         <p>The <code title=event-loop>loop</code> event is fired when the media is playing 
937                         through a loop prior to its final loop according to its <code title=dom-media-loopcount>
938                         <a href="#loopcount">loopCount</a></code>.
939                 </dl>
940         </div>
941
942         <div class='event-definition'>
943                 <dl>
944                 <dt><dfn id=eventdef-event-playcomplete class=event-playcomplete><strong>playcomplete</strong></dfn>
945                         <dd>
946                         <table >
947                                 <tr><th><em>Type:</em><td>playcomplete
948                                 <tr><th><em>Namespace:</em><td>TBD
949                                 <tr><th><em>Interface:</em><td><a href="http://www.w3.org/TR/DOM-Level-3-Events/events.html#Events-Event">Event</a>
950                                 <tr><th><em>Cancelable:</em><td>No
951                                 <tr><th><em>Bubbles:</em><td>No
952                                 <tr><th><em>Target:</em><td>Element
953                                 <tr><th><em>Context info:</em><td>None
954                         </table>
955                         <p>The <code title=event-playcomplete>playcomplete</code> event is fired when the element
956                         automatically stops playback because it reaches the limit of playback (i.e., the value of the 
957                         <code title=dom-media-endtime><a href="#endtime">endTime</a></code>
958                         property if playing forward, <code title=dom-media-starttime><a href="#starttime">startTime</a></code>
959                         if playing backward) and the media is playing through its final repetition, according to its
960                         <code title=dom-media-loopcount><a href="#loopcount">loopCount</a></code>.
961                 </dl>
962         </div>
963
964         <div class='event-definition'>
965                 <dl>
966                 <dt><dfn id=eventdef-event-timejump class=event-timejump><strong>timejump</strong></dfn>
967                         <dd>
968                         <table >
969                                 <tr><th><em>Type:</em><td>timejump
970                                 <tr><th><em>Namespace:</em><td>TBD
971                                 <tr><th><em>Interface:</em><td><a href="http://www.w3.org/TR/DOM-Level-3-Events/events.html#Events-Event">Event</a>
972                                 <tr><th><em>Cancelable:</em><td>No
973                                 <tr><th><em>Bubbles:</em><td>No
974                                 <tr><th><em>Target:</em><td>Element
975                                 <tr><th><em>Context info:</em><td>None
976                         </table>
977                         <p>The <code title=event-timechange>timechange</code> event is fired when the media element's 
978                         current time changes by any other means than playback at the current rate. This can be either by an explicit
979                         change to the <code title=dom-media-currenttime><a href="#currenttime">currentTime</a></code>
980                         property (e.g., under script control) or by any other means than playback at the current rate. 
981                         In other words, this event is not fired during play back but is fired if the 
982                         <code title=dom-media-currenttime><a href="#currenttime">currentTime</a></code> 
983                         property is explicitly changed. Setting the <code title=dom-media-currenttime>
984                         <a href="#currenttime">currentTime</a></code> to its current value shall not fire the timechange event.
985                 </dl>
986         </div>
987
988
989         <h3 id=playback-events><span class=secno>3.2.</span> Media playback events</h3>
990         <div class='event-definition'>
991                 <dl>
992                 <dt><dfn id=eventdef-event-mediaunderstandable class=event-mediaunderstandable><strong>mediaunderstandable</strong></dfn>
993                         <dd>
994                         <table >
995                                 <tr><th><em>Type:</em><td>mediaunderstandable
996                                 <tr><th><em>Namespace:</em><td>TBD
997                                 <tr><th><em>Interface:</em><td><a href="http://www.w3.org/TR/DOM-Level-3-Events/events.html#Events-Event">Event</a>
998                                 <tr><th><em>Cancelable:</em><td>No
999                                 <tr><th><em>Bubbles:</em><td>No
1000                                 <tr><th><em>Target:</em><td>Element
1001                                 <tr><th><em>Context info:</em><td>None
1002                         </table>
1003                         <p>The <code title=event-mediaunderstandable>mediaunderstandable</code> event is 
1004                         fired when the element's <code title=dom-media-mediastatus>
1005                         <a href="#mediastatus">mediaStatus</a></code> transitions to or
1006                         past the UNDERSTANDABLE state. This indicates that attributes of the object that are
1007                         dependent upon the media resource or the loading of the resource (e.g., 
1008                         <code title=dom-media-duration><a href="#duration">duration</a></code>,
1009                         <code title=dom-media-availableduration><a href="#availableduration">availableDuration</a></code>,
1010                         <code title=dom-media-hasaudio><a href="#hasaudio">hasAudio</a></code>, etc)
1011                         can be retrieved. The UNDERSTANDABLE state does not
1012                         indicate that the element can render anything (e.g., drawing a frame if the media 
1013                         is visual or decoding audio if it has audio).
1014                 </dl>
1015         </div>
1016
1017         <div class='event-definition'>
1018                 <dl>
1019                 <dt><dfn id=eventdef-event-mediapresentable class=event-mediapresentable><strong>mediapresentable</strong></dfn>
1020                         <dd>
1021                         <table >
1022                                 <tr><th><em>Type:</em><td>mediapresentable
1023                                 <tr><th><em>Namespace:</em><td>TBD
1024                                 <tr><th><em>Interface:</em><td><a href="http://www.w3.org/TR/DOM-Level-3-Events/events.html#Events-Event">Event</a>
1025                                 <tr><th><em>Cancelable:</em><td>No
1026                                 <tr><th><em>Bubbles:</em><td>No
1027                                 <tr><th><em>Target:</em><td>Element
1028                                 <tr><th><em>Context info:</em><td>None
1029                         </table>
1030                         <p>The <code title=event-mediapresentable>mediapresentable</code> event is fired 
1031                         when the element's <code title=dom-media-mediastatus>
1032                         <a href="#mediastatus">mediaStatus</a></code> transitions to or past the
1033                         the PRESENTABLE state. This indicates that the media object can render something at
1034                         the current time (e.g., it can render the video frame at the current time). The
1035                         PRESENTABLE state does not however indicate that it has loaded sufficient media so
1036                         that setting the <code title=dom-media-currentrate><a href="#currentrate">currentRate</a></code>
1037                         property to a non-zero value will render anything more (video or audio).
1038
1039                 </dl>
1040         </div>
1041
1042         <div class='event-definition'>
1043                 <dl>
1044                 <dt><dfn id=eventdef-event-mediaplayable class=event-mediaplayable><strong>mediaplayable</strong></dfn>
1045                         <dd>
1046                         <table >
1047                                 <tr><th><em>Type:</em><td>mediaplayable
1048                                 <tr><th><em>Namespace:</em><td>TBD
1049                                 <tr><th><em>Interface:</em><td><a href="http://www.w3.org/TR/DOM-Level-3-Events/events.html#Events-Event">Event</a>
1050                                 <tr><th><em>Cancelable:</em><td>No
1051                                 <tr><th><em>Bubbles:</em><td>No
1052                                 <tr><th><em>Target:</em><td>Element
1053                                 <tr><th><em>Context info:</em><td>None
1054                         </table>
1055                         <p>The <code title=event-mediaplayable>mediaplayable</code> event is fired 
1056                         when the element's <code title=dom-media-mediastatus>
1057                         <a href="#mediastatus">mediaStatus</a></code> transitions to or past the
1058                         PLAYABLE state. This indicates the object has loaded sufficient media data so that
1059                         if the <code title=dom-media-currentrate><a href="#currentrate">currentRate</a></code>
1060                         is set to a non-zero value, time will advance. An example usage
1061                         would be not to allow the play button in a custom movie controller to take effect
1062                         unless this state or better has been reached.
1063                 </dl>
1064         </div>
1065
1066         <div class='event-definition'>
1067                 <dl>
1068                 <dt><dfn id=eventdef-event-mediacanplaythrough class=event-mediacanplaythrough><strong>mediacanplaythrough</strong></dfn>
1069                         <dd>
1070                         <table >
1071                                 <tr><th><em>Type:</em><td>mediacanplaythrough
1072                                 <tr><th><em>Namespace:</em><td>TBD
1073                                 <tr><th><em>Interface:</em><td><a href="http://www.w3.org/TR/DOM-Level-3-Events/events.html#Events-Event">Event</a>
1074                                 <tr><th><em>Cancelable:</em><td>No
1075                                 <tr><th><em>Bubbles:</em><td>No
1076                                 <tr><th><em>Target:</em><td>Element
1077                                 <tr><th><em>Context info:</em><td>None
1078                         </table>
1079                         <p>The <code title=event-mediacanplaythrough>mediacanplaythrough</code> event is 
1080                         fired when the element's <code title=dom-media-mediastatus>
1081                         <a href="#mediastatus">mediaStatus</a></code> transitions to
1082                         or past the PLAYTHROUGHOK state. This indicates the object has loaded sufficient
1083                         media data and playback conditions (e.g., download rates, data rate of the media,
1084                         playback rate) are sufficient to allow for uninterrupted playback (i.e., no stalls)
1085                         if the current playback rate is set to the value of <code title=dom-media-playrate>
1086                         <a href="#playrate">playRate</a></code>. 
1087                 </dl>
1088         </div>
1089
1090         <h2 id="window-additions"><span class="secno">4.</span> WindowHTML Additions</h2> 
1091
1092         <p>The <code><a href="#windowhtml">WindowHTML</a></code> object must
1093         provide the following constructors:
1094         
1095         <dl>
1096                 <dt><dfn id=audio-constructor title=dom-audio-constructor><code>Audio()</code></dfn>
1097                 
1098                 <dd>
1099                 <p>Constructs an <code><a href="#html-audio-element">
1100                 HTMLAudioElement</a></code> object (a new <code title=element-audio><a href="#audio">audio</a></code>
1101                 element).
1102
1103                 <dt><dfn id=video-constructor title=dom-video-constructor><code>Video()</code></dfn>
1104                 
1105                 <dt><dfn id=video-constructor-w title=dom-video-constructor-w><code>Video(in unsigned long <var
1106                 title="">width</var>)</code></dfn>
1107                 
1108                 <dt><dfn id=video-constructor-wh title=dom-video-constructor-wh><code>Video(in unsigned long <var
1109                 title="">width</var>, in unsigned long <var title="">height</var>)</code></dfn>
1110         
1111                 <dd>
1112                 <p>Constructs an <code><a href="#html-video-element">
1113                 HTMLVideoElement</a></code> object (a new
1114                 <code title=element-video><a href="#video">video</a></code> element). If the <var title="">width</var>
1115                 and <var title="">height</var> arguments are both present, the new object's <code title=video-element-width>
1116                 <a href="#dom-video-width">width</a></code> and <code title=video-element-height><a href="#dom-video-height">
1117                 height</a></code> content attributes must be set to <var title="">width</var> and
1118                 <var title="">height</var>. If only the <var title="">width</var> argument is present,
1119                 the new object's <code title=video-element-width><a href="#dom-video-width">width</a></code> content
1120                 attribute must be set to <var title="">width</var> and the <code title=video-element-height>
1121                 <a href="#dom-video-height">height</a></code> content attribute must be set to a value that 
1122                 maintains the media resource's intrinsic aspect ratio.
1123         </dl>
1124
1125
1126
1127         <h2 class=no-num id=references>References</h2>
1128
1129         <p>All references are normative unless marked "Informative".
1130
1131         <dl>
1132                 <dt id=refsCSS21>[CSS21]
1133
1134                 <dd><cite><a href="http://www.w3.org/TR/2006/WD-CSS21-20061106">
1135                         Cascading Style Sheets, level 2 revision 1 CSS 2.1 Specification
1136                 </a></cite>, 
1137                 H&aring;kon Wium Lie, Tantek &Ccedil;elik, Bert Bos, and Ian Hickson, Editors.
1138                 World Wide Web Consortium, 06&nbsp;Nov&nbsp;2006.
1139                 CSS 2.1 Specification is available at http://www.w3.org/TR/2006/WD-CSS21-20061106
1140                 
1141                 <dt id=refsRFC2046>[RFC2046]
1142                 
1143                 <dd><cite><a href="http://www.ietf.org/rfc/rfc2046">
1144                         Multipurpose Internet Mail Extensions (MIME) Part Two: Media Types
1145                 </a></cite>, 
1146                 N. Freed, N. Borenstein. IETF, November&nbsp;1996. 
1147                 RFC 2046 is available at http://www.ietf.org/rfc/rfc2046
1148                 
1149                 <dt id=refsRFC4281>[RFC4281]
1150                 
1151                 <dd><cite><a href="http://www.ietf.org/rfc/rfc4281">
1152                         The Codecs Parameter for "Bucket" Media Types
1153                 </a></cite>, 
1154                 R. Gellens, D. Singer, P. Frojdh. IETF, November&nbsp;2005. 
1155                 RFC 4281 is available at http://www.ietf.org/rfc/rfc4281
1156                 
1157         </dl>
1158
1159         
1160         <h2 class=no-num id=acknowledgements>Acknowledgements</h2>
1161                 <p class="big-issue">Coming soon</p>
1162         
1163 </body>
1164 </html>
1165