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.

  • autoplay Property

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

    Declaration

    attribute boolean autoplay

    Discussion

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

  • controls Property

    A Boolean value that determines whether the playback controls appear.

    Declaration

    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.

  • currentTime Property

    The current playback position in seconds.

    Declaration

    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.

  • The default rate used to play the media resource.

    Declaration

    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.

  • loop Property

    A Boolean value that determines whether the playback should loop.

    Declaration

    attribute boolean loop

    Discussion

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

  • muted Property

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

    Declaration

    attribute boolean muted

    Discussion

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

  • The speed that the media resource is playing.

    Declaration

    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.

  • 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

    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.

  • src Property

    The URI address of the media resource to play.

    Declaration

    attribute DOMString src

  • volume Property

    The volume of the audio portion of the media element.

    Declaration

    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.

  • buffered Property

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

    Declaration

    readonly attribute TimeRanges buffered

  • currentSrc Property

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

    Declaration

    readonly attribute DOMString currentSrc

    Discussion

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

  • duration Property

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

    Declaration

    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.

  • ended Property

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

    Declaration

    readonly attribute boolean ended

    Discussion

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

  • error Property

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

    Declaration

    readonly attribute MediaError error

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

    Declaration

    readonly attribute unsigned short networkState

    Discussion

    Possible values are described in Network States.

  • paused Property

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

    Declaration

    readonly attribute boolean paused

    Discussion

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

  • played Property

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

    Declaration

    readonly attribute TimeRanges played

  • readyState Property

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

    Declaration

    readonly attribute unsigned short readyState

    Discussion

    Possible values are described in Media Ready States.

  • seekable Property

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

    Declaration

    readonly attribute TimeRanges seekable

  • seeking Property

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

    Declaration

    readonly attribute boolean seeking

    Discussion

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

  • startTime Property

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

    Declaration

    readonly attribute float startTime

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

    Declaration

    DOMString canPlayType (in DOMString type);

    Return Value

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

  • Starts loading the media resource.

    Declaration

    void load ();

  • Pauses the media playback if in progress.

    Declaration

    void pause ();

  • Begins playing the media resource.

    Declaration

    void play ();

    Discussion

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

Constants

  • Possible values for the readyState property.

    Declaration

    Constants

    • HAVE_NOTHING

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

    • HAVE_METADATA

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

    • HAVE_CURRENT_DATA

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

    • HAVE_FUTURE_DATA

      Enough data is available to begin playback.

    • 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.

  • Possible values for the networkState property.

    Declaration

    Constants

    • NETWORK_EMPTY

      The element is not initialized.

    • NETWORK_IDLE

      The network connection is idle.

    • NETWORK_LOADING

      The media resource is loading.

    • NETWORK_NO_SOURCE

      No media resource was found.