Revision 901863 of Media events

<p>Various events are sent when handling media that are embedded in HTML documents using the {{ HTMLElement("audio") }} and {{ HTMLElement("video") }} elements; this section lists them and provides some helpful information about using them.</p>

<table class="standard-table">
 <tbody>
  <tr>
   <th>Event name</th>
   <th>Description</th>
  </tr>
  <tr>
   <td><code>abort</code></td>
   <td>Sent when playback is aborted; for example, if the media is playing and is restarted from the beginning, this event is sent.</td>
  </tr>
  <tr>
   <td><code>{{event("canplay")}}</code></td>
   <td>Sent when enough data is available that the media can be played, at least for a couple of frames.&nbsp; This corresponds to the <code>HAVE_ENOUGH_DATA</code>&nbsp;<code>readyState</code>.</td>
  </tr>
  <tr>
   <td><code>{{event("canplaythrough")}}</code></td>
   <td>Sent when the ready state changes to <code>CAN_PLAY_THROUGH</code>, indicating that the entire media can be played without interruption, assuming the download rate remains at least at the current level. <strong>Note</strong>: Manually setting the <code>currentTime</code> will eventually fire a <code>canplaythrough</code> event in firefox. Other browsers might not fire this event.</td>
  </tr>
  <tr>
   <td><code>{{event("durationchange")}}</code></td>
   <td>The metadata has loaded or changed, indicating a change in duration of the media.&nbsp; This is sent, for example, when the media has loaded enough that the duration is known.</td>
  </tr>
  <tr>
   <td><code>{{event("emptied")}}</code></td>
   <td>The media has become empty; for example, this event is sent if the media has already been loaded (or partially loaded), and the <a class="internal" href="/En/XPCOM_Interface_Reference/NsIDOMHTMLMediaElement" title="en/nsIDOMHTMLMediaElement"><code>load()</code></a>&nbsp;method is called to reload it.</td>
  </tr>
  <tr>
   <td>encrypted&nbsp;<span style="line-height:1.5">{{experimental_inline}}</span></td>
   <td>The user agent has encountered initialization data in the media data.</td>
  </tr>
  <tr>
   <td><code>ended</code></td>
   <td>Sent when playback completes.</td>
  </tr>
  <tr>
   <td><code>error</code></td>
   <td>Sent when an error occurs.&nbsp; The element's <code>error</code> attribute contains more information. See <a href="/en-US/docs/Web/Guide/HTML/Using_HTML5_audio_and_video#Error_handling">Error handling</a> for details.</td>
  </tr>
  <tr>
   <td><code>interruptbegin</code></td>
   <td>Sent when audio playing on a Firefox OS device is interrupted, either because the app playing the audio is sent to the background, or audio in a higher priority audio channel begins to play. See <a href="/en-US/docs/Web/API/AudioChannels_API/Using_the_AudioChannels_API">Using the AudioChannels API</a> for more details.</td>
  </tr>
  <tr>
   <td><code>interruptend</code></td>
   <td>Sent when previously interrupted audio on a Firefox OS device commences playing again — when the interruption ends. This is when the associated app comes back to the foreground, or when the higher priority audio finished playing. See <a href="/en-US/docs/Web/API/AudioChannels_API/Using_the_AudioChannels_API">Using the AudioChannels API</a> for more details.</td>
  </tr>
  <tr>
   <td><code>{{event("loadeddata")}}</code></td>
   <td>The first frame of the media has finished loading.</td>
  </tr>
  <tr>
   <td><code>{{event("loadedmetadata")}}</code></td>
   <td>The media's metadata has finished loading; all attributes now contain as much useful information as they're going to.</td>
  </tr>
  <tr>
   <td><code>{{event("loadstart")}}</code></td>
   <td>Sent when loading of the media begins.</td>
  </tr>
  <tr>
   <td><code>mozaudioavailable</code></td>
   <td>Sent when an audio buffer is provided to the audio layer for processing; the buffer contains raw audio samples that may or may not already have been played by the time you receive the event.</td>
  </tr>
  <tr>
   <td><code>{{event("pause")}}</code></td>
   <td>Sent when playback is paused.</td>
  </tr>
  <tr>
   <td><code>{{event("play")}}</code></td>
   <td>Sent when playback of the media starts after having been paused; that is, when playback is resumed after a prior <code>pause</code> event.</td>
  </tr>
  <tr>
   <td><code>{{event("playing")}}</code></td>
   <td>Sent when the media begins to play (either for the first time, after having been paused, or after ending and then restarting).</td>
  </tr>
  <tr>
   <td><code>{{event("progress")}}</code></td>
   <td>Sent periodically to inform interested parties of progress downloading the media. Information about the current amount of the media that has been downloaded is available in the media element's <code>buffered</code> attribute.</td>
  </tr>
  <tr>
   <td><code>{{event("ratechange")}}</code></td>
   <td>Sent when the playback speed changes.</td>
  </tr>
  <tr>
   <td><code>{{event("seeked")}}</code></td>
   <td>Sent when a seek operation completes.</td>
  </tr>
  <tr>
   <td><code>{{event("seeking")}}</code></td>
   <td>Sent when a seek operation begins.</td>
  </tr>
  <tr>
   <td><code>{{event("stalled")}}</code></td>
   <td>Sent when the user agent is trying to fetch media data, but data is unexpectedly not forthcoming.</td>
  </tr>
  <tr>
   <td><code>{{event("suspend")}}</code></td>
   <td>Sent when loading of the media is suspended; this may happen either because the download has completed or because it has been paused for any other reason.</td>
  </tr>
  <tr>
   <td><code>{{event("timeupdate")}}</code></td>
   <td>The time indicated by the element's <code>currentTime</code> attribute has changed.</td>
  </tr>
  <tr>
   <td><code>{{event("volumechange")}}</code></td>
   <td>Sent when the audio volume changes (both when the volume is set and when the <code>muted</code> attribute is changed).</td>
  </tr>
  <tr>
   <td><code>{{event("waiting")}}</code></td>
   <td>Sent when the requested operation (such as playback) is delayed pending the completion of another operation (such as a seek).</td>
  </tr>
 </tbody>
