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
API | OS 5.0 | OS 6.0 | OS 7.0 | PlayBook | Ripple |
---|---|---|---|---|---|
addTrack | Y | Y | Y | ||
canPlayType | Y | Y | Y | ||
load | Y | Y | Y | ||
pause | Y | Y | Y | ||
play | Y | Y | Y | ||
autoplay | Y | Y | Y | ||
controls | Y | Y | Y | ||
currentSRC | Y | Y | Y | ||
currentTime | Y | Y | Y | ||
defaultPlaybackRate | Y | Y | Y | ||
duration | Y | Y | Y | ||
ended | Y | Y | Y | ||
error | Y | Y | Y | ||
initialTime | Y | Y | Y | ||
loop | Y | Y | Y | ||
muted | Y | Y | Y | ||
networkState | Y | Y | Y | ||
paused | Y | Y | Y | ||
playbackRate | Y | Y | Y | ||
played | Y | Y | Y | ||
preload | Y | Y | Y | ||
readyState | Y | Y | Y | ||
seekable | Y | Y | Y | ||
seeking | Y | Y | Y | ||
src | Y | Y | Y | ||
startOffsetTime | Y | Y | Y | ||
textTracks | Y | Y | Y | ||
volume | Y | Y | Y | ||
NETWORK_EMPTY | Y | Y | Y | ||
NETWORK_IDLE | Y | Y | Y | ||
NETWORK_LOADING | Y | Y | Y | ||
NETWORK_NO_SOURCE | Y | Y | Y | ||
HAVE_NOTHING | Y | Y | Y | ||
HAVE_METADATA | Y | Y | Y | ||
HAVE_CURRENT_DATA | Y | Y | Y | ||
HAVE_FUTURE_DATA | Y | Y | Y | ||
HAVE_ENOUGH_DATA | Y | Y | Y |
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 Only) |
---|
This API does not require a <permission> element to be declared in the configuration document of your BlackBerry WebWorks Application. |
API Summary
Functions
Properties
addTrack
MutableTextTrack addTrack(kind : String, label : String, language : String) |
Supported Platform(s)
- BlackBerry OS 6.0+- BlackBerry PlayBook
Description
Creates and returns a new MutableTextTrack object, which is also added to the media element's list of text tracks.
Parameter | Type | Description |
---|---|---|
kind | String | Kind is one of the following strings "subtitles", "captions", "descriptions", "chapters", "metadata" |
label | String | Text track label |
language | String | Language of the text track |
canPlayType
void canPlayType(type : String) |
Supported Platform(s)
- BlackBerry OS 6.0+- BlackBerry PlayBook
Description
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.
Parameter | Type | Description |
---|---|---|
type | String | The media type you are trying to play, for example: "application/octet-stream;codecs=theora" would return an empty string. |
load
void load() |
Supported Platform(s)
- BlackBerry OS 6.0+- BlackBerry PlayBook
Description
Causes the element to reset and start selecting and loading a new media resource from scratch.
pause
void pause() |
Supported Platform(s)
- BlackBerry OS 6.0+- BlackBerry PlayBook
Description
Pause playback of the video.
play
void play() |
Supported Platform(s)
- BlackBerry OS 6.0+- BlackBerry PlayBook
Description
Play the video. If the video has ended, the player will seek to the beginning and start again.
Properties:
Property | Type | Description | Supported Platform(s) |
---|---|---|---|
autoplay | Boolean |
If true, the user agent will automatically begin playback of the media
resource as soon as it can do so without stopping.
|
- BlackBerry OS 6.0+
- BlackBerry PlayBook |
controls | Boolean |
Indicates that the author has not provided a scripted controller and
would like the user agent to provide its own set of controls.
|
- BlackBerry OS 6.0+
- BlackBerry PlayBook |
currentSRC |
String
readonly |
The currentSrc IDL attribute is initially the empty string. If
absolute URL in 'src' was obtained successfully, set the currentSrc
attribute to absolute URL.
|
- BlackBerry OS 6.0+
- BlackBerry PlayBook |
currentTime | Number |
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).
|
- BlackBerry OS 6.0+
- BlackBerry PlayBook |
defaultPlaybackRate | Number |
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.
|
- BlackBerry OS 6.0+
- BlackBerry PlayBook |
duration |
Number
readonly |
The duration attribute must return the time of the end of the media resource, in seconds.
|
- BlackBerry OS 6.0+
- BlackBerry PlayBook |
ended |
Boolean
readonly |
The ended attribute must return true if the media element has ended
playback and the direction of playback is forwards, and false
otherwise.
|
- BlackBerry OS 6.0+
- BlackBerry PlayBook |
error |
MediaError | null
readonly |
Returns a MediaError object representing the current error state of the element.
Returns null if there is no error.
|
- BlackBerry OS 6.0+
- BlackBerry PlayBook |
initialTime |
Number
readonly |
return the initial playback position, expressed in seconds.
|
- BlackBerry OS 6.0+
- BlackBerry PlayBook |
loop | Boolean |
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.
|
- BlackBerry OS 6.0+
- BlackBerry PlayBook |
muted | Boolean |
Must return true if the audio channels are muted and false otherwise.
|
- BlackBerry OS 6.0+
- BlackBerry PlayBook |
networkState |
Number | HTMLMediaElement.NETWORK_EMPTY | HTMLMediaElement.NETWORK_IDLE | HTMLMediaElement.NETWORK_LOADING | HTMLMediaElement.NETWORK_NO_SOURCE
readonly |
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
|
- BlackBerry OS 6.0+
- BlackBerry PlayBook |
paused |
Boolean
readonly |
The paused attribute represents whether the media element is paused or not. The attribute must initially be true.
|
- BlackBerry OS 6.0+
- BlackBerry PlayBook |
playbackRate | Number |
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).
|
- BlackBerry OS 6.0+
- BlackBerry PlayBook |
played |
TimeRanges
readonly |
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.
|
- BlackBerry OS 6.0+
- BlackBerry PlayBook |
preload | String |
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> |
- BlackBerry OS 6.0+
- BlackBerry PlayBook |
readyState |
Number | HTMLMediaElement.HAVE_NOTHING | HTMLMediaElement.HAVE_METADATA | HTMLMediaElement.HAVE_CURRENT_DATA | HTMLMediaElement.HAVE_FUTURE_DATA | HTMLMediaElement.HAVE_ENOUGH_DATA
readonly |
on getting, return the value described above that describes the
current ready state of the media element.
|
- BlackBerry OS 6.0+
- BlackBerry PlayBook |
seekable | TimeRanges |
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.
|
- BlackBerry OS 6.0+
- BlackBerry PlayBook |
seeking | Boolean |
Returns true if the user agent is currently seeking. The seeking
attribute must initially have the value false.
|
- BlackBerry OS 6.0+
- BlackBerry PlayBook |
src | String |
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).
|
- BlackBerry OS 6.0+
- BlackBerry PlayBook |
startOffsetTime |
Date
readonly |
The startOffsetTime attribute must return a new Date object representing the current timeline offset.
|
- BlackBerry OS 6.0+
- BlackBerry PlayBook |
textTracks |
TextTrack[]
readonly |
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.
|
- BlackBerry OS 6.0+
- BlackBerry PlayBook |
volume | Number |
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.
|
- BlackBerry OS 6.0+
- BlackBerry PlayBook |
Constants:
Property | Type | Description | Supported Platform(s) |
---|---|---|---|
NETWORK_EMPTY | Number |
The element has not yet been initialized. All attributes are in their
initial states.
|
- BlackBerry OS 6.0+
- BlackBerry PlayBook |
NETWORK_IDLE | Number |
The element's resource selection algorithm is active and has
selected a resource, but it is not actually using the network at this time.
|
- BlackBerry OS 6.0+
- BlackBerry PlayBook |
NETWORK_LOADING | Number |
The element's resource selection algorithm is active, but it has not
yet found a resource to use.
|
- BlackBerry OS 6.0+
- BlackBerry PlayBook |
NETWORK_NO_SOURCE | Number |
The user agent is actively trying to download data.
|
- BlackBerry OS 6.0+
- BlackBerry PlayBook |
HAVE_NOTHING | Number |
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.
|
- BlackBerry OS 6.0+
- BlackBerry PlayBook |
HAVE_METADATA | Number |
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.
|
- BlackBerry OS 6.0+
- BlackBerry PlayBook |
HAVE_CURRENT_DATA | Number |
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.
|
- BlackBerry OS 6.0+
- BlackBerry PlayBook |
HAVE_FUTURE_DATA | Number |
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.
|
- BlackBerry OS 6.0+
- BlackBerry PlayBook |
HAVE_ENOUGH_DATA | Number |
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.
|
- BlackBerry OS 6.0+
- BlackBerry PlayBook |