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
View Supported Platform Table
APIBB5.0BB6.0BB7.0PB1.0PB2.0BB10Ripple
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 IDBB5.0BB6.0BB7.0PB1.0PB2.0BB10Ripple
<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.




Constants

Number TIME_UNKNOWN
Number CLOSED
Number UNREALIZED
Number REALIZED
Number PREFETCHED

Constructors

blackberry.audio.Player (locator : String, [type : String], [async : Boolean])

Audio Player object for BlackBerry 5.0 smartphones that do not support the HTML5 <audio> element

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:
<script type="text/javascript">

  function createPlayerFromMediaFileStoredInLocal() {
    var playerInstance = new  blackberry.audio.Player("local:///res/filename.mid", "audio/mid", true);
  }

  function createPlayerFromMediaFileStoresInSystem() {
    var playerInstance = new  blackberry.audio.Player("file:///store/home/user/music/filename.mid");
  }
</script>
<script type="text/javascript">
  // Display some player static and non-static constants.
  var playerInstance = new  blackberry.audio.Player("file:///store/home/user/music/filename.mid");
  var res = blackberry.audio.Player.UNREALIZED;
  alert("The value of UNREALIZED static constant is: " + res);
  res = playerInstance.EVENT_DURATION_UPDATED;
  alert("The value of EVENT_DURATION_UPDATED non-static constant is: " + res);
</script>
<script type="text/javascript">
  var playerInstance = new  blackberry.audio.Player("file:///store/home/user/music/filename.mp3");

  // Setting new time for media
  playerInstance.mediaTime = 10000;
  alert("New media time: " + playerInstance.mediaTime);

  // Setting new volume for media
  playerInstance.volumeLevel = 85;
  alert("New volume level: " + playerInstance.volumeLevel);    
</script>

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:
<script type="text/javascript">
  // Subscribing and unsubscribing with player's events
  var playerInstance = new  blackberry.audio.Player("file:///store/home/user/music/filename.mp3");    
  playerInstance.addPlayerListener(OnPlayerUpdate);

  // Invoked when there is an update event for the player.
  function OnPlayerUpdate(player, event, eventData) {
    try {
      alert("Player's duration is: " + player.duration)
    } catch (e) {}
    try {
      alert("Event: " + event);
    } catch (e) {}
    try {
      alert("Event Data:  " + eventData);
    } catch (e) {}

    playerInstance.addPlayerListener(null);
  }
</script>

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:
<script type="text/javascript">
  // Pausing the player and then closing it
  var playerInstance = new  blackberry.audio.Player("file:///store/home/user/music/filename.mp3");    
  playerInstance.pause();
  playerInstance.close();
</script>

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:
<script type="text/javascript">
  // Playing the player
  var playerInstance = new  blackberry.audio.Player("file:///store/home/user/music/filename.mp3");    
  playerInstance.play();
</script>

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:

  1. Media player busy: the media player is currently performing an operation that precludes the requested operation.
  2. Invalid parameter: a parameter was specified with an invalid value.
  3. Insufficient memory: there is insufficient memory to perform the requested operation.
  4. Need more data: playback cannot proceed until the streaming source provides more data.
  5. Unspecified: some error occured which does not fit into any other category.
  6. Format: an error in the media file was detected.
  7. No server response: a server has stopped responding.
  8. Connetion lost: the current connection has been dropped.
  9. DNS resolve error: an invalid URL has been detected.
  10. 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.
  11. Connection timeout: the (streaming) server is unreachable.
  12. No rights: The DRM agent wasn't able to find a valid digital right in the media. RTSP error 401 has occurred.
  13. General client error: The streaming server rejected the streaming request. RTSP error 4xx not covered by another error code has occurred.
  14. Server error: An error occured on the streaming server while streaming. RTSP error 5xx has occurred.
  15. Payment required: Payment is required to stream this item from the server. RTSP error 402 has occurred.
  16. Forbidden: The streaming server has rejected the streaming request for security reasons. RTSP error 403 has occurred.
  17. Client file not found: The item required to stream doesn't exist or has been removed from the server. RTSP error 404 has occurred.
  18. Client proxy authentication required: Device needs to authenticate with a proxy server before streaming. RTSP error 407 has occurred.
  19. Client request URI too large: The request URI sent to the server is too large. RTSP error 414 has occurred.
  20. Not enough bandwidth: There is not enough bandwidth to support streaming. RTSP error 453 has occurred.
  21. Client session not found: Streaming session has been removed by the server (e.g.: when paused for too long). RTSP error 454 has occurred.
  22. Unsupported transport: The streaming server/network doesn't support UDP/TCP streaming. RTSP error 461 has occurred.
  1. 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

static readonly Number state


The current state of this Player (one of Enumerated Player's constants).


Supported Platforms
 - BlackBerry OS 5.0+
 - Ripple Emulator

static Number volumeLevel


Get/Set the player's volume level. Valid values are between 0 and 100.


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

static Number REALIZED = 200


The state of the Player indicating that it has acquired the required information but not the resources to function.


Supported Platforms
 - BlackBerry OS 5.0+
 - Ripple Emulator

static Number PREFETCHED = 300


The state of the Player indicating that it has acquired all the resources to begin playing.


Supported Platforms
 - BlackBerry OS 5.0+
 - Ripple Emulator

Documentation generated by JsDoc Toolkit 2.4.0 on Sun Dec 30 2012 18:15:42 GMT-0500 (EST)