HTMLMediaElement

Media elements are used to present audio data, or video and audio data, to the user. This is referred to as media data in this section, since this section applies equally to media elements for audio or for video.


Supported Platform(s)

- BlackBerry OS 6.0+
- BlackBerry PlayBook 1.0+
- BlackBerry 10
- Ripple Emulator
View Supported Platform Table
APIBB5.0BB6.0BB7.0PB1.0PB2.0BB10Ripple
addTrack   Y Y Y Y YY
canPlayType   Y Y Y Y YY
load   Y Y Y Y YY
pause   Y Y Y Y YY
play   Y Y Y Y Y 
autoplay   Y Y Y Y YY
controls   Y Y Y Y YY
currentSRC   Y Y Y Y YY
currentTime   Y Y Y Y YY
defaultPlaybackRate   Y Y Y Y YY
duration   Y Y Y Y YY
ended   Y Y Y Y YY
error   Y Y Y Y YY
initialTime   Y Y Y Y YY
loop   Y Y Y Y YY
muted   Y Y Y Y YY
networkState   Y Y Y Y YY
paused   Y Y Y Y YY
playbackRate   Y Y Y Y YY
played   Y Y Y Y YY
preload   Y Y Y Y YY
readyState   Y Y Y Y YY
seekable   Y Y Y Y YY
seeking   Y Y Y Y YY
src   Y Y Y Y YY
startOffsetTime   Y Y Y Y YY
textTracks   Y Y Y Y YY
volume   Y Y Y Y YY
NETWORK_EMPTY   Y Y Y Y YY
NETWORK_IDLE   Y Y Y Y YY
NETWORK_LOADING   Y Y Y Y YY
NETWORK_NO_SOURCE   Y Y Y Y YY
HAVE_NOTHING   Y Y Y Y YY
HAVE_METADATA   Y Y Y Y YY
HAVE_CURRENT_DATA   Y Y Y Y YY
HAVE_FUTURE_DATA   Y Y Y Y YY
HAVE_ENOUGH_DATA   Y Y Y Y YY

Configuration Document Settings

To use all of the API described for this object, you must ensure the following settings are in your configuration document:

This API does not require a <feature> element to be declared in the configuration document of your BlackBerry WebWorks Application.

Permission Elements (PlayBook and BlackBerry 10+)
This API does not require a <permission> element to be declared in the configuration document of your BlackBerry WebWorks Application.

Functions



Functions

MutableTextTrack addTrack (kind : String, label : String, language : String)


Creates and returns a new MutableTextTrack object, which is also added to the media element's list of text tracks.


Supported Platforms
 - BlackBerry OS 6.0+
 - BlackBerry PlayBook 1.0+
 - BlackBerry 10
 - Ripple Emulator


Parameters
kind Kind is one of the following strings "subtitles", "captions", "descriptions", "chapters", "metadata"
label Text track label
language Language of the text track

String canPlayType (type : String)


Returns the empty string (a negative response), "maybe", or "probably" based on how confident the user agent is that it can play media resources of the given type.


Supported Platforms
 - BlackBerry OS 6.0+
 - BlackBerry PlayBook 1.0+
 - BlackBerry 10
 - Ripple Emulator


Parameters
type The media type you are trying to play, for example: "application/octet-stream;codecs=theora" would return an empty string.

Return:

A string indicating the likelyhood of being able to play the type


void load ()


Causes the element to reset and start selecting and loading a new media resource from scratch.


Supported Platforms
 - BlackBerry OS 6.0+
 - BlackBerry PlayBook 1.0+
 - BlackBerry 10
 - Ripple Emulator

void pause ()


Pause playback of the video.


Supported Platforms
 - BlackBerry OS 6.0+
 - BlackBerry PlayBook 1.0+
 - BlackBerry 10
 - Ripple Emulator

void play ()


Play the video. If the video has ended, the player will seek to the beginning and start again.


Supported Platforms
 - BlackBerry OS 6.0+
 - BlackBerry PlayBook 1.0+
 - BlackBerry 10

Properties

Boolean autoplay


If true, the user agent will automatically begin playback of the media resource as soon as it can do so without stopping.


