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