HTMLMediaElement Class Reference

Inherits from
HTMLElement : Element : Node
Availability
Available in Safari 3.1 and later.
Available in iOS 3.0 and later.

Overview

An abstract superclass for media classes that display audio or video in webpages. This class defines common properties and methods inherited by the HTMLAudioElement and HTMLVideoElement classes representing the HTML audio and video elements.

Handling Events

The different types of media events that can occur are described in Table 1.

Table 1  Media element events

Event

Description

abort

Sent when the browser stops fetching the media data before the media resource was completely downloaded.

canplay

Sent when the browser can resume playback of the media data, but estimates that if playback is 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

Sent when the browser estimates that if playback is 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.

durationchange

Sent when the duration property changes.

emptied

Sent when the media element network state changes to the NETWORK_EMPTY state.

ended

Sent when playback has stopped at the end of the media resource and the ended property is set to true.

error

Sent when an error occurs while fetching the media data. Use the error property to get the current error.

loadeddata

Sent when the browser can render the media data at the current playback position for the first time.

loadedmetadata

Sent when the browser knows the duration and dimensions of the media resource.

loadstart

Sent when the browser begins loading the media data.

pause

Sent when playback pauses after the pause method returns.

play

Sent when playback starts after the play method returns.

playing

Sent when playback starts.

progress

Sent when the browser is fetching the media data.

ratechange

Sent when either the defaultPlaybackRate or the playbackRate property changes.

seeked

Sent when the seeking property is set to false

seeking

Sent when the seeking property is set to true and there is time to send this event.

stalled

Sent when the browser is fetching media data but it has stopped arriving.

suspend

Sent when the browser suspends loading the media data and does not have the entire media resource downloaded.

timeupdate

Sent when the currentTime property changes as part of normal playback or because of some other condition.

volumechange

Sent when either the volume property or the muted property changes.

waiting

Sent when the browser stops playback because it is waiting for the next frame.

Tasks

Getting and Setting Properties

Getting State

Controlling Playback

Properties

autobuffer

A Boolean value that gives a hint to the browser that it should automatically buffer media when the webpage is loaded. (Deprecated. This property is replaced by the preload property.)

attribute boolean autobuffer;
Discussion

If true, the media data is automatically buffered; otherwise, it is not. The default value is true.

Availability

autoplay

A Boolean value that determines whether the media resource plays automatically when available.

attribute boolean autoplay
Discussion

If false, the media resource does not automatically play when loaded; otherwise, it does. The default value is false.

Availability

buffered

The time ranges of the media resource that have been downloaded. (read-only)

readonly attribute TimeRanges buffered
Availability

controls

A Boolean value that determines whether the playback controls appear.

attribute boolean controls
Discussion

On the desktop, if false (the default), the playback controls do not appear; otherwise, they do appear. On iOS, a native application is used to playback video in full screen; therefore, this property is ignored.

Availability

currentSrc

The absolute URL of the media resource. (read-only)

readonly attribute DOMString currentSrc
Discussion

This property is an empty string if the networkState property is NETWORK_EMPTY.

Availability

currentTime

The current playback position in seconds.

attribute float currentTime
Discussion

When you set this property, the media play head moves to the new location. An INVALID_STATE_ERR DOM exception is raised if there is no selected media resource when you set this property. An INDEX_SIZE_ERR DOM exception is raised if the specified time is not within the start and end times.

Availability

defaultPlaybackRate

The default rate used to play the media resource.

attribute float defaultPlaybackRate
Discussion

The value of this property is a multiple of the media resource’s intrinsic speed. The default value is 1.0.

Availability

duration

The length of the media resource in seconds. (read-only)

readonly attribute float duration
Discussion

This property is 0 if there is no media data available. This property is NaN if the duration is unknown. The value is positive infinity if the duration is known but is indefinite—for example, a live stream.

Availability

ended

A Boolean value that indicates whether the media played to the end. (read-only)

readonly attribute boolean ended
Discussion

If true, the video played to the end; otherwise, it did not.

Availability

error

The last error that occurred for this element. (read-only)

readonly attribute MediaError error
Availability

loop

A Boolean value that determines whether the playback should loop.

attribute boolean loop
Discussion

If true, the playback should loop; otherwise, it should not.

Availability

muted

A Boolean value that determines whether the audio content should be muted.

attribute boolean muted
Discussion

