HTML/Elements/audio

From W3C Wiki
< HTML‎ | Elements
Revision as of 15:35, 26 April 2013 by Tparisot (Talk | contribs)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

<audio> Element

An <audio> element represents a sound or an audio stream.

HTML reference

This element was introduced in HTML5 - 4.8.7 The audio element.

Examples

An audio, using the user agent default set of controls, with one source [try it]:

<audio controls
  src="http://media.w3.org/2010/07/bunny/04-Death_Becomes_Fur.oga">
Your user agent does not support the HTML5 Audio element.
</audio>

Audio01.png

An audio, using the user agent default set of controls, with alternative sources [try it]:

<audio controls>
 <source src="http://media.w3.org/2010/07/bunny/04-Death_Becomes_Fur.mp4"
         type='audio/mp4'>
 <source src="http://media.w3.org/2010/07/bunny/04-Death_Becomes_Fur.oga"
         type='audio/ogg; codecs=vorbis'>
 <p>Your user agent does not support the HTML5 Audio element.</p>
</audio>

Audio02.png

An audio, with its own HTML control [try it]:

<audio id="myAudio"
 <source src="http://media.w3.org/2010/07/bunny/04-Death_Becomes_Fur.mp4"
         type='audio/mp4'>
 <source src="http://media.w3.org/2010/07/bunny/04-Death_Becomes_Fur.oga"
         type='audio/ogg; codecs=vorbis'>
 Your user agent does not support the HTML5 Audio element.
</audio>
<button type="button" onclick="aud_play_pause()">Play/Pause</button>
<script>
function aud_play_pause() {
  var myAudio = document.getElementById("myAudio");
  if (myAudio.paused) {
    myAudio.play();
  } else {
    myAudio.pause();
  }
}
</script>

Audio03.png

HTML Attributes

  • autoplay = "autoplay" or "" (empty string) or empty
    Instructs the UA to automatically begin playback of the audio stream as soon as it can do so without stopping.
  • preload = "none" or "metadata" or "auto" or "" (empty string) or empty
    Represents a hint to the UA about whether optimistic downloading of the audio stream itself or its metadata is considered worthwhile.
    • "none": Hints to the UA that the user is not expected to need the video, or that minimizing unnecessary traffic is desirable.
    • "metadata": Hints to the UA that the user is not expected to need the audio stream, but that fetching its metadata (duration and so on) is desirable.
    • "auto": Hints to the UA that optimistically downloading the entire audio stream is considered desirable.
      Specifying the empty string is equivalent to specifying the value "auto".
  • controls = "controls" or "" (empty string) or empty
    Instructs the UA to expose a user interface for controlling playback of the audio stream.
  • loop = "loop" or "" (empty string) or empty
    Instructs the UA to seek back to the start of the audio stream upon reaching the end.
  • mediagroup = string
    Instructs the UA to link multiple videos and/or audio streams together.
  • src = URL potentially surrounded by spaces
    The URL for the audio stream.

See also global attributes.

IDL Attributes and Methods

The following IDL attributes and methods are exposed to dynamic scripts.

  // error state
  readonly attribute MediaError error;

  // network state
           attribute DOMString src;
  readonly attribute DOMString currentSrc;
  const unsigned short NETWORK_EMPTY = 0;
  const unsigned short NETWORK_IDLE = 1;
  const unsigned short NETWORK_LOADING = 2;
  const unsigned short NETWORK_NO_SOURCE = 3;
  readonly attribute unsigned short networkState;
           attribute DOMString preload;
  readonly attribute TimeRanges buffered;
  void load();
  DOMString canPlayType(in DOMString type);

  // ready state
  const unsigned short HAVE_NOTHING = 0;
  const unsigned short HAVE_METADATA = 1;
  const unsigned short HAVE_CURRENT_DATA = 2;
  const unsigned short HAVE_FUTURE_DATA = 3;
  const unsigned short HAVE_ENOUGH_DATA = 4;
  readonly attribute unsigned short readyState;
  readonly attribute boolean seeking;

  // playback state
           attribute float currentTime;
  readonly attribute float startTime;
  readonly attribute float duration;
  readonly attribute boolean paused;
           attribute float defaultPlaybackRate;
           attribute float playbackRate;
  readonly attribute TimeRanges played;
  readonly attribute TimeRanges seekable;
  readonly attribute boolean ended;
           attribute boolean autoplay;
           attribute boolean loop;
  void play();
  void pause();

  // controls
           attribute boolean controls;
           attribute float volume;
           attribute boolean muted;

Note: Relating API is not a document yet.

Media Events

Event name Dispatched when...
loadstart The user agent begins looking for media data, as part of the resource selection algorithm.
progress The user agent is fetching media data.
suspend The user agent is intentionally not currently fetching media data, but does not have the entire media resource downloaded.
abort The user agent stops fetching the media data before it is completely downloaded, but not due to an error.
error An error occurs while fetching the media data.
emptied A media element whose networkState was previously not in the NETWORK_EMPTY state has just switched to that state (either because of a fatal error during load that's about to be reported, or because the load() method was invoked while the resource selection algorithm was already running).
stalled The user agent is trying to fetch media data, but data is unexpectedly not forthcoming.
play Playback has begun. Fired after the play() method has returned, or when the autoplay attribute has caused playback to begin.
pause Playback has been paused. Fired after the pause() method has returned.
loadedmetadata The user agent has just determined the duration and dimensions of the media resource
loadeddata The user agent can render the media data at the current playback position for the first time.
waiting Playback has stopped because the next frame is not available, but the user agent expects that frame to become available in due course.
playing Playback has started.
canplay The user agent can resume playback of the media data, but estimates that if playback were to be started now, the media resource could not be rendered at the current playback rate up to its end without having to stop for further buffering of content.
canplaythrough The user agent estimates that if playback were to be started now, the media resource could be rendered at the current playback rate all the way to its end without having to stop for further buffering.
seeking The seeking IDL attribute changed to true and the seek operation is taking long enough that the user agent has time to fire the event.
seeked The seeking IDL attribute changed to false.
timeupdate The current playback position changed as part of normal playback or in an especially interesting way, for example discontinuously.
ended Playback has stopped because the end of the media resource was reached.
ratechange Either the defaultPlaybackRate or the playbackRate attribute has just been updated.
durationchange The duration attribute has just been updated.
volumechange Either the volume attribute or the muted attribute has changed. Fired after the relevant attribute's setter has returned.

Accessibility

Authors should ensure that the information and user interface components must be presentable to users in ways they can perceive (WCAG 2.0 - Principle 1: Perceivable). This includes providing alternatives for time-based media Guideline 1.2.

Work in still in progress proper technical support in HTML5.

Formats and Codecs

The HTML5 specification does not require a specific audio codec to be supported by all user agents due to unclear licensing rights or rights that are not consistent with the W3C Royalty-free license. Thus, one need to provide alternate sources to ensure proper experience in the existing user agents. Using Ogg/Vorbis and MP4/AAC seems to cover most of the cases out there (if not all). See the wikipedia Audio format support.

See also

  1. Audio in the browser
  2. HTML5 Canvas and Audio Experiment
  3. HTML5 and Xiph codecs