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