Audio Player
The audio player is an API introduced so that audio can be played on the BlackBerry 5.0 operating system since the
HTML5 <audio> element is not yet supported on this OS. The audio player is intended to play audio files only
which does not include streaming audio.
It is recommended that you use the HTML5 <audio> element on BlackBerry Operating Systems with versions higher than OS 5.0 as well as on the Tablet OS.
The audio Player object is an instance object; if a new instance is desired, it must be created using the new keyword.
Supported Platform(s)
- BlackBerry OS 5.0+ |
- Ripple Emulator |
API | BB5.0 | BB6.0 | BB7.0 | PB1.0 | PB2.0 | BB10 | Ripple |
---|---|---|---|---|---|---|---|
blackberry.audio.Player | Y | Y | Y | Y | |||
blackberry.audio.Player.addPlayerListener | Y | Y | Y | Y | |||
blackberry.audio.Player.close | Y | Y | Y | Y | |||
blackberry.audio.Player.pause | Y | Y | Y | Y | |||
blackberry.audio.Player.play | Y | Y | Y | Y | |||
EVENT_BUFFERING_STARTED | Y | Y | Y | Y | |||
EVENT_BUFFERING_STOPPED | Y | Y | Y | Y | |||
EVENT_CLOSED | Y | Y | Y | Y | |||
EVENT_DEVICE_AVAILABLE | Y | Y | Y | Y | |||
EVENT_DEVICE_UNAVAILABLE | Y | Y | Y | Y | |||
EVENT_DURATION_UPDATED | Y | Y | Y | Y | |||
EVENT_END_OF_MEDIA | Y | Y | Y | Y | |||
EVENT_ERROR | Y | Y | Y | Y | |||
EVENT_RECORD_ERROR | Y | Y | Y | Y | |||
EVENT_RECORD_STARTED | Y | Y | Y | Y | |||
EVENT_RECORD_STOPPED | Y | Y | Y | Y | |||
EVENT_SIZE_CHANGED | Y | Y | Y | Y | |||
EVENT_STARTED | Y | Y | Y | Y | |||
EVENT_STOPPED | Y | Y | Y | Y | |||
EVENT_STOPPED_AT_TIME | Y | Y | Y | Y | |||
EVENT_VOLUME_CHANGED | Y | Y | Y | Y | |||
duration | Y | Y | Y | Y | |||
mediaTime | Y | Y | Y | Y | |||
state | Y | Y | Y | Y | |||
volumeLevel | Y | Y | Y | Y | |||
TIME_UNKNOWN | Y | Y | Y | Y | |||
CLOSED | Y | Y | Y | Y | |||
UNREALIZED | Y | Y | Y | Y | |||
REALIZED | Y | Y | Y | Y | |||
PREFETCHED | Y | 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: |
You must declare the feature element(s) below in your configuration document: |
Feature ID | BB5.0 | BB6.0 | BB7.0 | PB1.0 | PB2.0 | BB10 | Ripple |
---|---|---|---|---|---|---|---|
<feature id="blackberry.audio.Player" /> | Y | Y | Y | Y |
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. |
Constructors
Functions
Boolean | blackberry.audio.Player.addPlayerListener |
Boolean | blackberry.audio.Player.close |
Boolean | blackberry.audio.Player.pause |
Boolean | blackberry.audio.Player.play |
Properties
String | EVENT_BUFFERING_STARTED |
String | EVENT_BUFFERING_STOPPED |
String | EVENT_CLOSED |
String | EVENT_DEVICE_AVAILABLE |
String | EVENT_DEVICE_UNAVAILABLE |
String | EVENT_DURATION_UPDATED |
String | EVENT_END_OF_MEDIA |
String | EVENT_ERROR |
String | EVENT_RECORD_ERROR |
String | EVENT_RECORD_STARTED |
String | EVENT_RECORD_STOPPED |
String | EVENT_SIZE_CHANGED |
String | EVENT_STARTED |
String | EVENT_STOPPED |
String | EVENT_STOPPED_AT_TIME |
String | EVENT_VOLUME_CHANGED |
Number | duration |
Number | mediaTime |
Number | state |
Number | volumeLevel |
Constants
Number | TIME_UNKNOWN |
Number | CLOSED |
Number | UNREALIZED |
Number | REALIZED |
Number | PREFETCHED |
Constructors
blackberry.audio.Player
(locator : String, [type : String], [async : Boolean])
Media locators are specified in URI syntax which is defined in the form: '<scheme>:<scheme-specific-part>'. If scheme is 'local', media type should be specified.
Supported Platforms | |
---|---|
- BlackBerry OS 5.0+ | |
- Ripple Emulator |
Parameters | |
---|---|
locator | Media locator string in URI syntax that describes the media content. |
type | The ContentType of the media. |
async | The parameter specifying whether the player should asynchronously advance to PREFETCHED state. If not provided set to false. |
Code Example:
|
|
|
Functions
static
Boolean
blackberry.audio.Player.addPlayerListener
([onPlayerUpdate: function([player: blackberry.audio.Player], [event: String], [eventData: Object])])
Add a player listener for this player. All subsequent calls assigning a new onPlayerUpdate callback will override the previous callback assigned. To unsubscribe from the PlayerListener, pass null as an onPlayerUpdate parameter.
Supported Platforms | |
---|---|
- BlackBerry OS 5.0+ | |
- Ripple Emulator |
Parameters | |
---|---|
onPlayerUpdate |
This callback function is called to deliver an event to a registered listener when a Player event is observed.
player: The player which generated the event. event: The event generated as defined by the enumerated types. eventData: The associated event data. |
Return:
Returns true if the callback is successfully assigned
Code Example:
|
static
Boolean
blackberry.audio.Player.close
()
Closing the Player and releases most of its resources, it must not be used again.
Supported Platforms | |
---|---|
- BlackBerry OS 5.0+ | |
- Ripple Emulator |
Return:
Returns true if the player is successfully closed
static
Boolean
blackberry.audio.Player.pause
()
Pause the player's playback.
Supported Platforms | |
---|---|
- BlackBerry OS 5.0+ | |
- Ripple Emulator |
Return:
Returns true if the player is successfully paused
Code Example:
|
static
Boolean
blackberry.audio.Player.play
()
Starts playing the loaded content.
Supported Platforms | |
---|---|
- BlackBerry OS 5.0+ | |
- Ripple Emulator |
Return:
Returns true if the player successfully starts playing
Code Example:
|
Properties
static
readonly
String
EVENT_BUFFERING_STARTED
Posted when the Player enters into a buffering mode.
When this event is received, the eventdata parameter will be a number designating the media time when the buffering is started.
Supported Platforms | |
---|---|
- BlackBerry OS 5.0+ | |
- Ripple Emulator |
static
readonly
String
EVENT_BUFFERING_STOPPED
Posted when the Player leaves the buffering mode.
When this even is received, the eventData parameter will be a number designating the media time when the buffering stopped.
Supported Platforms | |
---|---|
- BlackBerry OS 5.0+ | |
- Ripple Emulator |
static
readonly
String
EVENT_CLOSED
Posted when a Player is closed.
When this event is received, the eventData parameter is null.
Supported Platforms | |
---|---|
- BlackBerry OS 5.0+ | |
- Ripple Emulator |
static
readonly
String
EVENT_DEVICE_AVAILABLE
Posted when the system or another higher priority application has released an exclusive device which is now available to the Player.
The eventData parameter is a string specifying the name of the device.
Supported Platforms | |
---|---|
- BlackBerry OS 5.0+ | |
- Ripple Emulator |
static
readonly
String
EVENT_DEVICE_UNAVAILABLE
Posted when the system or another higher priority application has temporarily taken control of an exclusive device which was previously available to the Player.
The eventData parameter is a string specifying the name of the device.
Supported Platforms | |
---|---|
- BlackBerry OS 5.0+ | |
- Ripple Emulator |
static
readonly
String
EVENT_DURATION_UPDATED
Posted when the duration of a Player is updated.
When this event is received, the eventData parameter will be a number designating the duration of the media.
Supported Platforms | |
---|---|
- BlackBerry OS 5.0+ | |
- Ripple Emulator |
static
readonly
String
EVENT_END_OF_MEDIA
Posted when a Player has reached the end of the media.
When this event is received, the eventData parameter will be a number designating the media time when the player reached end of media and stopped.
Supported Platforms | |
---|---|
- BlackBerry OS 5.0+ | |
- Ripple Emulator |
static
readonly
String
EVENT_ERROR
Posted when an error had occurred.
When this event is received, the eventData parameter will be a string object specifying the error message. Error code:
- Media player busy: the media player is currently performing an operation that precludes the requested operation.
- Invalid parameter: a parameter was specified with an invalid value.
- Insufficient memory: there is insufficient memory to perform the requested operation.
- Need more data: playback cannot proceed until the streaming source provides more data.
- Unspecified: some error occured which does not fit into any other category.
- Format: an error in the media file was detected.
- No server response: a server has stopped responding.
- Connetion lost: the current connection has been dropped.
- DNS resolve error: an invalid URL has been detected.
- Unseekable: the media player needs to seek in the file in order to access headers, but can't since the file being played is unseekable.
- Connection timeout: the (streaming) server is unreachable.
- No rights: The DRM agent wasn't able to find a valid digital right in the media. RTSP error 401 has occurred.
- General client error: The streaming server rejected the streaming request. RTSP error 4xx not covered by another error code has occurred.
- Server error: An error occured on the streaming server while streaming. RTSP error 5xx has occurred.
- Payment required: Payment is required to stream this item from the server. RTSP error 402 has occurred.
- Forbidden: The streaming server has rejected the streaming request for security reasons. RTSP error 403 has occurred.
- Client file not found: The item required to stream doesn't exist or has been removed from the server. RTSP error 404 has occurred.
- Client proxy authentication required: Device needs to authenticate with a proxy server before streaming. RTSP error 407 has occurred.
- Client request URI too large: The request URI sent to the server is too large. RTSP error 414 has occurred.
- Not enough bandwidth: There is not enough bandwidth to support streaming. RTSP error 453 has occurred.
- Client session not found: Streaming session has been removed by the server (e.g.: when paused for too long). RTSP error 454 has occurred.
- Unsupported transport: The streaming server/network doesn't support UDP/TCP streaming. RTSP error 461 has occurred.
- Switch cannot be completed: Try to do a fast content switch but failed. The server returned 4xx/5xx error.
Supported Platforms | |
---|---|
- BlackBerry OS 5.0+ | |
- Ripple Emulator |
static
readonly
String
EVENT_RECORD_ERROR
Posted when an error occurs during the recording.
When this event is received, the eventData parameter will be a string object specifying the error message.
Supported Platforms | |
---|---|
- BlackBerry OS 5.0+ | |
- Ripple Emulator |
static
readonly
String
EVENT_RECORD_STARTED
Posted when recording is started.
When this event is received, the eventData parameter will be a number designating the media time when the recording is started.
Supported Platforms | |
---|---|
- BlackBerry OS 5.0+ | |
- Ripple Emulator |
static
readonly
String
EVENT_RECORD_STOPPED
Posted when recording is stopped.
When this event is received, the eventData parameter will be a number designating the media time when the recording stopped.
Supported Platforms | |
---|---|
- BlackBerry OS 5.0+ | |
- Ripple Emulator |
static
readonly
String
EVENT_SIZE_CHANGED
Posted when the size of the video is changed either because the source video size or the display size is changed.
When this event is received, the eventdata parameter will be null.
Supported Platforms | |
---|---|
- BlackBerry OS 5.0+ | |
- Ripple Emulator |
static
readonly
String
EVENT_STARTED
Posted when a Player is started.
When this event is received, the eventData parameter will be a number designating the media time when the player is started.
Supported Platforms | |
---|---|
- BlackBerry OS 5.0+ | |
- Ripple Emulator |
static
readonly
String
EVENT_STOPPED
Posted when a Player stops in response to the stop method call.
When this event is received, the eventData parameter will be a number designating the media time when the player stopped.
Supported Platforms | |
---|---|
- BlackBerry OS 5.0+ | |
- Ripple Emulator |
static
readonly
String
EVENT_STOPPED_AT_TIME
Posted when a Player is stopped as responding to the setStopTime call using the StopTimeControl.
When this event is received, the eventData parameter will be a number designating the media time when the player is stopped.
Supported Platforms | |
---|---|
- BlackBerry OS 5.0+ | |
- Ripple Emulator |
static
readonly
String
EVENT_VOLUME_CHANGED
Posted when the volume of an audio device is changed.
When this event is received, the eventData parameter will be null.
Supported Platforms | |
---|---|
- BlackBerry OS 5.0+ | |
- Ripple Emulator |
static
readonly
Number
duration
The duration of the media in milliseconds.
Supported Platforms | |
---|---|
- BlackBerry OS 5.0+ | |
- Ripple Emulator |
static
Number
mediaTime
Get/Set Player's media time.
Supported Platforms | |
---|---|
- BlackBerry OS 5.0+ | |
- Ripple Emulator |
Constants
static
Number
TIME_UNKNOWN
= -1
The returned value indicating that the requested time is unknown.
Supported Platforms | |
---|---|
- BlackBerry OS 5.0+ | |
- Ripple Emulator |
static
Number
CLOSED
= 0
The state of the Player indicating that the Player is closed.
Supported Platforms | |
---|---|
- BlackBerry OS 5.0+ | |
- Ripple Emulator |
static
Number
UNREALIZED
= 100
The state of the Player indicating that it has not acquired the required information and resources to function.
Supported Platforms | |
---|---|
- BlackBerry OS 5.0+ | |
- Ripple Emulator |