Supported Platforms
 - BlackBerry OS 6.0+
 - BlackBerry PlayBook 1.0+
 - BlackBerry 10
 - Ripple Emulator

Boolean controls


Indicates that the author has not provided a scripted controller and would like the user agent to provide its own set of controls.


Supported Platforms
 - BlackBerry OS 6.0+
 - BlackBerry PlayBook 1.0+
 - BlackBerry 10
 - Ripple Emulator

readonly String currentSRC


The currentSrc IDL attribute is initially the empty string. If absolute URL in 'src' was obtained successfully, set the currentSrc attribute to absolute URL.


Supported Platforms
 - BlackBerry OS 6.0+
 - BlackBerry PlayBook 1.0+
 - BlackBerry 10
 - Ripple Emulator

Number currentTime


The currentTime attribute must, on getting, return the current playback position, expressed in seconds. On setting, the user agent must seek to the new value (which might raise an exception).


Supported Platforms
 - BlackBerry OS 6.0+
 - BlackBerry PlayBook 1.0+
 - BlackBerry 10
 - Ripple Emulator

Number defaultPlaybackRate


The defaultPlaybackRate attribute gives the desired speed at which the media resource is to play, as a multiple of its intrinsic speed. The attribute is mutable: on getting it must return the last value it was set to, or 1.0 if it hasn't yet been set; on setting the attribute must be set to the new value.


Supported Platforms
 - BlackBerry OS 6.0+
 - BlackBerry PlayBook 1.0+
 - BlackBerry 10
 - Ripple Emulator

readonly Number duration


The duration attribute must return the time of the end of the media resource, in seconds.


Supported Platforms
 - BlackBerry OS 6.0+
 - BlackBerry PlayBook 1.0+
 - BlackBerry 10
 - Ripple Emulator

readonly Boolean ended


The ended attribute must return true if the media element has ended playback and the direction of playback is forwards, and false otherwise.


Supported Platforms
 - BlackBerry OS 6.0+
 - BlackBerry PlayBook 1.0+
 - BlackBerry 10
 - Ripple Emulator

readonly MediaError | null error


Returns a MediaError object representing the current error state of the element. Returns null if there is no error.


Supported Platforms
 - BlackBerry OS 6.0+
 - BlackBerry PlayBook 1.0+
 - BlackBerry 10
 - Ripple Emulator

readonly Number initialTime


return the initial playback position, expressed in seconds.


Supported Platforms
 - BlackBerry OS 6.0+
 - BlackBerry PlayBook 1.0+
 - BlackBerry 10
 - Ripple Emulator

Boolean loop


If set to "true", the loop attribute indicates that the media element is to seek back to the start of the media resource upon reaching the end.


Supported Platforms
 - BlackBerry OS 6.0+
 - BlackBerry PlayBook 1.0+
 - BlackBerry 10
 - Ripple Emulator

Boolean muted


Must return true if the audio channels are muted and false otherwise.


Supported Platforms
 - BlackBerry OS 6.0+
 - BlackBerry PlayBook 1.0+
 - BlackBerry 10
 - Ripple Emulator

readonly Number | HTMLMediaElement.NETWORK_EMPTY | HTMLMediaElement.NETWORK_IDLE | HTMLMediaElement.NETWORK_LOADING | HTMLMediaElement.NETWORK_NO_SOURCE networkState


As media elements interact with the network, their current network activity is represented by the networkState attribute. On getting, it must return the current network state of the element


Supported Platforms
 - BlackBerry OS 6.0+
 - BlackBerry PlayBook 1.0+
 - BlackBerry 10
 - Ripple Emulator

readonly Boolean paused


The paused attribute represents whether the media element is paused or not. The attribute must initially be true.


Supported Platforms
 - BlackBerry OS 6.0+
 - BlackBerry PlayBook 1.0+
 - BlackBerry 10
 - Ripple Emulator

Number playbackRate


The playbackRate attribute gives the speed at which the media resource plays, as a multiple of its intrinsic speed. If it is not equal to the defaultPlaybackRate, then the implication is that the user is using a feature such as fast forward or slow motion playback. The attribute is mutable: on getting it must return the last value it was set to, or 1.0 if it hasn't yet been set; on setting the attribute must be set to the new value, and the playback must change speed (if the element is potentially playing).


