JavaScript API
4.3 Control Methods in the API
The following JavaScript control methods defined on media elements are explained in this section:
• load()
• play()
• pause()
• canPlayType() load()
The load() control method, when executed on a media element, causes all activity on a media resource to be suspended (including resource selection and loading, seeking and playback), all network activity to be seized, the element to be reset (including removal of pending callbacks and events), and the resource selection and loading process to be restarted.
In a typical scenario for a successful load(), roughly the following sequence of steps will happen:
• Initialization:
• @networkState is set to NETWORK_EMPTY.
• @readyState is set to HAVE_NOTHING.
• @paused is set to “true.”
• @seeking is set to “false.”
• @ended is set to “false.”
• @currentTime is set to 0.
• @error is set to null.
• @buffered, @played, and @seekable are set to empty.
• @playbackRate is set to the value of @defaultPlaybackRate.
• Resource selection:
• @currentSrc is set from the given @src value or the <source> elements.
• @networkState is set to NETWORK_LOADING.
• the loadstart event is fired.
• Resource fetching:
• begin downloading the media resource identified in the @currentSrc attribute.
http://freepdf-books.com
123
• progress event is fired roughly every 350ms or for every byte received (whichever is less frequent).
• @preload and @autoplay values help determine how much to download.
• when the resource's metadata has been downloaded:
@startTime is determined.
@currentTime is set to @startTime.
@duration is determined.
the durationchange event is fired.
@videoWidth and @videoHeight are determined (if video element).
@seekable is determined.
@readyState is set to HAVE_METADATA.
the loadedmetadata event is fired.
• seek to the appropriate start time given in the media resource or the
@currentSrc URI:
@currentTime is set to this start time.
the timeupdate event is fired.
• potentially more media data is downloaded (and decoded):
@readyState changes to HAVE_CURRENT_DATA or higher.
the loadeddata event is fired.
the canplay event is fired for any @readyState higher than HAVE_FUTURE_DATA.
@buffered is updated.
• @networkState is set to NETWORK_IDLE.
• playback start, if @autoplay is “true”:
• download more data until @readyState is HAVE_FUTURE_DATA or higher (preferably HAVE_ENOUGH_DATA so playback doesn't get stalled).
• @paused is set to “false.”
• the play event is fired.
• the playing event is fired.
• playback is started.
Note that many error and network state situations are also dealt with through the loading process.
For example, if the network download stalls and the browser hasn't received data for more than about 3 seconds, a stalled event will be fired.
Several previous examples in this chapter have made use of the load() control method; see e.g.
Listings 4–15 and 4–17. We will not include another example here.
http://freepdf-books.com
124 play()
The play() control method executed on a media element sets the @paused IDL attribute to “false”
and starts playback of the media resource, downloading and buffering media data as required.
In a typical scenario for a successful play(), roughly the following sequence of steps will happen:
• if @networkState is NETWORK_EMPTY—i.e. no @currentSrc has been determined yet (e.g. because the @src of the element was empty as the element was set up, but now the attribute was set through JavaScript and the resource can be fetched)—
“resource selection” and “resource fetching,” as described for load() above, are executed.
• if @ended is “true” and the playback direction is forward, the browser seeks to
@startTime.
• @currentTime is set to @startTime.
• timeupdate event is fired.
• “start playback” as described for load() above is executed.
We'll look at an example use of play() together with pause().
pause()
The pause() control method, when executed on a media element, sets the @paused IDL attribute to
“true” and stops playback of the media resource.
In a typical scenario for a successful pause(), roughly the following sequence of steps will happen:
if @networkState is NETWORK_EMPTY—i.e. no @currentSrc has been determined yet—“resource selection” and “resource fetching,” as described for load() above, are executed. @currentSrc may not have been determined yet because the @src of the element was empty as the element was set up, but now the attribute was set through JavaScript and the resource can be fetched.
• pause playback:
• @paused is set to “true.”
• timeupdate event is fired.
• pause event is fired.
• downloading of more media data is potentially suspended and a suspend event is fired if the browser is far ahead of the current playback position.
Listing 4–21 makes use of both, play() and pause(). At first, no media resource is specified for a video element. Then, we set the @src attribute, depending on what format a browser supports, and call play(). Later we call pause() halfway through playing. Figure 4–18 shows the results in the browsers.
Listing 4–21. Using the play() and pause() control methods for a media element <video controls width="400">
</video>
<p>currentSrc on start: <span id="currentSrc_first"></span>.</p>
<p>currentSrc after loadedmetadata:
<span id="currentSrc_loadedmetadata"></span>.</p>
<p>currentTime on pause: <span id="currentTime_pause"></span>.</p>
<script type="text/javascript">
video = document.getElementsByTagName("video")[0];
http://freepdf-books.com
125 source = document.getElementsByTagName("source");
span1 = document.getElementById("currentSrc_first");
span1.innerHTML = video.currentSrc;
if (video.canPlayType("video/ogg") != "") { video.src = "HelloWorld.ogv";
} else if (video.canPlayType("video/webm") != "") { video.src = "HelloWorld.webm";
} else if (video.canPlayType("video/mp4") != "") { video.src = "HelloWorld.mp4";
}
video.play();
span2 = document.getElementById("currentSrc_loadedmetadata");
function span2Update(evt) { span2.innerHTML = video.currentSrc; } function callpause(evt) {
if (video.currentTime > video.duration/2) { video.pause();
} }
span3 = document.getElementById("currentTime_pause");
function span3Update(evt) { span3.innerHTML = video.currentTime; } video.addEventListener("loadedmetadata", span2Update, false);
video.addEventListener("timeupdate", callpause, false);
video.addEventListener("pause", span3Update, false);
</script>
http://freepdf-books.com
126
Figure 4–18. Using the play() and pause() control methods in Firefox, Safari (top row), Opera, Chrome (middle row), and IE (bottom)
All browsers support this functionality.
canPlayType()
The canPlayType(in DOMString type) control method for a media element takes a string as a parameter that is of a MIME type and returns whether the browser is confident that it can play back that media type.
Possible return values are:
Download from www.eBookTM.Com
http://freepdf-books.com
127
• the empty string “”:
the browser is confident it cannot decode and render this type of media resource in a media element.
• "maybe":
the browser is not sure if it can or cannot render this type of media resource in a media element.
• "probably":
the browser is confident that it can decode and render this type of media resource in a media element; because this implies knowledge about whether the codecs in a container format are supported by the browser. Browsers are encouraged to only return “probably” for a MIME type that includes the codecs parameter.
The previous example in Listing 4–21 has made use of the canPlayType() control method, and it has also been used in Chapter 2 in Listings 2–28 and 2–29.
4.4 Events
In the following table we summarize all the available events, many of which we have already used in previous examples. This is just an overview table to find everything in one place.
Event Is dispatched when... Preconditions loadstart the browser begins looking for media data, as
part of the resource selection upon media element load, or load(), play(), or pause().
@networkState is NETWORK_LOADING for the first time.
progress the browser is fetching media data. @networkState is NETWORK_LOADING.
suspend the browser has paused fetching media data, but does not have the entire media resource downloaded yet.
@networkState is NETWORK_IDLE.
abort the browser was stopped from fetching the media data before it is completely
downloaded, but not due to an error—rather due to a user action, such as browsing away.
@error is MEDIA_ERR_ABORTED.
@networkState is either
NETWORK_EMPTY or NETWORK_IDLE, depending on when the download was aborted.
error an error occurred while fetching the media data.
@error is MEDIA_ERR_NETWORK or higher. @networkState is either NETWORK_EMPTY or NETWORK_IDLE, depending on when the download was aborted.
http://freepdf-books.com
128
Event Is dispatched when... Preconditions emptied a media element has just lost the network
connection to a media resource, 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.
@networkState is NETWORK_EMPTY for the first time and all the IDL attributes are in their initial states.
stalled the browser tried to fetch media data, but data has not arrived for more than 3 seconds.
@networkState is NETWORK_LOADING.
play playback has begun upon media element load with an @autoplay attribute through user interaction or after the play() method has returned.
@paused is newly “false.”
pause playback has been paused either through user interaction, or after the pause() method has returned.
@paused is newly “true”.
loadedmetadata the browser has just set up the decoding pipeline for the media resource and determined the @duration and dimensions.
@readyState is HAVE_METADATA or greater for the first time.
loadeddata the browser can render the media data at the current playback position for the first time.
@readyState is HAVE_CURRENT_DATA or greater for the first time.
waiting playback has stopped because the next media data is not yet available from the network, but the browser expects that frame to become available in due course; i.e. less than 3 seconds.
This can be after a seek or when the network is unexpectedly slow.
@readyState is newly equal to or less than HAVE_CURRENT_DATA, and
@paused is “false.” Either @seeking is
“true,” or the current playback position is not contained in any of the ranges in @buffered.
playing playback has started. @readyState is newly equal to or
greater than HAVE_FUTURE_DATA,
@paused is “false,” @seeking is
“false,” or the current playback position is contained in one of the ranges in @buffered.
canplay the browser can start or resume playback of the media resource, but without being certain of being able to play through at the given playback rate without a need for further buffering.
@readyState newly increased to HAVE_FUTURE_DATA or greater.
http://freepdf-books.com
129 Event Is dispatched when... Preconditions
canplaythrough the browser is certain that with the given media data, the rate at which the network delivers further media data and the given playback rate, the media resource can play through without further buffering.
@readyState is newly equal to HAVE_ENOUGH_DATA.
seeking the browser is seeking and the seek operation is taking long enough that the browser has time to fire the event.
@seeking is “true” and @readyState is less than HAVE_FUTURE_DATA.
seeked the browser is finished seeking. @seeking has changed to “false.”
timeupdate the current playback position changed as part of normal playback every 15 to 250ms. It is also fired when seeking, or when fetching a new media resource. It is also fired when playback has ended, is paused, is stopped due to an error or because the media resource needs to buffer from the network.
@seeking is newly “true” OR
@startTime is newly set OR @ended is newly “true” OR @paused is newly
“true” OR @readyState newly changed to a value lower than HAVE_FUTURE_DATA without @ended is “true” OR @error is newly non-null with @readyState being
HAVE_METADATA or more OR @seeking is “false,” @paused is “false,” @ended is “false,” @readyState is at least HAVE_FUTURE_DATA, and the last timeupdate was fired more than 15-250ms ago
ended playback has stopped because the end of the media resource was reached.
@ended is newly “true” and
@currentTime is equal to @startTime plus @duration.
ratechange either the default playback rate or the playback rate has just been updated.
@defaultPlaybackRate or
@playbackRate is newly changed.
durationchange the duration has just been changed upon media element load, or after an explicit change of @src and media resource fetching, or when the browser has a better estimate; e.g. during streaming.
@readyState is HAVE_METADATA or greater for the first time.
volumechange either the volume or the muted state of the media element changed.
@volume or @muted changed.
http://freepdf-books.com
130