Audio Player

- BlackBerry OS 5.0+
- Ripple Emulator

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

blackberry.audio.Player

---

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

Supported Platform(s)

 - BlackBerry OS 5.0+
 - Ripple Emulator

Description

Parameter	Type	Description
locator	String	Media locator string in URI syntax that describes the media content.
type	String Optional	The ContentType of the media.
async	Boolean Optional	The parameter specifying whether the player should asynchronously advance to PREFETCHED state. If not provided set to false.

Code Example(s)

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

addPlayerListener

---

static Boolean addPlayerListener([onPlayerUpdate: function])

Supported Platform(s)

 - BlackBerry OS 5.0+
 - Ripple Emulator

Description

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.

Returns

Returns true if the callback is successfully assigned

Parameter	Type	Description
onPlayerUpdate	function([player: blackberry.audio.Player], [event: String], [eventData: Object]) Optional	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.

Code Example(s)

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

close

---

static Boolean close()

Supported Platform(s)

 - BlackBerry OS 5.0+
 - Ripple Emulator

Description

Closing the Player and releases most of its resources, it must not be used again.

Returns

Returns true if the player is successfully closed

pause

---

static Boolean pause()

Supported Platform(s)

 - BlackBerry OS 5.0+
 - Ripple Emulator

Description

Pause the player's playback.

Returns

Returns true if the player is successfully paused

Code Example(s)

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

play

---

static Boolean play()

Supported Platform(s)

 - BlackBerry OS 5.0+
 - Ripple Emulator

Description

Starts playing the loaded content.

Returns

Returns true if the player successfully starts playing

Code Example(s)

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

Properties:

---

Property	Type	Description	Supported Platform(s)
EVENT_BUFFERING_STARTED	Static String readonly	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.	- BlackBerry OS 5.0+  - Ripple Emulator
EVENT_BUFFERING_STOPPED	Static String readonly	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.	- BlackBerry OS 5.0+  - Ripple Emulator
EVENT_CLOSED	Static String readonly	Posted when a Player is closed. When this event is received, the eventData parameter is null.	- BlackBerry OS 5.0+  - Ripple Emulator
EVENT_DEVICE_AVAILABLE	Static String readonly	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.	- BlackBerry OS 5.0+  - Ripple Emulator
EVENT_DEVICE_UNAVAILABLE	Static String readonly	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.	- BlackBerry OS 5.0+  - Ripple Emulator
EVENT_DURATION_UPDATED	Static String readonly	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.	- BlackBerry OS 5.0+  - Ripple Emulator
EVENT_END_OF_MEDIA	Static String readonly	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.	- BlackBerry OS 5.0+  - Ripple Emulator
EVENT_ERROR	Static String readonly	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.	- BlackBerry OS 5.0+  - Ripple Emulator
EVENT_RECORD_ERROR	Static String readonly	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.	- BlackBerry OS 5.0+  - Ripple Emulator
EVENT_RECORD_STARTED	Static String readonly	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.	- BlackBerry OS 5.0+  - Ripple Emulator
EVENT_RECORD_STOPPED	Static String readonly	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.	- BlackBerry OS 5.0+  - Ripple Emulator
EVENT_SIZE_CHANGED	Static String readonly	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.	- BlackBerry OS 5.0+  - Ripple Emulator
EVENT_STARTED	Static String readonly	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.	- BlackBerry OS 5.0+  - Ripple Emulator
EVENT_STOPPED	Static String readonly	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.	- BlackBerry OS 5.0+  - Ripple Emulator
EVENT_STOPPED_AT_TIME	Static String readonly	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.	- BlackBerry OS 5.0+  - Ripple Emulator
EVENT_VOLUME_CHANGED	Static String readonly	Posted when the volume of an audio device is changed. When this event is received, the eventData parameter will be null.	- BlackBerry OS 5.0+  - Ripple Emulator
duration	Static Number readonly	The duration of the media in milliseconds.	- BlackBerry OS 5.0+  - Ripple Emulator
mediaTime	Static Number	Get/Set Player's media time.	- BlackBerry OS 5.0+  - Ripple Emulator
state	Static Number readonly	The current state of this Player (one of Enumerated Player's constants).	- BlackBerry OS 5.0+  - Ripple Emulator
volumeLevel	Static Number	Get/Set the player's volume level. Valid values are between 0 and 100.	- BlackBerry OS 5.0+  - Ripple Emulator

Constants:

---

Property	Type	Description	Supported Platform(s)
TIME_UNKNOWN default: -1	Number	The returned value indicating that the requested time is unknown.	- BlackBerry OS 5.0+  - Ripple Emulator
CLOSED default: 0	Number	The state of the Player indicating that the Player is closed.	- BlackBerry OS 5.0+  - Ripple Emulator
UNREALIZED default: 100	Number	The state of the Player indicating that it has not acquired the required information and resources to function.	- BlackBerry OS 5.0+  - Ripple Emulator
REALIZED default: 200	Number	The state of the Player indicating that it has acquired the required information but not the resources to function.	- BlackBerry OS 5.0+  - Ripple Emulator
PREFETCHED default: 300	Number	The state of the Player indicating that it has acquired all the resources to begin playing.	- BlackBerry OS 5.0+  - Ripple Emulator

Documentation generated by JsDoc Toolkit 2.4.0 on Sun Dec 30 2012 13:31:19 GMT-0500 (EST)