Supported Platforms
 - BlackBerry OS 6.0+
 - BlackBerry PlayBook 1.0+
 - BlackBerry 10
 - Ripple Emulator

readonly TimeRanges played


The played attribute must return a new static normalized TimeRanges object that represents the ranges of the media resource, if any, that the user agent has so far rendered, at the time the attribute is evaluated.


Supported Platforms
 - BlackBerry OS 6.0+
 - BlackBerry PlayBook 1.0+
 - BlackBerry 10
 - Ripple Emulator

String preload


The preload attribute is intended to provide a hint to the user agent about what the author thinks will lead to the best user experience. The attribute may be ignored altogether, for example based on explicit user preferences or based on the available connectivity.

The preload attribute is an enumerated attribute. The following table lists the keywords and states for the attribute � the keywords in the left column map to the states in the cell in the second column on the same row as the keyword.

<table>l <thead><tr> <th>Keyword</th> <th>State</th> <th>Brief description</th> </tr></thead> <tbody> <tr> <td><code>none</code></td> <td>None</td> <td>Hints to the user agent that either the author does not expect the user to need the media resource, or that the server wants to minimise unnecessary traffic.</td> </tr> <tr> <td><code>metadata</code></td> <td>Metadata</td> <td>Hints to the user agent that the author does not expect the user to need the media resource, but that fetching the resource metadata (dimensions, first frame, track list, duration, etc) is reasonable.</td> </tr> <tr> <td><code>auto</code></td> <td>Automatic</td> <td>Hints to the user agent that the user agent can put the user\'s needs first without risk to the server, up to and including optimistically downloading the entire resource.</td> </tr> </tbody> </table>


Supported Platforms
 - BlackBerry OS 6.0+
 - BlackBerry PlayBook 1.0+
 - BlackBerry 10
 - Ripple Emulator

readonly Number | HTMLMediaElement.HAVE_NOTHING | HTMLMediaElement.HAVE_METADATA | HTMLMediaElement.HAVE_CURRENT_DATA | HTMLMediaElement.HAVE_FUTURE_DATA | HTMLMediaElement.HAVE_ENOUGH_DATA readyState


on getting, return the value described above that describes the current ready state of the media element.


Supported Platforms
 - BlackBerry OS 6.0+
 - BlackBerry PlayBook 1.0+
 - BlackBerry 10
 - Ripple Emulator

TimeRanges seekable


The seekable attribute must return a new static normalized TimeRanges object that represents the ranges of the media resource, if any, that the user agent is able to seek to, at the time the attribute is evaluated.


Supported Platforms
 - BlackBerry OS 6.0+
 - BlackBerry PlayBook 1.0+
 - BlackBerry 10
 - Ripple Emulator

Boolean seeking


Returns true if the user agent is currently seeking. The seeking attribute must initially have the value false.


Supported Platforms
 - BlackBerry OS 6.0+
 - BlackBerry PlayBook 1.0+
 - BlackBerry 10
 - Ripple Emulator

String src


The src content attribute on media elements gives the address of the media resource (video, audio) to show. The attribute, if present, must contain a valid non-empty URL potentially surrounded by spaces. If a src attribute of a media element is set or changed, the user agent must invoke the media element's media element load algorithm. (Removing the src attribute does not do this, even if there are source elements present).


Supported Platforms
 - BlackBerry OS 6.0+
 - BlackBerry PlayBook 1.0+
 - BlackBerry 10
 - Ripple Emulator

readonly Date startOffsetTime


The startOffsetTime attribute must return a new Date object representing the current timeline offset.


Supported Platforms
 - BlackBerry OS 6.0+
 - BlackBerry PlayBook 1.0+
 - BlackBerry 10
 - Ripple Emulator

readonly TextTrack[] textTracks


Returns the TextTrack objects of the text tracks in the media element's list of text tracks, in the same order as in the list of text tracks.