</table>

<p>You can easily watch for these events, using code such as the following:</p>

<pre class="brush: js">
var v = document.getElementsByTagName("video")[0];
v.addEventListener("seeked", function() { document.getElementsByTagName("video")[0].play(); }, true);
v.currentTime = 10.0;
</pre>

<p>This example fetches the first video element in the document and attaches an event listener to it, watching for the <code>seeked</code> event, which is sent whenever a seek operation completes.&nbsp; The listener simply calls the element's <code>play()</code> method, which starts playback.</p>

<p>Then, in line 3, the example sets the element's <code>currentTime</code> attribute to 10.0, which initiates a seek operation to the 10-second mark in the media.&nbsp; This causes a <code>seeking</code> event to be sent when the operation begins, then a <code>seeked</code> event to be dispatched when the seek is completed.</p>

<p>In other words, this example seeks to the 10-second mark in the media, then begins playback as soon as that's finished.</p>

<h2 id="Compatibility">Compatibility</h2>

<p>{{ CompatibilityTable() }}</p>

<div id="compat-desktop">
<table class="compat-table">
 <tbody>
  <tr>
   <th>Feature</th>
   <th>Chrome</th>
   <th>Firefox (Gecko)</th>
   <th>Internet Explorer</th>
   <th>Opera</th>
   <th>Safari</th>
  </tr>
  <tr>
   <td>Basic support</td>
   <td>{{ CompatUnknown() }}</td>
   <td>{{ CompatGeckoDesktop("1.9.1") }} (Prior to Gecko 2.0, media events bubbled.)</td>
   <td>{{ CompatUnknown() }}</td>
   <td>{{ CompatUnknown() }}</td>
   <td>{{ CompatUnknown() }}</td>
  </tr>
  <tr>
   <td>encrypted</td>
   <td>
    <p class="p1">{{CompatChrome(42.0)}}</p>
   </td>
   <td><span style="font-size:12px; line-height:16.3636360168457px">{{ CompatUnknown() }}</span></td>
   <td><span style="font-size:12px; line-height:16.3636360168457px">{{ CompatUnknown() }}</span></td>
   <td><span style="font-size:12px; line-height:16.3636360168457px">{{ CompatUnknown() }}</span></td>
   <td><span style="font-size:12px; line-height:16.3636360168457px">{{ CompatUnknown() }}</span></td>
  </tr>
  <tr>
   <td>load</td>
   <td>{{ CompatUnknown() }}</td>
   <td>Removed in {{ CompatGeckoDesktop("1.9.2") }}</td>
   <td>{{ CompatUnknown() }}</td>
   <td>{{ CompatUnknown() }}</td>
   <td>{{ CompatUnknown() }}</td>
  </tr>
  <tr>
   <td>mozaudioavailable {{ non-standard_inline() }}</td>
   <td>{{ CompatNo() }}</td>
   <td>{{ CompatGeckoDesktop("2.0") }}</td>
   <td>{{ CompatNo() }}</td>
   <td>{{ CompatNo() }}</td>
   <td>{{ CompatNo() }}</td>
  </tr>
  <tr>
   <td>suspend</td>
   <td>{{ CompatUnknown() }}</td>
   <td>{{ CompatGeckoDesktop("1.9.2") }}</td>
   <td>{{ CompatUnknown() }}</td>
   <td>{{ CompatUnknown() }}</td>
   <td>{{ CompatUnknown() }}</td>
  </tr>
 </tbody>