If true, the audio track is muted; otherwise, it is not.

Availability

networkState

The state of downloading the media resource. (read-only)

readonly attribute unsigned short networkState
Discussion

Possible values are described in “Network States.”

Availability

paused

A Boolean value that indicates whether the media is paused. (read-only)

readonly attribute boolean paused
Discussion

If true, the video is paused; otherwise, it is not.

Availability

playbackRate

The speed that the media resource is playing.

attribute float playbackRate
Discussion

The value of this property is a multiple of the media resource’s intrinsic speed. If set to 0.0, a NOT_SUPPORTED_ERR DOM exception is raised. The default value is 1.0.

Availability

played

The ranges of the media resource that was played. (read-only)

readonly attribute TimeRanges played
Availability

preload

A Boolean value that gives a hint to the browser that it should automatically preload media when the webpage is loaded.

attribute boolean preload;
Discussion

If true (the default), the media data might be automatically buffered; otherwise, it is not. This attribute is a hint to the browser, telling it your preferences. There is no guarantee that you get the behavior that you request.

Availability

readyState

The ready state of the media resource. (read-only)

readonly attribute unsigned short readyState
Discussion

Possible values are described in “Media Ready States.”

Availability

seekable

The ranges that can be played in a nonlinear fashion. (read-only)

readonly attribute TimeRanges seekable
Availability

seeking

A Boolean value that indicates whether the element is seeking. (read-only)

readonly attribute boolean seeking
Discussion

If true, the media resource is playing in a nonlinear fashion; otherwise, it is not.

Availability

src

The URI address of the media resource to play.

attribute DOMString src
Availability

startTime

The earliest possible time in seconds to start playback. (read-only)

readonly attribute float startTime
Availability

volume

The volume of the audio portion of the media element.

attribute float volume
Discussion

The value of this property must be in the range from 0.0 (silent) to 1.0 (loudest); otherwise, a INDEX_SIZE_ERR DOM exception is raised. The default value is 1.0.

Availability

Methods

canPlayType

Returns whether the media element supports the specified MIME type.

DOMString canPlayType (in DOMString type);
Return Value

The possible string values are: “no”, “probably” and “maybe”.

Availability
  • Available in Safari 4.0 and later.
  • Available in iOS 3.0 and later.

load

Starts loading the media resource.

void load ();
Availability
  • Available in Safari 3.1 and later.
  • Available in iOS 3.0 and later.

pause

Pauses the media playback if in progress.

void pause ();
Availability
  • Available in Safari 3.1 and later.
  • Available in iOS 3.0 and later.

play

Begins playing the media resource.

void play ();
Discussion

If the media resource is not available for playback, this method loads it.

Availability
  • Available in Safari 3.1 and later.
  • Available in iOS 3.0 and later.

Constants

Media Ready States

Possible values for the readyState property.

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;
Constants
HAVE_NOTHING

No media data is available for playback at the current time.

Available in Safari 4.0 and later.

Available in iOS 3.0 and later.

HAVE_METADATA

Enough of the media resource has been loaded to know the duration, and in the case of a video element, the dimensions.

Available in Safari 4.0 and later.

Available in iOS 3.0 and later.

HAVE_CURRENT_DATA

Data for the current playback position is available, but not enough to begin playback.

Available in Safari 4.0 and later.

Available in iOS 3.0 and later.

HAVE_FUTURE_DATA

Enough data is available to begin playback.

Available in Safari 4.0 and later.

Available in iOS 3.0 and later.

HAVE_ENOUGH_DATA

Enough data is available to play at the default playback rate to the end of the media resource without having to pause to rebuffer.

Available in Safari 4.0 and later.

Available in iOS 3.0 and later.

Network States

Possible values for the networkState property.

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;
Constants
NETWORK_EMPTY

The element is not initialized.

Available in Safari 4.0 and later.

Available in iOS 3.0 and later.

NETWORK_IDLE

The network connection is idle.

Available in Safari 4.0 and later.

Available in iOS 3.0 and later.

NETWORK_LOADING

The media resource is loading.

Available in Safari 4.0 and later.

Available in iOS 3.0 and later.

NETWORK_NO_SOURCE

No media resource was found.

Available in Safari 4.0 and later.

Available in iOS 3.0 and later.



© 2011 Apple Inc. All Rights Reserved. (Last updated: 2011-06-14)

Did this document help you? Yes It's good, but... Not helpful...