Supported Platforms
 - BlackBerry OS 6.0+
 - BlackBerry PlayBook 1.0+
 - BlackBerry 10
 - Ripple Emulator

Number volume


Return the playback volume of any audio portions of the media element, in the range 0.0 (silent) to 1.0 (loudest). Initially, the volume must be 1.0, but user agents may remember the last set value across sessions, on a per-site basis or otherwise, so the volume may start at other values. On setting, if the new value is in the range 0.0 to 1.0 inclusive, the attribute must be set to the new value.


Supported Platforms
 - BlackBerry OS 6.0+
 - BlackBerry PlayBook 1.0+
 - BlackBerry 10
 - Ripple Emulator

Constants

static Number NETWORK_EMPTY


The element has not yet been initialized. All attributes are in their initial states.


Supported Platforms
 - BlackBerry OS 6.0+
 - BlackBerry PlayBook 1.0+
 - BlackBerry 10
 - Ripple Emulator

static Number NETWORK_IDLE


The element's resource selection algorithm is active and has selected a resource, but it is not actually using the network at this time.


Supported Platforms
 - BlackBerry OS 6.0+
 - BlackBerry PlayBook 1.0+
 - BlackBerry 10
 - Ripple Emulator

static Number NETWORK_LOADING


The element's resource selection algorithm is active, but it has not yet found a resource to use.


Supported Platforms
 - BlackBerry OS 6.0+
 - BlackBerry PlayBook 1.0+
 - BlackBerry 10
 - Ripple Emulator

static Number NETWORK_NO_SOURCE


The user agent is actively trying to download data.


Supported Platforms
 - BlackBerry OS 6.0+
 - BlackBerry PlayBook 1.0+
 - BlackBerry 10
 - Ripple Emulator

static Number HAVE_NOTHING


No information regarding the media resource is available. No data for the current playback position is available. Media elements whose networkState attribute are set to NETWORK_EMPTY are always in the HAVE_NOTHING state.


Supported Platforms
 - BlackBerry OS 6.0+
 - BlackBerry PlayBook 1.0+
 - BlackBerry 10
 - Ripple Emulator

static Number HAVE_METADATA


Enough of the resource has been obtained that the duration of the resource is available. In the case of a video element, the dimensions of the video are also available. The API will no longer raise an exception when seeking. No media data is available for the immediate current playback position. The text tracks are ready.


Supported Platforms
 - BlackBerry OS 6.0+
 - BlackBerry PlayBook 1.0+
 - BlackBerry 10
 - Ripple Emulator

static Number HAVE_CURRENT_DATA


Data for the immediate current playback position is available, but either not enough data is available that the user agent could successfully advance the current playback position in the direction of playback at all without immediately reverting to the HAVE_METADATA state, or there is no more data to obtain in the direction of playback. For example, in video this corresponds to the user agent having data from the current frame, but not the next frame; and to when playback has ended.


Supported Platforms
 - BlackBerry OS 6.0+
 - BlackBerry PlayBook 1.0+
 - BlackBerry 10
 - Ripple Emulator

static Number HAVE_FUTURE_DATA


Data for the immediate current playback position is available, as well as enough data for the user agent to advance the current playback position in the direction of playback at least a little without immediately reverting to the HAVE_METADATA state. For example, in video this corresponds to the user agent having data for at least the current frame and the next frame. The user agent cannot be in this state if playback has ended, as the current playback position can never advance in this case.


Supported Platforms
 - BlackBerry OS 6.0+
 - BlackBerry PlayBook 1.0+
 - BlackBerry 10
 - Ripple Emulator

static Number HAVE_ENOUGH_DATA


All the conditions described for the HAVE_FUTURE_DATA state are met, and, in addition, the user agent estimates that data is being fetched at a rate where the current playback position, if it were to advance at the rate given by the defaultPlaybackRate attribute, would not overtake the available data before playback reaches the end of the media resource.


Supported Platforms
 - BlackBerry OS 6.0+
 - BlackBerry PlayBook 1.0+
 - BlackBerry 10
 - Ripple Emulator

Documentation generated by JsDoc Toolkit 2.4.0 on Mon Feb 11 2013 14:51:07 GMT-0500 (EST)