Tag: multimedia

BlackBerry AMMS (Advanced Multimedia Supplement) API Support

The Advanced Multimedia Supplement (AMMS) API, also known as JSR-234, is used to access advanced camera features on the BlackBerry® platform.  As of BlackBerry® 6.0 none of the audio capabilities of AMMS has been implemented, with the exception of AudioFormatControl and VideoFormatControl which have been implemented only so far as to support their stated features for video and still image capture.  Conversely many of the camera capabilities have been implemented.

AMMS by definition allows implementers to implement only some of the API.  Specifically, only the relevant ‘parts’ to the destination platform need to be implemented, with each ‘part’ consisting of a set of classes to implement.  The guarantee AMMS makes however is that any part that is implemented must be fully implemented to the extent that the platform can support it.  This means that each class that must be implemented as a part will itself be only partially implemented enough to fulfill that part with what the device is capable of.  Still following?

To put it another way, within each class the level of implementation depends on what the device can actually do. When an AMMS class is implemented the BlackBerry platform will guarantee to support the invocation (meaning an application that attempts to call an unsupported feature will compile and, if properly written, will fail gracefully and not crash) but not necessarily the implementation.

This is why developers who have used the AMMS API classes have found that not every portion of a class is fully implemented.  For example, the CameraControl class is an implemented AMMS class on the BlackBerry platform.  If an application were to call its isShutterFeedbackEnabled() method, it would always return true since that feature is supported on all platforms (a ‘click’ sound is heard when a picture is taken).  However, if that same application called its enableShutterFeedback(boolean) method, a MediaException would be thrown with the message “Setting shutter feedback is not possible”. This is because although the feature is supported, the ability to toggle it is not – it is always on.

For most classes in the AMMS API there are built-in methods to query the level of support of that class, but this was not done consistently.  In some cases the AMMS JavaDoc™ will state the behaviour of the platform if the particular feature or method is not supported on the implementing platform.  For example, in the case of the MediaException mentioned in the example above, there is no method to query if toggling shutter feedback is supported but the documentation states that the method “throws javax.microedition.media.MediaException – if setting of the shutter feedback is not possible”.[1]

What’s Supported?

Once your application has created a player for still image capture or for video capture, the controls available depend largely on the context of the player.  For example a player for still image capture will not have an AudioFormatControl available, however a player for video capture will.  The following is a list of controls that are implemented for at least one player context:

javax.microedition.amms.control.camera.CameraControl

javax.microedition.amms.control.camera.FlashControl

javax.microedition.amms.control.camera.SnapshotControl

javax.microedition.amms.control.camera.ZoomControl

javax.microedition.amms.control.camera.FocusControl

net.rim.device.api.amms.control.camera.EnhancedFocusControl

javax.microedition.amms.control.AudioFormatControl

javax.microedition.amms.control.VideoFormatControl

javax.microedition.amms.control.ContainerFormatControl

Similarly, the following controls are not implemented at all on the BlackBerry platform:

javax.microedition.amms.EffectOrderControl

javax.microedition.amms.control.camera.ImageFormatControl

javax.microedition.amms.MIDIChannelControl

javax.microedition.amms.PanControl

javax.microedition.amms.PriorityControl

javax.microedition.amms.control.camera.ExposureControl

None of the controls in javax.microedition.amms.control.audio3d

None of the controls in javax.microedition.amms.control.audioeffect

None of the controls in javax.microedition.amms.control.tuner

None of the controls in javax.microedition.amms.control.imageeffect

Within each implemented class, there are varying levels of implemented methods, as previously explained.  The table below shows a list of which methods are implemented for each supported AMMS Control.