</table>
</div>

<div id="compat-mobile">
<table class="compat-table">
 <tbody>
  <tr>
   <th>Feature</th>
   <th>Android</th>
   <th>Android Webview</th>
   <th>Firefox Mobile (Gecko)</th>
   <th>IE Mobile</th>
   <th>Opera Mobile</th>
   <th>Safari Mobile</th>
   <th>Chrome for Android</th>
  </tr>
  <tr>
   <td>Basic support</td>
   <td>{{ CompatUnknown() }}</td>
   <td>{{ CompatUnknown() }}</td>
   <td>{{ CompatUnknown() }}</td>
   <td>{{ CompatUnknown() }}</td>
   <td>{{ CompatUnknown() }}</td>
   <td>{{ CompatUnknown() }}</td>
   <td><span style="font-size:12px; line-height:16.3636360168457px">{{ CompatUnknown() }}</span></td>
  </tr>
  <tr>
   <td>encrypted</td>
   <td><span style="font-size:12px; line-height:16.3636360168457px">{{ CompatNo }}</span></td>
   <td>{{CompatChrome(43.0)}}</td>
   <td><span style="font-size:12px; line-height:16.3636360168457px">{{ CompatUnknown() }}</span></td>
   <td><span style="font-size:12px; line-height:16.3636360168457px">{{ CompatUnknown() }}</span></td>
   <td><span style="font-size:12px; line-height:16.3636360168457px">{{ CompatUnknown() }}</span></td>
   <td><span style="font-size:12px; line-height:16.3636360168457px">{{ CompatUnknown() }}</span></td>
   <td>
    <p class="p1">{{CompatChrome(42.0)}}</p>
   </td>
  </tr>
  <tr>
   <td>load</td>
   <td>{{ CompatUnknown() }}</td>
   <td>{{ CompatUnknown() }}</td>
   <td>{{ CompatUnknown() }}</td>
   <td>{{ CompatUnknown() }}</td>
   <td>{{ CompatUnknown() }}</td>
   <td>{{ CompatUnknown() }}</td>
   <td><span style="font-size:12px; line-height:16.3636360168457px">{{ CompatUnknown() }}</span></td>
  </tr>
  <tr>
   <td>mozaudioavailable {{ non-standard_inline() }}</td>
   <td>{{ CompatNo() }}</td>
   <td>{{ CompatUnknown() }}</td>
   <td>{{ CompatGeckoMobile("2.0") }}</td>
   <td>{{ CompatNo() }}</td>
   <td>{{ CompatNo() }}</td>
   <td>{{ CompatNo() }}</td>
   <td><span style="font-size:12px; line-height:16.3636360168457px">{{ CompatUnknown() }}</span></td>
  </tr>
  <tr>
   <td>suspend</td>
   <td>{{ CompatUnknown() }}</td>
   <td>{{ CompatUnknown() }}</td>
   <td>{{ CompatUnknown() }}</td>
   <td>{{ CompatUnknown() }}</td>
   <td>{{ CompatUnknown() }}</td>
   <td>{{ CompatUnknown() }}</td>
   <td><span style="font-size:12px; line-height:16.3636360168457px">{{ CompatUnknown() }}</span></td>
  </tr>
 </tbody>
</table>
</div>

<p>&nbsp;</p>