Safari Developer Library

Developer

HTMLMediaElement Class Reference

Options
Deployment Target:

On This Page

HTMLMediaElement

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 1Media 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.

Inheritance


Conforms To


Not Applicable

Import Statement


Not Applicable Not Applicable

Availability


Available in Safari 3.1 and later.
Available in iOS 3.0 and later.
  • autoplay Property

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

    Declaration

    JavaScript

    attribute boolean autoplay

    Discussion

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

    Availability

    Available in Safari 3.1 and later.

    Available in iOS 3.0 and later.

  • controls Property

    A Boolean value that determines whether the playback controls appear.

    Declaration

    JavaScript

    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

    Available in Safari 3.1 and later.

    Available in iOS 3.0 and later.

  • currentTime Property

    The current playback position in seconds.

    Declaration

    JavaScript

    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

    Available in Safari 3.1 and later.

    Available in iOS 3.0 and later.

  • The default rate used to play the media resource.

    Declaration

    JavaScript

    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

    Available in Safari 3.1 and later.

    Available in iOS 3.0 and later.

  • loop Property

    A Boolean value that determines whether the playback should loop.

    Declaration

    JavaScript

    attribute boolean loop

    Discussion

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

    Availability

    Available in Safari 4.0 and later.

    Available in iOS 3.0 and later.

  • muted Property

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

    Declaration

    JavaScript

    attribute boolean muted

    Discussion

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

    Availability

    Available in Safari 3.1 and later.

    Available in iOS 3.0 and later.

  • playbackRate Property

    The speed that the media resource is playing.

    Declaration

    JavaScript

    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. Use this property to create custom controls for playback rate. Values greater than 1.0 fast-forward media and values less than 0.0 rewind. This property can not be set for HTML5 audio/video elements on iOS.

    Availability

    Available in Safari 3.1 and later.

    Available in iOS 3.0 and later.

  • preload Property

    A DOMString value that gives a hint to the browser how much of the media should be fetched when the webpage is loaded.

    Declaration

    JavaScript

    attribute DOMString preload

    Discussion

    Possible values are auto, metadata, and none. The attribute defaults to auto, suggesting to the browser the server is able to provide the media for immediate and agressive downloading. The metadata value suggests minimal server interaction to retrieve only metadata and the first frames of the media resource, while none suggests no server interaction is needed. These preload values can be changed dynamically. There is no guarantee that you get the behavior that you request.

    Availability

    Available in Safari 5.0 and later.

    Available in iOS 4.2 and later.

  • src Property

    The URI address of the media resource to play.

    Declaration

    JavaScript

    attribute DOMString src

    Availability

    Available in Safari 3.1 and later.

    Available in iOS 3.0 and later.

  • volume Property

    The volume of the audio portion of the media element.

    Declaration

    JavaScript

    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

    Available in Safari 3.1 and later.

    Available in iOS 3.0 and later.

  • buffered Property

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

    Declaration

    JavaScript

    readonly attribute TimeRanges buffered

    Availability

    Available in Safari 3.1 and later.

    Available in iOS 3.0 and later.

  • currentSrc Property

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

    Declaration

    JavaScript

    readonly attribute DOMString currentSrc

    Discussion

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

    Availability

    Available in Safari 3.1 and later.

    Available in iOS 3.0 and later.

  • duration Property

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

    Declaration

    JavaScript

    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

    Available in Safari 3.1 and later.

    Available in iOS 3.0 and later.

  • ended Property

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

    Declaration

    JavaScript

    readonly attribute boolean ended

    Discussion

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

    Availability

    Available in Safari 3.1 and later.

    Available in iOS 3.0 and later.

  • error Property

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

    Declaration

    JavaScript

    readonly attribute MediaError error

    Availability

    Available in Safari 3.1 and later.

    Available in iOS 3.0 and later.

  • networkState Property

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

    Declaration

    JavaScript

    readonly attribute unsigned short networkState

    Discussion

    Possible values are described in Network States.

    Availability

    Available in Safari 3.1 and later.

    Available in iOS 3.0 and later.

  • paused Property

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

    Declaration

    JavaScript

    readonly attribute boolean paused

    Discussion

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

    Availability

    Available in Safari 3.1 and later.

    Available in iOS 3.0 and later.

  • played Property

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

    Declaration

    JavaScript

    readonly attribute TimeRanges played

    Availability

    Available in Safari 3.1 and later.

    Available in iOS 3.0 and later.

  • readyState Property

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

    Declaration

    JavaScript

    readonly attribute unsigned short readyState

    Discussion

    Possible values are described in Media Ready States.

    Availability

    Available in Safari 3.1 and later.

    Available in iOS 3.0 and later.

  • seekable Property

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

    Declaration

    JavaScript

    readonly attribute TimeRanges seekable

    Availability

    Available in Safari 3.1 and later.

    Available in iOS 3.0 and later.

  • seeking Property

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

    Declaration

    JavaScript

    readonly attribute boolean seeking

    Discussion

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

    Availability

    Available in Safari 3.1 and later.

    Available in iOS 3.0 and later.

  • startTime Property

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

    Declaration

    JavaScript

    readonly attribute float startTime

    Availability

    Available in Safari 4.0 and later.

    Available in iOS 3.2 and later.

  • Returns whether the media element supports the specified MIME type.

    Declaration

    JavaScript

    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.

  • Starts loading the media resource.

    Declaration

    JavaScript

    void load ();

    Availability

    Available in Safari 3.1 and later.

    Available in iOS 3.0 and later.

  • Pauses the media playback if in progress.

    Declaration

    JavaScript

    void pause ();

    Availability

    Available in Safari 3.1 and later.

    Available in iOS 3.0 and later.

  • Begins playing the media resource.

    Declaration

    JavaScript

    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

  • Possible values for the readyState property.

    Declaration

    JavaScript

    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

      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

      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

      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

      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

      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.

  • Possible values for the networkState property.

    Declaration

    JavaScript

    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

      NETWORK_EMPTY

      The element is not initialized.

      Available in Safari 4.0 and later.

      Available in iOS 3.0 and later.

    • NETWORK_IDLE

      NETWORK_IDLE

      The network connection is idle.

      Available in Safari 4.0 and later.

      Available in iOS 3.0 and later.

    • NETWORK_LOADING

      NETWORK_LOADING

      The media resource is loading.

      Available in Safari 4.0 and later.

      Available in iOS 3.0 and later.

    • NETWORK_NO_SOURCE

      NETWORK_NO_SOURCE

      No media resource was found.

      Available in Safari 4.0 and later.

      Available in iOS 3.0 and later.