Class Method Implemented?
CameraControl enableShutterFeedback(boolean) NO
getCameraRotation() YES
getExposureMode() YES
getStillResolution() YES
getSupportedExposureModes() YES
getSupportedStillResolutions() YES
getSupportedVideoResolutions() NO
getVideoResolution() NO
isShutterFeedbackEnabled() YES
setExposureMode(String) YES
setStillResolution(int) YES
setVideoResolution(int) NO
FocusControl getFocus() YES
getFocusSteps() NO
getMacro() YES
getMinFocus() NO
isAutoFocusSupported() YES
isMacroSupported() YES
isManualFocusSupported() YES
setFocus(int) YES
setMacro(boolean) YES
EnhancedFocusControl getCurrentFocusMode() YES
isAutoFocusLocked() YES
isFocusModeSupported() YES
setFocusMode() YES
startAutoFocus() YES
stopAutoFocus() YES
FlashControl getMode() YES
getSupportedModes() YES
isFlashReady() YES
setMode(int) YES
ZoomControl getDigitalZoom() YES
getDigitalZoomLevels() YES
getMaxDigitalZoom() YES
getMaxOpticalZoom() NO
getMinFocalLength() NO
getOpticalZoom() NO
getOpticalZoomLevels() YES
setDigitalZoom(int) YES
setOpticalZoom(int) YES
SnapshotControl getDirectory() YES
getFilePrefix() YES
getFileSuffix() YES
setDirectory(String) YES
setFilePrefix(String) YES
setFileSuffix(String) YES
start(int) YES
stop() YES
unfreeze(boolean) YES
AudioFormatControl getEstimatedBitRate() NO
getFormat() YES
getIntParameterValue(String) NO
getMetadataOverride() YES
getMetadataSupportMode() YES
getStrParameterValue(String) YES
getSupportedFormats() YES
getSupportedIntParameterRange(String) NO
getSupportedIntParameters() YES
getSupportedMetadataKeys() YES
getSupportedStrParameters() YES
getSupportedStrParameterValues(String) YES
setFormat(String) YES
setMetadata(String, String) NO
setMetadataOverride(boolean) NO
setParameter(String, int) NO
setParameter(String, String) YES
VideoFormatControl getEstimatedBitRate() NO
getFormat() YES
getIntParameterValue(String) YES
getMetadataOverride() YES
getMetadataSupportMode() YES
getStrParameterValue(String) YES
getSupportedFormats() YES
getSupportedIntParameterRange(String) YES
getSupportedIntParameters() YES
getSupportedMetadataKeys() YES
getSupportedStrParameters() YES
getSupportedStrParameterValues(String) YES
setFormat(String) YES
setMetadata(String, String) NO
setMetadataOverride(boolean) NO
setParameter(String, int) YES
setParameter(String, String) YES
ContainerFormatControl getEstimatedBitRate() NO
getFormat() YES
getIntParameterValue(String) NO
getMetadataOverride() YES
getMetadataSupportMode() YES
getStrParameterValue(String) YES
getSupportedFormats() YES
getSupportedIntParameterRange(String) NO
getSupportedIntParameters() NO
getSupportedMetadataKeys() NO
getSupportedStrParameters() YES
getSupportedStrParameterValues(String) YES
setFormat(String) NO
setMetadata(String, String) NO
setMetadataOverride(boolean) NO
setParameter(String, int) YES
setParameter(String, String) NO





[1] http://supportforums.blackberry.com/t5/Java-Development/Advanced-Multimedia-Supplement-API-What-s-Supported/ta-p/770659
[2] http://jcp.org/aboutJava/communityprocess/mrel/jsr234/index.html


Streaming Multimedia on BlackBerry

Summary

 

This article applies to the following:

  • BlackBerry® Device Software 4.2.1 and later

 

Details

 

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.

Basic Streaming Media

There are two methods that can be used to stream media.

 

Streaming media over RTSP

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.

 

  • Using the browser (starts the Media application on the BlackBerry smartphone)String url = "rtsp://mystreamingserver.com/001.aac";Browser.getDefaultSession().displayPage(url);
  • Using the Mobile Media API that is specified in JSR 135 (plays within an application)String url = "rtsp://mystreamingserver.com/001.aac";Player player = Manager.createPlayer(url);player.start();

Streaming media over HTTP

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.

 

  • Using the browser (starts the Media application on the BlackBerry smartphone)
    • String url = "http://mystreamingserver.com/001.mp3";
    • Browser.getDefaultSession().displayPage(url);
  • Using the Mobile Media API that is specified in JSR 135 (plays within an application)
    • String url = "http://mystreamingserver.com/001.mp3";
    • Player player = Manager.createPlayer(url);player.start();

Advantages of streaming media over HTTP

  • API calls are simple to use.
  • This method hides many complex details.

Limitations of streaming media over HTTP

  • Raw data in the buffer cannot be accessed.
  • The data flow from the buffer to the media player cannot be controlled.
  • There is no seek() support prior to BlackBerry Device Software 5.0.
  • There is no access to the raw data stream.

