This article applies to the following:
- BlackBerry® Device Software 4.2.1 and later
This article describes how to create a solid streaming media application and how to use the
StreamingPlayer class, which is an open-source application programming interface (API) containing classes and methods that support streaming media.
There are two methods that can be used to stream media.
Real Time Streaming Protocol (RTSP) was first implemented in BlackBerry Device Software 4.3 for BlackBerry smartphones that operate on Code Division Multiple Access (CDMA) networks. RTSP is now supported by all BlackBerry smartphones running BlackBerry Device Software 4.5 and later. There are two ways to stream media content over RTSP.
String url = "rtsp://mystreamingserver.com/001.aac";Browser.get
String url = "rtsp://mystreamingserver.com/001.aac";Player player = Manager.createPlayer(url);player.start();
Hypertext Transfer Protocol (HTTP) is a protocol that can stream media content and provide real-time playback. Like RTSP, there are two ways to stream media content over HTTP.
String url = "http://mystreamingserver.com/001.mp3";
String url = "http://mystreamingserver.com/001.mp3";
Player player = Manager.createPlayer(url);player.start();
seek()support prior to BlackBerry Device Software 5.0.
The Mobile Media API (JSR 135) defines advanced APIs that you can use to control media streaming and allow flexibility in development. These APIs can be found in the
The following diagram illustrates the different components and classes that are involved in streaming media and the data flow between a remote media source and the media player.
The media file that is located on a content server.
A thread that connects to the source media and downloads the media file to the media buffer.
A circular byte buffer for storing downloaded data until it is sent to media player for playback.
An instance of the
class. The SourceStream acts as an input stream for the media player by providing methods such as
An instance of the
javax.microedition.media.protocol.DataSource. DataSource class, and performs the following procedure:
SourceStreamobjects to play.
An instance of
Player object plays media content as the content is downloaded. You can initialize a
Player object by invoking
The code sample that is included this article shows a complete implementation of all the components and classes that are mentioned. The code sample also includes a
StreamingPlayer class and a
StreamingPlayerListener interface that you can use as an API or extend to meet special use cases.
DataSource is an abstract class and has six methods. Each of the following methods is invoked by the
public void connect()
public void disconnect()
public String getContentType()
public SourceStream getStreams()
public void start()
public void stop()
public ContentDescriptor getContentDescriptor()
ContentDescriptorobject based on the content type of the media
public long getContentLength()
public int getSeekType()
Playerto seek to nearby locations from the current position.
SourceStream RANDOM_ACCESSIBLEmust be set because video files can have audio and video at different offsets for each frame and the BlackBerry Device Software requires both for smooth playback. If -1 is returned by
getContentLength(), the seek calls will only be to a previous position in the media file.
public int read(byte b, int off, int len)
public long seek(long where)
Playerto seek to a point between 0 and the content length
seek()point is within the buffered data. Otherwise, return the current position.
public long tell()
There are two types of user-initiated seek calls. In both cases,
Player.setMediaTime(long microseconds) must be invoked, which in turn invokes
seek() within the buffer using
Playerwhen buffer contains enough information.
Because media is streaming over a wireless network, there must be a mechanism to stop data feed to the
Player when the buffer runs out of space due to of network delay. There must also be a way to determine how much of the buffer should be filled before restarting or resuming playback. Downloaded data in the buffer must be held as long as possible to allow for backward seek calls made by the
Player, but when buffer is full the data must be discarded to download more data. You can use the following variables to control the feed to the
Determines how much data to buffer before playback starts for the first time. This variable can be determined dynamically by the following criteria:
Determines when to resume the data feed to the
Player based on the data that is available in the buffer. This variable can be determined dynamically by the following criteria:
Determines the size of the buffer where data is stored. This variable can be determined dynamically by the following criteria:
Video playback requires the
Player to seek back from the current position because audio and video data for the same frame are at different offsets. To accommodate this situation, downloaded data is stored until the
Player is at the end of the buffer and the buffer is full. This method requires that more data must be downloaded for the playback to continue. In this situation, the oldest data is discarded first to create space for downloading more data.
bufferLeakSize determines how much data is discarded each time this occurs.
To create a
Player from a
DataSource, use the following code:
Player player = Manager.createPlayer(new MyDataSource());player.start();
Wi-Fi® technology is the preferred transport because it is fast and free. If a Wi-Fi connection becomes available during a streaming session, it is recommended that the
Player dynamically switch to the Wi-Fi connection after prompting the BlackBerry smartphone user to do so. If a Wi-Fi connection is not available, transport methods that are used by wireless service providers, such as Wireless Application Protocol (WAP/WAP2) or Transmission Control Protocol (TCP), are recommended. Using the BlackBerry® Mobile Data System (BlackBerry MDS) or the BlackBerry® Internet Service is not recommended because media streaming results in large data usage through these transport methods. Both the BlackBerry MDS and BlackBerry Internet Service also result in added latency because the data travels through the BlackBerry® Infrastructure.
A complete implementation of a streaming media application is available to download. This example application uses the
StreamingPlayer class and
StreamingPlayerListener class as libraries, and can be used in your application to stream media over HTTP. This application will only play the media files that are supported by the target BlackBerry smartphone. Make sure that you type the web page and content type of your media file on the Options screen of the application before pressing play.
Note: The API needs an implementation of a thread safe Circular Byte Buffer. You can copy the implementation as CircularByteBuffer.java to rimx.media.streaming package and then compile the project. For an example, click here.
Refer to attachment section below to download the example application, including the libraries.