Advanced streaming media

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 javax.microedition.media package.

Components of advanced streaming media

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.

 

1828i24A9F271819BF829

Source Media

The media file that is located on a content server.

 

Download Thread

A thread that connects to the source media and downloads the media file to the media buffer.

Media Buffer

A circular byte buffer for storing downloaded data until it is sent to media player for playback.

SourceStream

An instance of the javax.microedition.media.protocol.SourceStream class. The SourceStream acts as an input stream for the media player by providing methods such as read() and seek().

DataSource

An instance of the javax.microedition.media.protocol.DataSource. DataSource class, and performs the following procedure:

  1. Open a connection to the remote source media.
  2. Start the download thread.
  3. Initialize and return SourceStream objects to play.
  4. Close the connection.

Player

An instance of javax.microedition.media.Player. The Player object plays media content as the content is downloaded. You can initialize a Playerobject by invoking

javax.microedition.media.Manager.createPlayer(DataSource source).

 

Implementation

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.

Implementing the DataSource

DataSource is an abstract class and has six methods. Each of the following methods is invoked by the Player object:

 

public void connect()

  • Opens connections and input/output (I/O) streams

public void disconnect()

  • Closes connections, I/O streams, and so on

public String getContentType()

  • Returns the content type of the source media

public SourceStream[] getStreams()

  • Returns SourceStream objects

public void start()

  • Starts the download thread and begins downloading data

public void stop()

  • Stops downloading data

Implementing the SourceStream

public ContentDescriptor getContentDescriptor()

  • Returns a ContentDescriptor object based on the content type of the media

public long getContentLength()

  • Returns the content length.

public int getSeekType()

  • Returns RANDOM_ACCESSIBLE
    • Allows the Player to seek to nearby locations from the current position. SourceStream RANDOM_ACCESSIBLE must 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)

  • Sends data to the Player.
  • Blocks or resumes the feed,depending on the status of the buffer

public long seek(long where)

  • Called by the Player to seek to a point between 0 and the content length
  • Implementation varies based the following connection types:
  • HTTP streaming
    • Uses this method only if seek() is feasible.
    • seek() point is within the buffered data. Otherwise, return the current position.
  • FileConnection streaming
    • Uses this method with mark()reset() and skip()

public long tell()

  • Returns the current position in the stream

How to handle user-initiated seek()

There are two types of user-initiated seek calls. In both cases, Player.setMediaTime(long microseconds) must be invoked, which in turn invokesSourceStream.seek(long position).

  • Seek calls within available data
    • Invoke seek() within the buffer using mark()reset() or skip()
      1829iDBC451CCF5CA4D3D
  • Seek calls beyond the data that is available
    • Block the feed to the Player.
    • Stop downloading data.
    • Close the HTTP connection.
    • Reopen the connection using the HTTP range header to get data from the seek position.
    • Start downloading using the new connection.
    • Resume the feed to the Player when buffer contains enough information.
    1830i3391D28D515A6667

Stream control

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

  1. initialBufferDetermines how much data to buffer before playback starts for the first time. This variable can be determined dynamically by the following criteria:
    • Connection type
    • Bit rate
    • Bandwidth and latency
  2. restartThresholdDetermines 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:
    • Connection type
    • Bit rate
    • Bandwidth and latency
  3. bufferCapacityDetermines the size of the buffer where data is stored. This variable can be determined dynamically by the following criteria:
    • Connection type
    • Bit rate
    • Bandwidth and latency
    • If a buffer is too small, it can frequently run out of space.
    • If a buffer too big, it can waste system resources.
  4. bufferLeakSizeVideo 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.

Creating a Player from a DataSource

To create a Player from a DataSource, use the following code:

Player player = Manager.createPlayer(new MyDataSource());player.start();

 

Using the right transport method

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.

Downloads

A complete implementation of a streaming media application is available to download. This example application uses the StreamingPlayer class andStreamingPlayerListener 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 complile the project. For an example, click here.

 

1831i1650ADCE11412CDA
 

Refer to attachment section below to download the example application, including the libraries.

 

 

[1] http://supportforums.blackberry.com/t5/Java-Development/Streaming-media-Start-to-finish/ta-p/488255

streamingplayersampleapp__download_pdf_renameto_zip


  • Copyright © 1996-2010 vaks.in. All rights reserved.
    iDream theme by Templates Next | Powered by WordPress